Add support to column values with various unicode encodings.

Support for char16_t, u16string & u16string_view.
Support for char8_t, u8string & u8string_view.
Support for wchar_t, wstring & wstring_view (on 2-byte platforms).

Author: dougnazar

include/SQLiteCpp/Column.h

@@ -102,6 +102,49 @@ class Column
      */
     std::string getString() const;
 
+#ifdef __cpp_unicode_characters
+    /**
+     * @brief Return a pointer to the text value (NULL terminated UTF-16 string) of the column.
+     *
+     * @warning The value pointed at is only valid while the statement is valid (ie. not finalized),
+     *          thus you must copy it before using it beyond its scope (to a std::u16string for instance).
+     */
+    const char16_t* getU16Text(const char16_t* apDefaultValue = u"") const noexcept;
+    /**
+     * @brief Return a std::u16string for a TEXT column.
+     *
+     * Note this correctly handles strings that contain null bytes.
+     */
+    std::u16string getU16String() const;
+#if WCHAR_MAX == 0xffff
+    /**
+     * @brief Return a pointer to the text value (NULL terminated UTF-16 string) of the column.
+     *
+     * @warning The value pointed at is only valid while the statement is valid (ie. not finalized),
+     *          thus you must copy it before using it beyond its scope (to a std::wstring for instance).
+     */
+    const wchar_t* getWText(const wchar_t* apDefaultValue = L"") const noexcept;
+    /**
+     * @brief Return a std::wstring for a TEXT column.
+     */
+    std::wstring getWString() const;
+#endif  // WCHAR_MAX == 0xffff
+#endif  // __cpp_unicode_characters
+#ifdef __cpp_char8_t
+    /**
+     * @brief Return a pointer to the text value (NULL terminated UTF-8 string) of the column.
+     *
+     * @warning The value pointed at is only valid while the statement is valid (ie. not finalized),
+     *          thus you must copy it before using it beyond its scope (to a std::u8string for instance).
+     */
+    const char8_t* getU8Text(const char8_t* apDefaultValue = u8"") const noexcept;
+    /**
+     * @brief Return a std::u8string for a TEXT or BLOB column.
+     *
+     * Note this correctly handles strings that contain null bytes.
+     */
+    std::u8string getU8String() const;
+#endif  // __cpp_char8_t
     /**
      * @brief Return the type of the value of the column using sqlite3_column_type()
      *
@@ -142,7 +185,10 @@ class Column
     }
 
     /**
-     * @brief Return the number of bytes used by the text (or blob) value of the column
+     * @brief Return the number of bytes used by the UTF-8 text (or blob) value of the column
+     *
+     *  Can cause conversion to text and between UTF-8/UTF-16 encodings
+     *  Be careful when using with getBytes16() and UTF-16 functions
      *
      * Return either :
      * - size in bytes (not in characters) of the string returned by getText() without the '\0' terminator
@@ -152,6 +198,19 @@ class Column
      */
     int getBytes() const noexcept;
 
+    /**
+     * @brief Return the number of bytes used by the UTF-16 text value of the column
+     *
+     *  Can cause conversion to text and between UTF-8/UTF-16 encodings
+     *  Be careful when using with getBytes() and UTF-8 functions
+     *
+     * Return either :
+     * - size in bytes (not in characters) of the string returned by getText() without the '\0' terminator
+     * - size in bytes of the string representation of the numerical value (integer or double)
+     * - 0 for a NULL value
+     */
+    int getBytes16() const noexcept;
+
     /// Alias returning the number of bytes used by the text (or blob) value of the column
     int size() const noexcept
     {
@@ -226,6 +285,73 @@ class Column
         return getString();
     }
 
+#ifdef __cpp_unicode_characters
+    /**
+     * @brief Inline cast operator to char16_t*
+     *
+     * @see getU16String
+     */
+    operator const char16_t* () const
+    {
+        return getU16Text();
+    }
+    /**
+     * @brief Inline cast operator to std::u16string
+     *
+     * Handles UTF-16 TEXT
+     *
+     * @see getU16String
+     */
+    operator std::u16string() const
+    {
+        return getU16String();
+    }
+#if WCHAR_MAX == 0xffff
+    /**
+     * @brief Inline cast operator to wchar_t*
+     *
+     * @see getWText
+     */
+    operator const wchar_t* () const
+    {
+        return getWText();
+    }
+    /**
+     * @brief Inline cast operator to std::wstring
+     *
+     * Handles UTF-16 TEXT
+     *
+     * @see getWString
+     */
+    operator std::wstring() const
+    {
+        return getWString();
+    }
+#endif  // WCHAR_MAX == 0xffff
+#endif  // __cpp_unicode_characters
+#ifdef __cpp_char8_t
+    /**
+     * @brief Inline cast operator to char8_t*
+     *
+     * @see getU8Text
+     */
+    operator const char8_t* () const
+    {
+        return getU8Text();
+    }
+    /**
+     * @brief Inline cast operator to std::u8string
+     *
+     * Handles BLOB or TEXT, which may contain null bytes within
+     *
+     * @see getU8String
+     */
+    operator std::u8string() const
+    {
+        return getU8String();
+    }
+#endif  // __cpp_char8_t
+
 private:
     Statement::TStatementPtr    mStmtPtr;  ///< Shared Pointer to the prepared SQLite Statement Object
     int                         mIndex;    ///< Index of the column in the row of result, starting at 0

src/Column.cpp

@@ -102,18 +102,69 @@ std::string Column::getString() const
     return std::string(data, sqlite3_column_bytes(mStmtPtr.get(), mIndex));
 }
 
+#ifdef __cpp_unicode_characters
+const char16_t* Column::getU16Text(const char16_t* apDefaultValue /* = u"" */) const noexcept
+{
+    auto pText = static_cast<const char16_t*>(sqlite3_column_text16(mStmtPtr.get(), mIndex));
+    return (pText ? pText : apDefaultValue);
+}
+std::u16string Column::getU16String() const
+{
+    (void)sqlite3_column_bytes16(mStmtPtr.get(), mIndex);
+    auto data = static_cast<const char16_t*>(sqlite3_column_blob(mStmtPtr.get(), mIndex));
+    return std::u16string(data, sqlite3_column_bytes16(mStmtPtr.get(), mIndex) / sizeof(char16_t));
+}
+#if WCHAR_MAX == 0xffff
+const wchar_t* Column::getWText(const wchar_t* apDefaultValue /* = L"" */) const noexcept
+{
+    auto pText = static_cast<const wchar_t*>(sqlite3_column_text16(mStmtPtr.get(), mIndex));
+    return (pText ? pText : apDefaultValue);
+}
+std::wstring Column::getWString() const
+{
+    (void)sqlite3_column_bytes16(mStmtPtr.get(), mIndex);
+    auto data = static_cast<const wchar_t*>(sqlite3_column_blob(mStmtPtr.get(), mIndex));
+    return std::wstring(data, sqlite3_column_bytes16(mStmtPtr.get(), mIndex) / sizeof(wchar_t));
+}
+#endif  // WCHAR_MAX == 0xffff
+#endif  // __cpp_unicode_characters
+#ifdef __cpp_char8_t
+const char8_t* Column::getU8Text(const char8_t* apDefaultValue /* = u8"" */) const noexcept
+{
+    auto pText = reinterpret_cast<const char8_t*>(sqlite3_column_text(mStmtPtr.get(), mIndex));
+    return (pText ? pText : apDefaultValue);
+}
+std::u8string Column::getU8String() const
+{
+    (void)sqlite3_column_bytes(mStmtPtr.get(), mIndex);
+    auto data = static_cast<const char8_t*>(sqlite3_column_blob(mStmtPtr.get(), mIndex));
+    return std::u8string(data, sqlite3_column_bytes(mStmtPtr.get(), mIndex));
+}
+#endif  // __cpp_char8_t
+
+
 // Return the type of the value of the column
 int Column::getType() const noexcept
 {
     return sqlite3_column_type(mStmtPtr.get(), mIndex);
 }
 
-// Return the number of bytes used by the text value of the column
+// Return the number of bytes used by the UTF-8 text value of the column
+// Can cause conversion to text and between UTF-8/UTF-16 encodings
+// Be careful when using with getBytes16() and UTF-16 functions
 int Column::getBytes() const noexcept
 {
     return sqlite3_column_bytes(mStmtPtr.get(), mIndex);
 }
 
+// Return the number of bytes used by the UTF-16 text value of the column
+// Can cause conversion to text and between UTF-8/UTF-16 encodings
+// Be careful when using with getBytes() and UTF-8 functions
+int Column::getBytes16() const noexcept
+{
+    return sqlite3_column_bytes16(mStmtPtr.get(), mIndex);
+}
+
 // Standard std::ostream inserter
 std::ostream& operator<<(std::ostream& aStream, const Column& aColumn)
 {

tests/Column_test.cpp

@@ -197,6 +197,59 @@ static void test_column_basis(bool utf16)
         const SQLite::Column dbl = query.getColumn(3);
         EXPECT_EQ(0.123, dbl.getDouble());
     }
+
+#ifdef __cpp_unicode_characters
+    query.reset();
+    query.executeStep();
+
+    {
+        const auto first_u16 = u"first";
+
+        const std::u16string    str16 = query.getColumn(1);
+        const char16_t *        txt16 = query.getColumn(1);
+
+        EXPECT_EQ(5, str16.length());
+        EXPECT_EQ(10, query.getColumn(1).getBytes16());
+        EXPECT_EQ(0, memcmp(first_u16, str16.data(), str16.length() * sizeof(char16_t)));
+        EXPECT_EQ(5, std::char_traits<char16_t>::length(txt16));
+        EXPECT_EQ(0, std::char_traits<char16_t>::compare(first_u16, txt16, 6));
+    }
+
+#if WCHAR_MAX == 0xffff
+    query.reset();
+    query.executeStep();
+
+    {
+        const auto first_w = L"first";
+
+        const std::wstring      wstr = query.getColumn(1);
+        const wchar_t*          wtxt = query.getColumn(1);
+
+        EXPECT_EQ(5, wstr.length());
+        EXPECT_EQ(0, memcmp(first_w, wstr.data(), wstr.length() * sizeof(wchar_t)));
+        EXPECT_EQ(5, std::char_traits<wchar_t>::length(wtxt));
+        EXPECT_EQ(0, std::char_traits<wchar_t>::compare(first_w, wtxt, 6));
+    }
+#endif  // WCHAR_MAX == 0xffff
+
+#endif  // __cpp_unicode_characters
+
+#ifdef __cpp_char8_t
+    query.reset();
+    query.executeStep();
+
+    {
+        const auto first_u8 = u8"first";
+
+        const std::u8string     str8 = query.getColumn(1);
+        const char8_t*          txt8 = query.getColumn(1);
+
+        EXPECT_EQ(5, str8.length());
+        EXPECT_EQ(0, memcmp(first_u8, str8.data(), str8.length() * sizeof(char8_t)));
+        EXPECT_EQ(5, std::char_traits<char8_t>::length(txt8));
+        EXPECT_EQ(0, std::char_traits<char8_t>::compare(first_u8, txt8, 6));
+    }
+#endif  // __cpp_char8_t
 }
 
 TEST(Column, basis)