Compile time checks for size of UTF-16 code units

Use ARCH_INDEPENDENT with write_basic_package_version_file

.circleci/config.yml

@@ -1,13 +0,0 @@
-version: 2
-
-jobs:
-  build:
-    docker:
-      - image: nemtrif/utf8cpp:3.1.3
-    steps:
-      - checkout
-      - run: git submodule update --init --recursive --remote
-      - run: mkdir build
-      - run: cd build && cmake ..
-      - run: cd build && cmake --build .
-      - run: cd build && ctest -VV

.github/workflows/cmake-multi-platform.yml

@@ -0,0 +1,75 @@
+# This starter workflow is for a CMake project running on multiple platforms. There is a different starter workflow if you just want a single platform.
+# See: https://github.com/actions/starter-workflows/blob/main/ci/cmake-single-platform.yml
+name: CMake on multiple platforms
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      # Set fail-fast to false to ensure that feedback is delivered for all matrix combinations. Consider changing this to true when your workflow is stable.
+      fail-fast: false
+
+      # Set up a matrix to run the following 3 configurations:
+      # 1. <Windows, Release, latest MSVC compiler toolchain on the default runner image, default generator>
+      # 2. <Linux, Release, latest GCC compiler toolchain on the default runner image, default generator>
+      # 3. <Linux, Release, latest Clang compiler toolchain on the default runner image, default generator>
+      #
+      # To add more build types (Release, Debug, RelWithDebInfo, etc.) customize the build_type list.
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        build_type: [Release]
+        c_compiler: [gcc, clang, cl]
+        include:
+          - os: windows-latest
+            c_compiler: cl
+            cpp_compiler: cl
+          - os: ubuntu-latest
+            c_compiler: gcc
+            cpp_compiler: g++
+          - os: ubuntu-latest
+            c_compiler: clang
+            cpp_compiler: clang++
+        exclude:
+          - os: windows-latest
+            c_compiler: gcc
+          - os: windows-latest
+            c_compiler: clang
+          - os: ubuntu-latest
+            c_compiler: cl
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set reusable strings
+      # Turn repeated input strings (such as the build output directory) into step outputs. These step outputs can be used throughout the workflow file.
+      id: strings
+      shell: bash
+      run: |
+        echo "build-output-dir=${{ github.workspace }}/tests/build" >> "$GITHUB_OUTPUT"
+
+    - name: Configure CMake
+      # Configure CMake in a 'build' subdirectory. `CMAKE_BUILD_TYPE` is only required if you are using a single-configuration generator such as make.
+      # See https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html?highlight=cmake_build_type
+      run: >
+        cmake -B ${{ steps.strings.outputs.build-output-dir }}
+        -DCMAKE_CXX_COMPILER=${{ matrix.cpp_compiler }}
+        -DCMAKE_C_COMPILER=${{ matrix.c_compiler }}
+        -DCMAKE_BUILD_TYPE=${{ matrix.build_type }}
+        -S ${{ github.workspace }}
+
+    - name: Build
+      # Build your program with the given configuration. Note that --config is needed because the default Windows generator is a multi-config generator (Visual Studio generator).
+      run: cmake --build ${{ steps.strings.outputs.build-output-dir }} --config ${{ matrix.build_type }}
+
+    - name: Test
+      working-directory: ${{ steps.strings.outputs.build-output-dir }}
+      # Execute tests defined by the CMake configuration. Note that --build-config is needed because the default Windows generator is a multi-config generator (Visual Studio generator).
+      # See https://cmake.org/cmake/help/latest/manual/ctest.1.html for more detail
+      run: ctest -VV --build-config ${{ matrix.build_type }}

CMakeLists.txt

@@ -1,67 +1,53 @@
-cmake_minimum_required (VERSION 3.0.2...3.27)
-project (utf8cpp VERSION 3.2.4 LANGUAGES CXX)
+# This file is deprecated and will be removed in a future release
+# Please see the instructions for installation in README.md file
 
-if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
-    set(IS_ROOT_PROJECT ON)
-else()
-    set(IS_ROOT_PROJECT OFF)
-endif()
+cmake_minimum_required (VERSION 3.14...3.27)
+project (utf8cpp 
+         VERSION 4.0.6
+         LANGUAGES CXX
+         DESCRIPTION "C++ portable library for working with utf-8 encoding")
 
-option(UTF8_TESTS "Enable tests for UTF8-CPP" ${IS_ROOT_PROJECT})
-option(UTF8_INSTALL "Enable installation for UTF8-CPP" ${IS_ROOT_PROJECT})
-option(UTF8_SAMPLES "Enable building samples for UTF8-CPP" ${IS_ROOT_PROJECT})
+add_library(${PROJECT_NAME} INTERFACE)
+
+include(GNUInstallDirs)
 
-add_library(utf8cpp INTERFACE)
 target_include_directories(utf8cpp INTERFACE
     "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/source>"
     $<INSTALL_INTERFACE:include/utf8cpp>
 )
-add_library(utf8::cpp ALIAS utf8cpp)
 
-if(UTF8_INSTALL)
-    include(CMakePackageConfigHelpers)
-    if(MSVC)
-        set(DEF_INSTALL_CMAKE_DIR CMake)
-    else()
-        include(GNUInstallDirs) # define CMAKE_INSTALL_*
-        set(DEF_INSTALL_CMAKE_DIR ${CMAKE_INSTALL_LIBDIR}/cmake/utf8cpp)
-    endif()
+include(CMakePackageConfigHelpers)
+write_basic_package_version_file(
+    "${PROJECT_BINARY_DIR}/${PROJECT_NAME}ConfigVersion.cmake"
+    VERSION ${PROJECT_VERSION}
+    COMPATIBILITY SameMajorVersion
+    ARCH_INDEPENDENT
+)
 
-    if(${CMAKE_VERSION} VERSION_GREATER "3.14")
-        set(OPTIONAL_ARCH_INDEPENDENT "ARCH_INDEPENDENT")
-    endif()
-    
-    write_basic_package_version_file(
-        ${CMAKE_CURRENT_BINARY_DIR}/utf8cppConfigVersion.cmake
-        VERSION ${PROJECT_VERSION}
-        COMPATIBILITY SameMajorVersion
-        ${OPTIONAL_ARCH_INDEPENDENT}
-    )
+install(TARGETS ${PROJECT_NAME}
+    EXPORT ${PROJECT_NAME}Targets
+    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+    PUBLIC_HEADER DESTINATION include COMPONENT Development
+    BUNDLE DESTINATION bin COMPONENT Runtime
+)
 
-    configure_package_config_file(
-        ${PROJECT_SOURCE_DIR}/utf8cppConfig.cmake.in
-        ${CMAKE_CURRENT_BINARY_DIR}/utf8cppConfig.cmake
-        INSTALL_DESTINATION ${DEF_INSTALL_CMAKE_DIR}
-    )
+configure_package_config_file(
+    "${PROJECT_SOURCE_DIR}/${PROJECT_NAME}Config.cmake.in"
+    "${PROJECT_BINARY_DIR}/${PROJECT_NAME}Config.cmake"
+    INSTALL_DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/${PROJECT_NAME}/cmake
+)
 
-    install(DIRECTORY source/ DESTINATION include/utf8cpp)
-    install(TARGETS utf8cpp EXPORT utf8cppTargets)
-    install(EXPORT utf8cppTargets DESTINATION ${DEF_INSTALL_CMAKE_DIR})
-    install(
-        FILES
-        ${CMAKE_CURRENT_BINARY_DIR}/utf8cppConfig.cmake
-        ${CMAKE_CURRENT_BINARY_DIR}/utf8cppConfigVersion.cmake
-        DESTINATION
-        ${DEF_INSTALL_CMAKE_DIR}
-    )
-endif()
+install(EXPORT ${PROJECT_NAME}Targets
+        FILE ${PROJECT_NAME}Targets.cmake
+        NAMESPACE ${PROJECT_NAME}::
+        DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/${PROJECT_NAME}/cmake)
 
-if(UTF8_SAMPLES)
-    add_executable(docsample ${PROJECT_SOURCE_DIR}/samples/docsample.cpp)
-    target_link_libraries(docsample PRIVATE utf8::cpp)
-endif()
+install(FILES "${PROJECT_BINARY_DIR}/${PROJECT_NAME}Config.cmake"
+              "${PROJECT_BINARY_DIR}/${PROJECT_NAME}ConfigVersion.cmake"
+        DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/${PROJECT_NAME}/cmake)
 
-if(UTF8_TESTS)
-    enable_testing()
-    add_subdirectory(tests)
-endif()
+install(FILES ${PROJECT_SOURCE_DIR}/source/utf8.h DESTINATION include/utf8cpp)
+install(DIRECTORY ${PROJECT_SOURCE_DIR}/source/utf8 DESTINATION
+        include/utf8cpp)

samples/docsample.cpp

@@ -1,64 +0,0 @@
-#include "../source/utf8.h"
-#include <iostream>
-#include <fstream>
-#include <string>
-#include <vector>
-
-
-using namespace std;
-
-int main(int argc, char** argv)
-{
-    if (argc != 2) {
-        cout << "\nUsage: docsample filename\n";
-        return 0;
-    }
-    const char* test_file_path = argv[1];
-    // Open the test file (must be UTF-8 encoded)
-    ifstream fs8(test_file_path);
-    if (!fs8.is_open()) {
-        cout << "Could not open " << test_file_path << endl;
-        return 0;
-    }
-
-    unsigned line_count = 1;
-    string line;
-    // Play with all the lines in the file
-    while (getline(fs8, line)) {
-        // check for invalid utf-8 (for a simple yes/no check, there is also utf8::is_valid function)
-#if __cplusplus >= 201103L // C++ 11 or later
-        auto end_it = utf8::find_invalid(line.begin(), line.end());
-#else
-        string::iterator end_it = utf8::find_invalid(line.begin(), line.end());
-#endif // C++ 11
-        if (end_it != line.end()) {
-            cout << "Invalid UTF-8 encoding detected at line " << line_count << "\n";
-            cout << "This part is fine: " << string(line.begin(), end_it) << "\n";
-        }
-        // Get the line length (at least for the valid part)
-        ptrdiff_t length = utf8::distance(line.begin(), end_it);
-        cout << "Length of line " << line_count << " is " << length <<  "\n";
-
-        // Convert it to utf-16
-#if __cplusplus >= 201103L // C++ 11 or later
-        u16string utf16line = utf8::utf8to16(line);
-#else
-        vector<unsigned short> utf16line;
-        utf8::utf8to16(line.begin(), end_it, back_inserter(utf16line));
-#endif // C++ 11
-        // And back to utf-8;
-#if __cplusplus >= 201103L // C++ 11 or later
-        string utf8line = utf8::utf16to8(utf16line);
-#else
-        string utf8line; 
-        utf8::utf16to8(utf16line.begin(), utf16line.end(), back_inserter(utf8line));
-#endif // C++ 11
-        // Confirm that the conversion went OK:
-        if (utf8line != string(line.begin(), end_it))
-            cout << "Error in UTF-16 conversion at line: " << line_count << "\n";        
-
-        line_count++;
-    } 
-
-    return 0;
-}

source/utf8.h

@@ -28,6 +28,18 @@ DEALINGS IN THE SOFTWARE.
 #ifndef UTF8_FOR_CPP_2675DCD0_9480_4c0c_B92A_CC14C027B731
 #define UTF8_FOR_CPP_2675DCD0_9480_4c0c_B92A_CC14C027B731
 
+/*
+To control the C++ language version used by the library, you can define UTF_CPP_CPLUSPLUS macro
+and set it to one of the values used by the __cplusplus predefined macro.
+
+For instance,
+    #define UTF_CPP_CPLUSPLUS 199711L
+will cause the UTF-8 CPP library to use only types and language features available in the C++ 98 standard.
+Some library features will be disabled.
+
+If you leave UTF_CPP_CPLUSPLUS undefined, it will be internally assigned to __cplusplus.
+*/
+
 #include "utf8/checked.h"
 #include "utf8/unchecked.h"
 

source/utf8/checked.h

@@ -39,28 +39,28 @@ namespace utf8
 
     // Exceptions that may be thrown from the library functions.
     class invalid_code_point : public exception {
-        uint32_t cp;
+        utfchar32_t cp;
     public:
-        invalid_code_point(uint32_t codepoint) : cp(codepoint) {}
+        invalid_code_point(utfchar32_t codepoint) : cp(codepoint) {}
         virtual const char* what() const UTF_CPP_NOEXCEPT UTF_CPP_OVERRIDE { return "Invalid code point"; }
-        uint32_t code_point() const {return cp;}
+        utfchar32_t code_point() const {return cp;}
     };
 
     class invalid_utf8 : public exception {
-        uint8_t u8;
+        utfchar8_t u8;
     public:
-        invalid_utf8 (uint8_t u) : u8(u) {}
-        invalid_utf8 (char c) : u8(static_cast<uint8_t>(c)) {}
+        invalid_utf8 (utfchar8_t u) : u8(u) {}
+        invalid_utf8 (char c) : u8(static_cast<utfchar8_t>(c)) {}
         virtual const char* what() const UTF_CPP_NOEXCEPT UTF_CPP_OVERRIDE { return "Invalid UTF-8"; }
-        uint8_t utf8_octet() const {return u8;}
+        utfchar8_t utf8_octet() const {return u8;}
     };
 
     class invalid_utf16 : public exception {
-        uint16_t u16;
+        utfchar16_t u16;
     public:
-        invalid_utf16 (uint16_t u) : u16(u) {}
+        invalid_utf16 (utfchar16_t u) : u16(u) {}
         virtual const char* what() const UTF_CPP_NOEXCEPT UTF_CPP_OVERRIDE { return "Invalid UTF-16"; }
-        uint16_t utf16_word() const {return u16;}
+        utfchar16_t utf16_word() const {return u16;}
     };
 
     class not_enough_room : public exception {
@@ -71,7 +71,7 @@ namespace utf8
     /// The library API - functions intended to be called by the users
 
     template <typename octet_iterator>
-    octet_iterator append(uint32_t cp, octet_iterator result)
+    octet_iterator append(utfchar32_t cp, octet_iterator result)
     {
         if (!utf8::internal::is_code_point_valid(cp))
             throw invalid_code_point(cp);
@@ -79,8 +79,22 @@ namespace utf8
         return internal::append(cp, result);
     }
 
+    inline void append(utfchar32_t cp, std::string& s)
+    {
+        append(cp, std::back_inserter(s));
+    }
+
+    template <typename word_iterator>
+    word_iterator append16(utfchar32_t cp, word_iterator result)
+    {
+        if (!utf8::internal::is_code_point_valid(cp))
+            throw invalid_code_point(cp);
+
+        return internal::append16(cp, result);
+    }
+
     template <typename octet_iterator, typename output_iterator>
-    output_iterator replace_invalid(octet_iterator start, octet_iterator end, output_iterator out, uint32_t replacement)
+    output_iterator replace_invalid(octet_iterator start, octet_iterator end, output_iterator out, utfchar32_t replacement)
     {
         while (start != end) {
             octet_iterator sequence_start = start;
@@ -115,14 +129,28 @@ namespace utf8
     template <typename octet_iterator, typename output_iterator>
     inline output_iterator replace_invalid(octet_iterator start, octet_iterator end, output_iterator out)
     {
-        static const uint32_t replacement_marker = utf8::internal::mask16(0xfffd);
+        static const utfchar32_t replacement_marker = utf8::internal::mask16(0xfffd);
         return utf8::replace_invalid(start, end, out, replacement_marker);
     }
 
-    template <typename octet_iterator>
-    uint32_t next(octet_iterator& it, octet_iterator end)
+    inline std::string replace_invalid(const std::string& s, utfchar32_t replacement)
     {
-        uint32_t cp = 0;
+        std::string result;
+        replace_invalid(s.begin(), s.end(), std::back_inserter(result), replacement);
+        return result;
+    }
+
+    inline std::string replace_invalid(const std::string& s)
+    {
+        std::string result;
+        replace_invalid(s.begin(), s.end(), std::back_inserter(result));
+        return result;
+    }
+
+    template <typename octet_iterator>
+    utfchar32_t next(octet_iterator& it, octet_iterator end)
+    {
+        utfchar32_t cp = 0;
         internal::utf_error err_code = utf8::internal::validate_next(it, end, cp);
         switch (err_code) {
             case internal::UTF8_OK :
@@ -132,21 +160,31 @@ namespace utf8
             case internal::INVALID_LEAD :
             case internal::INCOMPLETE_SEQUENCE :
             case internal::OVERLONG_SEQUENCE :
-                throw invalid_utf8(static_cast<uint8_t>(*it));
+                throw invalid_utf8(static_cast<utfchar8_t>(*it));
             case internal::INVALID_CODE_POINT :
                 throw invalid_code_point(cp);
         }
         return cp;
     }
 
+    template <typename word_iterator>
+    utfchar32_t next16(word_iterator& it, word_iterator end)
+    {
+        utfchar32_t cp = 0;
+        internal::utf_error err_code = utf8::internal::validate_next16(it, end, cp);
+        if (err_code == internal::NOT_ENOUGH_ROOM)
+            throw not_enough_room();
+        return cp;
+    }
+
     template <typename octet_iterator>
-    uint32_t peek_next(octet_iterator it, octet_iterator end)
+    utfchar32_t peek_next(octet_iterator it, octet_iterator end)
     {
         return utf8::next(it, end);
     }
 
     template <typename octet_iterator>
-    uint32_t prior(octet_iterator& it, octet_iterator start)
+    utfchar32_t prior(octet_iterator& it, octet_iterator start)
     {
         // can't do much if it == start
         if (it == start)
@@ -189,23 +227,23 @@ namespace utf8
     octet_iterator utf16to8 (u16bit_iterator start, u16bit_iterator end, octet_iterator result)
     {
         while (start != end) {
-            uint32_t cp = utf8::internal::mask16(*start++);
+            utfchar32_t cp = utf8::internal::mask16(*start++);
             // Take care of surrogate pairs first
             if (utf8::internal::is_lead_surrogate(cp)) {
                 if (start != end) {
-                    uint32_t trail_surrogate = utf8::internal::mask16(*start++);
+                    const utfchar32_t trail_surrogate = utf8::internal::mask16(*start++);
                     if (utf8::internal::is_trail_surrogate(trail_surrogate))
                         cp = (cp << 10) + trail_surrogate + internal::SURROGATE_OFFSET;
                     else
-                        throw invalid_utf16(static_cast<uint16_t>(trail_surrogate));
+                        throw invalid_utf16(static_cast<utfchar16_t>(trail_surrogate));
                 }
                 else
-                    throw invalid_utf16(static_cast<uint16_t>(cp));
+                    throw invalid_utf16(static_cast<utfchar16_t>(cp));
 
             }
             // Lone trail surrogate
             else if (utf8::internal::is_trail_surrogate(cp))
-                throw invalid_utf16(static_cast<uint16_t>(cp));
+                throw invalid_utf16(static_cast<utfchar16_t>(cp));
 
             result = utf8::append(cp, result);
         }
@@ -216,13 +254,13 @@ namespace utf8
     u16bit_iterator utf8to16 (octet_iterator start, octet_iterator end, u16bit_iterator result)
     {
         while (start < end) {
-            uint32_t cp = utf8::next(start, end);
+            const utfchar32_t cp = utf8::next(start, end);
             if (cp > 0xffff) { //make a surrogate pair
-                *result++ = static_cast<uint16_t>((cp >> 10)   + internal::LEAD_OFFSET);
-                *result++ = static_cast<uint16_t>((cp & 0x3ff) + internal::TRAIL_SURROGATE_MIN);
+                *result++ = static_cast<utfchar16_t>((cp >> 10)   + internal::LEAD_OFFSET);
+                *result++ = static_cast<utfchar16_t>((cp & 0x3ff) + internal::TRAIL_SURROGATE_MIN);
             }
             else
-                *result++ = static_cast<uint16_t>(cp);
+                *result++ = static_cast<utfchar16_t>(cp);
         }
         return result;
     }
@@ -252,9 +290,9 @@ namespace utf8
       octet_iterator range_start;
       octet_iterator range_end;
       public:
-      typedef uint32_t value_type;
-      typedef uint32_t* pointer;
-      typedef uint32_t& reference;
+      typedef utfchar32_t value_type;
+      typedef utfchar32_t* pointer;
+      typedef utfchar32_t& reference;
       typedef std::ptrdiff_t difference_type;
       typedef std::bidirectional_iterator_tag iterator_category;
       iterator () {}
@@ -268,7 +306,7 @@ namespace utf8
       }
       // the default "big three" are OK
       octet_iterator base () const { return it; }
-      uint32_t operator * () const
+      utfchar32_t operator * () const
       {
           octet_iterator temp = it;
           return utf8::next(temp, range_end);
@@ -309,7 +347,9 @@ namespace utf8
 
 } // namespace utf8
 
-#if UTF_CPP_CPLUSPLUS >= 201703L // C++ 17 or later
+#if UTF_CPP_CPLUSPLUS >= 202002L // C++ 20 or later
+#include "cpp20.h"
+#elif UTF_CPP_CPLUSPLUS >= 201703L // C++ 17 or later
 #include "cpp17.h"
 #elif UTF_CPP_CPLUSPLUS >= 201103L // C++ 11 or later
 #include "cpp11.h"

source/utf8/core.h

@@ -29,6 +29,8 @@ DEALINGS IN THE SOFTWARE.
 #define UTF8_FOR_CPP_CORE_H_2675DCD0_9480_4c0c_B92A_CC14C027B731
 
 #include <iterator>
+#include <cstring>
+#include <string>
 
 // Determine the C++ standard version.
 // If the user defines UTF_CPP_CPLUSPLUS, use that.
@@ -41,20 +43,33 @@ DEALINGS IN THE SOFTWARE.
 #if UTF_CPP_CPLUSPLUS >= 201103L // C++ 11 or later
     #define UTF_CPP_OVERRIDE override
     #define UTF_CPP_NOEXCEPT noexcept
+    #define UTF_CPP_STATIC_ASSERT(condition) static_assert(condition, "UTFCPP static assert");
 #else // C++ 98/03
     #define UTF_CPP_OVERRIDE
     #define UTF_CPP_NOEXCEPT throw()
+    // Simulate static_assert:
+    template <bool Condition> struct StaticAssert {static void assert() {int static_assert_impl[(Condition ? 1 : -1)];} };
+    template <> struct StaticAssert<true> {static void assert() {}};
+    #define UTF_CPP_STATIC_ASSERT(condition) StaticAssert<condition>::assert();
 #endif // C++ 11 or later
 
 
 namespace utf8
 {
-    // The typedefs for 8-bit, 16-bit and 32-bit unsigned integers
-    // You may need to change them to match your system.
-    // These typedefs have the same names as ones from cstdint, or boost/cstdint
-    typedef unsigned char   uint8_t;
-    typedef unsigned short  uint16_t;
-    typedef unsigned int    uint32_t;
+// The typedefs for 8-bit, 16-bit and 32-bit code units
+#if UTF_CPP_CPLUSPLUS >= 201103L // C++ 11 or later
+    #if UTF_CPP_CPLUSPLUS >= 202002L // C++ 20 or later
+        typedef char8_t         utfchar8_t;
+    #else // C++ 11/14/17
+        typedef unsigned char   utfchar8_t;
+    #endif
+    typedef char16_t        utfchar16_t;
+    typedef char32_t        utfchar32_t;
+#else // C++ 98/03
+    typedef unsigned char   utfchar8_t;
+    typedef unsigned short  utfchar16_t;
+    typedef unsigned int    utfchar32_t;
+#endif // C++ 11 or later
 
 // Helper code - not intended to be directly called by the library users. May be changed at any time
 namespace internal
@@ -62,61 +77,62 @@ namespace internal
     // Unicode constants
     // Leading (high) surrogates: 0xd800 - 0xdbff
     // Trailing (low) surrogates: 0xdc00 - 0xdfff
-    const uint16_t LEAD_SURROGATE_MIN  = 0xd800u;
-    const uint16_t LEAD_SURROGATE_MAX  = 0xdbffu;
-    const uint16_t TRAIL_SURROGATE_MIN = 0xdc00u;
-    const uint16_t TRAIL_SURROGATE_MAX = 0xdfffu;
-    const uint16_t LEAD_OFFSET         = 0xd7c0u;       // LEAD_SURROGATE_MIN - (0x10000 >> 10)
-    const uint32_t SURROGATE_OFFSET    = 0xfca02400u;   // 0x10000u - (LEAD_SURROGATE_MIN << 10) - TRAIL_SURROGATE_MIN
+    const utfchar16_t LEAD_SURROGATE_MIN  = 0xd800u;
+    const utfchar16_t LEAD_SURROGATE_MAX  = 0xdbffu;
+    const utfchar16_t TRAIL_SURROGATE_MIN = 0xdc00u;
+    const utfchar16_t TRAIL_SURROGATE_MAX = 0xdfffu;
+    const utfchar16_t LEAD_OFFSET         = 0xd7c0u;       // LEAD_SURROGATE_MIN - (0x10000 >> 10)
+    const utfchar32_t SURROGATE_OFFSET    = 0xfca02400u;   // 0x10000u - (LEAD_SURROGATE_MIN << 10) - TRAIL_SURROGATE_MIN
 
     // Maximum valid value for a Unicode code point
-    const uint32_t CODE_POINT_MAX      = 0x0010ffffu;
+    const utfchar32_t CODE_POINT_MAX      = 0x0010ffffu;
 
     template<typename octet_type>
-    inline uint8_t mask8(octet_type oc)
+    inline utfchar8_t mask8(octet_type oc)
     {
-        return static_cast<uint8_t>(0xff & oc);
+        return static_cast<utfchar8_t>(0xff & oc);
     }
     template<typename u16_type>
-    inline uint16_t mask16(u16_type oc)
+    inline utfchar16_t mask16(u16_type oc)
     {
-        return static_cast<uint16_t>(0xffff & oc);
+        return static_cast<utfchar16_t>(0xffff & oc);
     }
+
     template<typename octet_type>
     inline bool is_trail(octet_type oc)
     {
         return ((utf8::internal::mask8(oc) >> 6) == 0x2);
     }
 
-    template <typename u16>
-    inline bool is_lead_surrogate(u16 cp)
+    inline bool is_lead_surrogate(utfchar32_t cp)
     {
         return (cp >= LEAD_SURROGATE_MIN && cp <= LEAD_SURROGATE_MAX);
     }
 
-    template <typename u16>
-    inline bool is_trail_surrogate(u16 cp)
+    inline bool is_trail_surrogate(utfchar32_t cp)
     {
         return (cp >= TRAIL_SURROGATE_MIN && cp <= TRAIL_SURROGATE_MAX);
     }
 
-    template <typename u16>
-    inline bool is_surrogate(u16 cp)
+    inline bool is_surrogate(utfchar32_t cp)
     {
         return (cp >= LEAD_SURROGATE_MIN && cp <= TRAIL_SURROGATE_MAX);
     }
 
-    template <typename u32>
-    inline bool is_code_point_valid(u32 cp)
+    inline bool is_code_point_valid(utfchar32_t cp)
     {
         return (cp <= CODE_POINT_MAX && !utf8::internal::is_surrogate(cp));
     }
 
-    template <typename octet_iterator>
-    inline typename std::iterator_traits<octet_iterator>::difference_type
-    sequence_length(octet_iterator lead_it)
+    inline bool is_in_bmp(utfchar32_t cp)
     {
-        uint8_t lead = utf8::internal::mask8(*lead_it);
+        return cp < utfchar32_t(0x10000);
+    }
+
+    template <typename octet_iterator>
+    int sequence_length(octet_iterator lead_it)
+    {
+        const utfchar8_t lead = utf8::internal::mask8(*lead_it);
         if (lead < 0x80)
             return 1;
         else if ((lead >> 5) == 0x6)
@@ -129,8 +145,7 @@ namespace internal
             return 0;
     }
 
-    template <typename octet_difference_type>
-    inline bool is_overlong_sequence(uint32_t cp, octet_difference_type length)
+    inline bool is_overlong_sequence(utfchar32_t cp, int length)
     {
         if (cp < 0x80) {
             if (length != 1) 
@@ -144,7 +159,6 @@ namespace internal
             if (length != 3) 
                 return true;
         }
-
         return false;
     }
 
@@ -152,7 +166,7 @@ namespace internal
 
     /// Helper for get_sequence_x
     template <typename octet_iterator>
-    utf_error increase_safely(octet_iterator& it, octet_iterator end)
+    utf_error increase_safely(octet_iterator& it, const octet_iterator end)
     {
         if (++it == end)
             return NOT_ENOUGH_ROOM;
@@ -163,11 +177,11 @@ namespace internal
         return UTF8_OK;
     }
 
-    #define UTF8_CPP_INCREASE_AND_RETURN_ON_ERROR(IT, END) {utf_error ret = increase_safely(IT, END); if (ret != UTF8_OK) return ret;}    
+    #define UTF8_CPP_INCREASE_AND_RETURN_ON_ERROR(IT, END) {utf_error ret = increase_safely(IT, END); if (ret != UTF8_OK) return ret;}
 
     /// get_sequence_x functions decode utf-8 sequences of the length x
     template <typename octet_iterator>
-    utf_error get_sequence_1(octet_iterator& it, octet_iterator end, uint32_t& code_point)
+    utf_error get_sequence_1(octet_iterator& it, octet_iterator end, utfchar32_t& code_point)
     {
         if (it == end)
             return NOT_ENOUGH_ROOM;
@@ -178,7 +192,7 @@ namespace internal
     }
 
     template <typename octet_iterator>
-    utf_error get_sequence_2(octet_iterator& it, octet_iterator end, uint32_t& code_point)
+    utf_error get_sequence_2(octet_iterator& it, octet_iterator end, utfchar32_t& code_point)
     {
         if (it == end) 
             return NOT_ENOUGH_ROOM;
@@ -193,7 +207,7 @@ namespace internal
     }
 
     template <typename octet_iterator>
-    utf_error get_sequence_3(octet_iterator& it, octet_iterator end, uint32_t& code_point)
+    utf_error get_sequence_3(octet_iterator& it, octet_iterator end, utfchar32_t& code_point)
     {
         if (it == end)
             return NOT_ENOUGH_ROOM;
@@ -206,13 +220,13 @@ namespace internal
 
         UTF8_CPP_INCREASE_AND_RETURN_ON_ERROR(it, end)
 
-        code_point += (*it) & 0x3f;
+        code_point = static_cast<utfchar32_t>(code_point + ((*it) & 0x3f));
 
         return UTF8_OK;
     }
 
     template <typename octet_iterator>
-    utf_error get_sequence_4(octet_iterator& it, octet_iterator end, uint32_t& code_point)
+    utf_error get_sequence_4(octet_iterator& it, octet_iterator end, utfchar32_t& code_point)
     {
         if (it == end)
            return NOT_ENOUGH_ROOM;
@@ -225,11 +239,11 @@ namespace internal
 
         UTF8_CPP_INCREASE_AND_RETURN_ON_ERROR(it, end)
 
-        code_point += (utf8::internal::mask8(*it) << 6) & 0xfff;
+        code_point = static_cast<utfchar32_t>(code_point + ((utf8::internal::mask8(*it) << 6) & 0xfff));
 
         UTF8_CPP_INCREASE_AND_RETURN_ON_ERROR(it, end)
 
-        code_point += (*it) & 0x3f;
+        code_point = static_cast<utfchar32_t>(code_point + ((*it) & 0x3f));
 
         return UTF8_OK;
     }
@@ -237,7 +251,7 @@ namespace internal
     #undef UTF8_CPP_INCREASE_AND_RETURN_ON_ERROR
 
     template <typename octet_iterator>
-    utf_error validate_next(octet_iterator& it, octet_iterator end, uint32_t& code_point)
+    utf_error validate_next(octet_iterator& it, octet_iterator end, utfchar32_t& code_point)
     {
         if (it == end)
             return NOT_ENOUGH_ROOM;
@@ -246,10 +260,9 @@ namespace internal
         // Of course, it does not make much sense with i.e. stream iterators
         octet_iterator original_it = it;
 
-        uint32_t cp = 0;
+        utfchar32_t cp = 0;
         // Determine the sequence length based on the lead octet
-        typedef typename std::iterator_traits<octet_iterator>::difference_type octet_difference_type;
-        const octet_difference_type length = utf8::internal::sequence_length(it);
+        const int length = utf8::internal::sequence_length(it);
 
         // Get trail octets and calculate the code point
         utf_error err = UTF8_OK;
@@ -293,15 +306,55 @@ namespace internal
 
     template <typename octet_iterator>
     inline utf_error validate_next(octet_iterator& it, octet_iterator end) {
-        uint32_t ignored;
+        utfchar32_t ignored;
         return utf8::internal::validate_next(it, end, ignored);
     }
 
+    template <typename word_iterator>
+    utf_error validate_next16(word_iterator& it, word_iterator end, utfchar32_t& code_point)
+    {
+        // Make sure the iterator dereferences a large enough type
+        typedef typename std::iterator_traits<word_iterator>::value_type word_type;
+        UTF_CPP_STATIC_ASSERT(sizeof(word_type) >= sizeof(utfchar16_t));
+        // Check the edge case:
+        if (it == end)
+            return NOT_ENOUGH_ROOM;
+        // Save the original value of it so we can go back in case of failure
+        // Of course, it does not make much sense with i.e. stream iterators
+        word_iterator original_it = it;
+
+        utf_error err = UTF8_OK;
+
+        const utfchar16_t first_word = *it++;
+        if (!is_surrogate(first_word)) {
+            code_point = first_word;
+            return UTF8_OK;
+        }
+        else {
+            if (it == end)
+                err = NOT_ENOUGH_ROOM;
+            else if (is_lead_surrogate(first_word)) {
+                const utfchar16_t second_word = *it++;
+                if (is_trail_surrogate(second_word)) {
+                    code_point = static_cast<utfchar32_t>(first_word << 10) + second_word + SURROGATE_OFFSET;
+                    return UTF8_OK;
+                } else 
+                    err = INCOMPLETE_SEQUENCE; 
+                
+            } else {
+                err = INVALID_LEAD;               
+            }
+        }
+        // error branch
+        it = original_it;
+        return err;
+    }
+
     // Internal implementation of both checked and unchecked append() function
     // This function will be invoked by the overloads below, as they will know
     // the octet_type.
     template <typename octet_iterator, typename octet_type>
-    octet_iterator append(uint32_t cp, octet_iterator result) {
+    octet_iterator append(utfchar32_t cp, octet_iterator result) {
         if (cp < 0x80)                        // one octet
             *(result++) = static_cast<octet_type>(cp);
         else if (cp < 0x800) {                // two octets
@@ -325,7 +378,7 @@ namespace internal
     // One of the following overloads will be invoked from the API calls
 
     // A simple (but dangerous) case: the caller appends byte(s) to a char array
-    inline char* append(uint32_t cp, char* result) {
+    inline char* append(utfchar32_t cp, char* result) {
         return append<char*, char>(cp, result);
     }
 
@@ -333,17 +386,50 @@ namespace internal
     // i.e. append(cp, std::back_inserter(str));
     template<typename container_type>
     std::back_insert_iterator<container_type> append
-            (uint32_t cp, std::back_insert_iterator<container_type> result) {
+            (utfchar32_t cp, std::back_insert_iterator<container_type> result) {
         return append<std::back_insert_iterator<container_type>,
             typename container_type::value_type>(cp, result);
     }
 
     // The caller uses some other kind of output operator - not covered above
     // Note that in this case we are not able to determine octet_type
-    // so we assume it's uint_8; that can cause a conversion warning if we are wrong.
+    // so we assume it's utfchar8_t; that can cause a conversion warning if we are wrong.
     template <typename octet_iterator>
-    octet_iterator append(uint32_t cp, octet_iterator result) {
-        return append<octet_iterator, uint8_t>(cp, result);
+    octet_iterator append(utfchar32_t cp, octet_iterator result) {
+        return append<octet_iterator, utfchar8_t>(cp, result);
+    }
+
+    // Internal implementation of both checked and unchecked append16() function
+    // This function will be invoked by the overloads below, as they will know
+    // the word_type.
+    template <typename word_iterator, typename word_type>
+    word_iterator append16(utfchar32_t cp, word_iterator result) {
+        UTF_CPP_STATIC_ASSERT(sizeof(word_type) >= sizeof(utfchar16_t));
+        if (is_in_bmp(cp))
+            *(result++) = static_cast<word_type>(cp);
+        else {
+            // Code points from the supplementary planes are encoded via surrogate pairs
+            *(result++) = static_cast<word_type>(LEAD_OFFSET + (cp >> 10));
+            *(result++) = static_cast<word_type>(TRAIL_SURROGATE_MIN + (cp & 0x3FF));
+        }
+        return result;
+    }
+
+    // Hopefully, most common case: the caller uses back_inserter
+    // i.e. append16(cp, std::back_inserter(str));
+    template<typename container_type>
+    std::back_insert_iterator<container_type> append16
+            (utfchar32_t cp, std::back_insert_iterator<container_type> result) {
+        return append16<std::back_insert_iterator<container_type>,
+            typename container_type::value_type>(cp, result);
+    }
+
+    // The caller uses some other kind of output operator - not covered above
+    // Note that in this case we are not able to determine word_type
+    // so we assume it's utfchar16_t; that can cause a conversion warning if we are wrong.
+    template <typename word_iterator>
+    word_iterator append16(utfchar32_t cp, word_iterator result) {
+        return append16<word_iterator, utfchar16_t>(cp, result);
     }
 
 } // namespace internal
@@ -351,7 +437,7 @@ namespace internal
     /// The library API - functions intended to be called by the users
 
     // Byte order mark
-    const uint8_t bom[] = {0xef, 0xbb, 0xbf};
+    const utfchar8_t bom[] = {0xef, 0xbb, 0xbf};
 
     template <typename octet_iterator>
     octet_iterator find_invalid(octet_iterator start, octet_iterator end)
@@ -365,12 +451,36 @@ namespace internal
         return result;
     }
 
+    inline const char* find_invalid(const char* str)
+    {
+        const char* end = str + std::strlen(str);
+        return find_invalid(str, end); 
+    }
+
+    inline std::size_t find_invalid(const std::string& s)
+    {
+        std::string::const_iterator invalid = find_invalid(s.begin(), s.end());
+        return (invalid == s.end()) ? std::string::npos : static_cast<std::size_t>(invalid - s.begin());
+    }
+
     template <typename octet_iterator>
     inline bool is_valid(octet_iterator start, octet_iterator end)
     {
         return (utf8::find_invalid(start, end) == end);
     }
 
+    inline bool is_valid(const char* str)
+    {
+        return (*(utf8::find_invalid(str)) == '\0');
+    }
+
+    inline bool is_valid(const std::string& s)
+    {
+        return is_valid(s.begin(), s.end());
+    }
+
+
+
     template <typename octet_iterator>
     inline bool starts_with_bom (octet_iterator it, octet_iterator end)
     {
@@ -379,7 +489,12 @@ namespace internal
             ((it != end) && (utf8::internal::mask8(*it++)) == bom[1]) &&
             ((it != end) && (utf8::internal::mask8(*it))   == bom[2])
            );
-    }	
+    }
+
+    inline bool starts_with_bom(const std::string& s)
+    {
+        return starts_with_bom(s.begin(), s.end());
+    } 
 } // namespace utf8
 
 #endif // header guard

source/utf8/cpp11.h

@@ -29,14 +29,12 @@ DEALINGS IN THE SOFTWARE.
 #define UTF8_FOR_CPP_a184c22c_d012_11e8_a8d5_f2801f1b9fd1
 
 #include "checked.h"
-#include <string>
 
 namespace utf8
 {
-
-    inline void append(char32_t cp, std::string& s)
+    inline void append16(utfchar32_t cp, std::u16string& s)
     {
-        append(uint32_t(cp), std::back_inserter(s));
+        append16(cp, std::back_inserter(s));
     }
 
     inline std::string utf16to8(const std::u16string& s)
@@ -66,37 +64,6 @@ namespace utf8
         utf8to32(s.begin(), s.end(), std::back_inserter(result));
         return result;
     }
-
-    inline std::size_t find_invalid(const std::string& s)
-    {
-        std::string::const_iterator invalid = find_invalid(s.begin(), s.end());
-        return (invalid == s.end()) ? std::string::npos : static_cast<std::size_t>(invalid - s.begin());
-    }
-
-    inline bool is_valid(const std::string& s)
-    {
-        return is_valid(s.begin(), s.end());
-    }
-
-    inline std::string replace_invalid(const std::string& s, char32_t replacement)
-    {
-        std::string result;
-        replace_invalid(s.begin(), s.end(), std::back_inserter(result), replacement);
-        return result;
-    }
-
-    inline std::string replace_invalid(const std::string& s)
-    {
-        std::string result;
-        replace_invalid(s.begin(), s.end(), std::back_inserter(result));
-        return result;
-    }
-
-    inline bool starts_with_bom(const std::string& s)
-    {
-        return starts_with_bom(s.begin(), s.end());
-    }
- 
 } // namespace utf8
 
 #endif // header guard

source/utf8/cpp17.h

@@ -28,17 +28,10 @@ DEALINGS IN THE SOFTWARE.
 #ifndef UTF8_FOR_CPP_7e906c01_03a3_4daf_b420_ea7ea952b3c9
 #define UTF8_FOR_CPP_7e906c01_03a3_4daf_b420_ea7ea952b3c9
 
-#include "checked.h"
-#include <string>
+#include "cpp11.h"
 
 namespace utf8
 {
-
-    inline void append(char32_t cp, std::string& s)
-    {
-        append(uint32_t(cp), std::back_inserter(s));
-    }
-
     inline std::string utf16to8(std::u16string_view s)
     {
         std::string result;

source/utf8/cpp20.h

@@ -0,0 +1,124 @@
+// Copyright 2022 Nemanja Trifunovic
+
+/*
+Permission is hereby granted, free of charge, to any person or organization
+obtaining a copy of the software and accompanying documentation covered by
+this license (the "Software") to use, reproduce, display, distribute,
+execute, and transmit the Software, and to prepare derivative works of the
+Software, and to permit third-parties to whom the Software is furnished to
+do so, all subject to the following:
+
+The copyright notices in the Software and this entire statement, including
+the above license grant, this restriction and the following disclaimer,
+must be included in all copies of the Software, in whole or in part, and
+all derivative works of the Software, unless such copies or derivative
+works are solely in the form of machine-executable object code generated by
+a source language processor.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
+SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
+FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+*/
+
+
+#ifndef UTF8_FOR_CPP_207e906c01_03a3_4daf_b420_ea7ea952b3c9
+#define UTF8_FOR_CPP_207e906c01_03a3_4daf_b420_ea7ea952b3c9
+
+#include "cpp17.h"
+
+namespace utf8
+{
+    inline std::u8string utf16tou8(const std::u16string& s)
+    {
+        std::u8string result;
+        utf16to8(s.begin(), s.end(), std::back_inserter(result));
+        return result;
+    }
+
+    inline std::u8string utf16tou8(std::u16string_view s)
+    {
+        std::u8string result;
+        utf16to8(s.begin(), s.end(), std::back_inserter(result));
+        return result;
+    }
+
+    inline std::u16string utf8to16(const std::u8string& s)
+    {
+        std::u16string result;
+        utf8to16(s.begin(), s.end(), std::back_inserter(result));
+        return result;
+    }
+
+    inline std::u16string utf8to16(const std::u8string_view& s)
+    {
+        std::u16string result;
+        utf8to16(s.begin(), s.end(), std::back_inserter(result));
+        return result;
+    }
+
+    inline std::u8string utf32tou8(const std::u32string& s)
+    {
+        std::u8string result;
+        utf32to8(s.begin(), s.end(), std::back_inserter(result));
+        return result;
+    }
+
+    inline std::u8string utf32tou8(const std::u32string_view& s)
+    {
+        std::u8string result;
+        utf32to8(s.begin(), s.end(), std::back_inserter(result));
+        return result;
+    }
+
+    inline std::u32string utf8to32(const std::u8string& s)
+    {
+        std::u32string result;
+        utf8to32(s.begin(), s.end(), std::back_inserter(result));
+        return result;
+    }
+
+    inline std::u32string utf8to32(const std::u8string_view& s)
+    {
+        std::u32string result;
+        utf8to32(s.begin(), s.end(), std::back_inserter(result));
+        return result;
+    }
+
+    inline std::size_t find_invalid(const std::u8string& s)
+    {
+        std::u8string::const_iterator invalid = find_invalid(s.begin(), s.end());
+        return (invalid == s.end()) ? std::string_view::npos : static_cast<std::size_t>(invalid - s.begin());
+    }
+
+    inline bool is_valid(const std::u8string& s)
+    {
+        return is_valid(s.begin(), s.end());
+    }
+
+    inline std::u8string replace_invalid(const std::u8string& s, char32_t replacement)
+    {
+        std::u8string result;
+        replace_invalid(s.begin(), s.end(), std::back_inserter(result), replacement);
+        return result;
+    }
+
+    inline std::u8string replace_invalid(const std::u8string& s)
+    {
+        std::u8string result;
+        replace_invalid(s.begin(), s.end(), std::back_inserter(result));
+        return result;
+    }
+
+    inline bool starts_with_bom(const std::u8string& s)
+    {
+        return starts_with_bom(s.begin(), s.end());
+    }
+ 
+} // namespace utf8
+
+#endif // header guard
+

source/utf8/unchecked.h

@@ -35,13 +35,19 @@ namespace utf8
     namespace unchecked
     {
         template <typename octet_iterator>
-        octet_iterator append(uint32_t cp, octet_iterator result)
+        octet_iterator append(utfchar32_t cp, octet_iterator result)
         {
             return internal::append(cp, result);
         }
 
+        template <typename word_iterator>
+        word_iterator append16(utfchar32_t cp, word_iterator result)
+        {
+            return internal::append16(cp, result);
+        }
+
         template <typename octet_iterator, typename output_iterator>
-        output_iterator replace_invalid(octet_iterator start, octet_iterator end, output_iterator out, uint32_t replacement)
+        output_iterator replace_invalid(octet_iterator start, octet_iterator end, output_iterator out, utfchar32_t replacement)
         {
             while (start != end) {
                 octet_iterator sequence_start = start;
@@ -52,17 +58,17 @@ namespace utf8
                             *out++ = *it;
                         break;
                     case internal::NOT_ENOUGH_ROOM:
-                        out = utf8::unchecked::append (replacement, out);
+                        out = utf8::unchecked::append(replacement, out);
                         start = end;
                         break;
                     case internal::INVALID_LEAD:
-                        out = utf8::unchecked::append (replacement, out);
+                        out = utf8::unchecked::append(replacement, out);
                         ++start;
                         break;
                     case internal::INCOMPLETE_SEQUENCE:
                     case internal::OVERLONG_SEQUENCE:
                     case internal::INVALID_CODE_POINT:
-                        out = utf8::unchecked::append (replacement, out);
+                        out = utf8::unchecked::append(replacement, out);
                         ++start;
                         // just one replacement mark for the sequence
                         while (start != end && utf8::internal::is_trail(*start))
@@ -76,16 +82,29 @@ namespace utf8
         template <typename octet_iterator, typename output_iterator>
         inline output_iterator replace_invalid(octet_iterator start, octet_iterator end, output_iterator out)
         {
-            static const uint32_t replacement_marker = utf8::internal::mask16(0xfffd);
+            static const utfchar32_t replacement_marker = utf8::internal::mask16(0xfffd);
             return utf8::unchecked::replace_invalid(start, end, out, replacement_marker);
         }
 
-        template <typename octet_iterator>
-        uint32_t next(octet_iterator& it)
+        inline std::string replace_invalid(const std::string& s, utfchar32_t replacement)
         {
-            uint32_t cp = utf8::internal::mask8(*it);
-            typename std::iterator_traits<octet_iterator>::difference_type length = utf8::internal::sequence_length(it);
-            switch (length) {
+            std::string result;
+            replace_invalid(s.begin(), s.end(), std::back_inserter(result), replacement);
+            return result;
+        }
+
+        inline std::string replace_invalid(const std::string& s)
+        {
+            std::string result;
+            replace_invalid(s.begin(), s.end(), std::back_inserter(result));
+            return result;
+        }
+
+        template <typename octet_iterator>
+        utfchar32_t next(octet_iterator& it)
+        {
+            utfchar32_t cp = utf8::internal::mask8(*it);
+            switch (utf8::internal::sequence_length(it)) {
                 case 1:
                     break;
                 case 2:
@@ -96,15 +115,15 @@ namespace utf8
                     ++it; 
                     cp = ((cp << 12) & 0xffff) + ((utf8::internal::mask8(*it) << 6) & 0xfff);
                     ++it;
-                    cp += (*it) & 0x3f;
+                    cp = static_cast<utfchar32_t>(cp + ((*it) & 0x3f));
                     break;
                 case 4:
                     ++it;
                     cp = ((cp << 18) & 0x1fffff) + ((utf8::internal::mask8(*it) << 12) & 0x3ffff);                
                     ++it;
-                    cp += (utf8::internal::mask8(*it) << 6) & 0xfff;
+                    cp = static_cast<utfchar32_t>(cp + ((utf8::internal::mask8(*it) << 6) & 0xfff));
                     ++it;
-                    cp += (*it) & 0x3f; 
+                    cp = static_cast<utfchar32_t>(cp + ((*it) & 0x3f)); 
                     break;
             }
             ++it;
@@ -112,13 +131,22 @@ namespace utf8
         }
 
         template <typename octet_iterator>
-        uint32_t peek_next(octet_iterator it)
+        utfchar32_t peek_next(octet_iterator it)
         {
             return utf8::unchecked::next(it);
         }
 
+        template <typename word_iterator>
+        utfchar32_t next16(word_iterator& it)
+        {
+            utfchar32_t cp = utf8::internal::mask16(*it++);
+            if (utf8::internal::is_lead_surrogate(cp))
+                return (cp << 10) + *it++ + utf8::internal::SURROGATE_OFFSET;
+            return cp;
+        }
+
         template <typename octet_iterator>
-        uint32_t prior(octet_iterator& it)
+        utfchar32_t prior(octet_iterator& it)
         {
             while (utf8::internal::is_trail(*(--it))) ;
             octet_iterator temp = it;
@@ -126,7 +154,7 @@ namespace utf8
         }
 
         template <typename octet_iterator, typename distance_type>
-        void advance (octet_iterator& it, distance_type n)
+        void advance(octet_iterator& it, distance_type n)
         {
             const distance_type zero(0);
             if (n < zero) {
@@ -142,7 +170,7 @@ namespace utf8
 
         template <typename octet_iterator>
         typename std::iterator_traits<octet_iterator>::difference_type
-        distance (octet_iterator first, octet_iterator last)
+        distance(octet_iterator first, octet_iterator last)
         {
             typename std::iterator_traits<octet_iterator>::difference_type dist;
             for (dist = 0; first < last; ++dist) 
@@ -151,13 +179,15 @@ namespace utf8
         }
 
         template <typename u16bit_iterator, typename octet_iterator>
-        octet_iterator utf16to8 (u16bit_iterator start, u16bit_iterator end, octet_iterator result)
+        octet_iterator utf16to8(u16bit_iterator start, u16bit_iterator end, octet_iterator result)
         {
             while (start != end) {
-                uint32_t cp = utf8::internal::mask16(*start++);
-            // Take care of surrogate pairs first
+                utfchar32_t cp = utf8::internal::mask16(*start++);
+                // Take care of surrogate pairs first
                 if (utf8::internal::is_lead_surrogate(cp)) {
-                    uint32_t trail_surrogate = utf8::internal::mask16(*start++);
+                    if (start == end)
+                        return result;
+                    utfchar32_t trail_surrogate = utf8::internal::mask16(*start++);
                     cp = (cp << 10) + trail_surrogate + internal::SURROGATE_OFFSET;
                 }
                 result = utf8::unchecked::append(cp, result);
@@ -166,22 +196,22 @@ namespace utf8
         }
 
         template <typename u16bit_iterator, typename octet_iterator>
-        u16bit_iterator utf8to16 (octet_iterator start, octet_iterator end, u16bit_iterator result)
+        u16bit_iterator utf8to16(octet_iterator start, octet_iterator end, u16bit_iterator result)
         {
             while (start < end) {
-                uint32_t cp = utf8::unchecked::next(start);
+                utfchar32_t cp = utf8::unchecked::next(start);
                 if (cp > 0xffff) { //make a surrogate pair
-                    *result++ = static_cast<uint16_t>((cp >> 10)   + internal::LEAD_OFFSET);
-                    *result++ = static_cast<uint16_t>((cp & 0x3ff) + internal::TRAIL_SURROGATE_MIN);
+                    *result++ = static_cast<utfchar16_t>((cp >> 10)   + internal::LEAD_OFFSET);
+                    *result++ = static_cast<utfchar16_t>((cp & 0x3ff) + internal::TRAIL_SURROGATE_MIN);
                 }
                 else
-                    *result++ = static_cast<uint16_t>(cp);
+                    *result++ = static_cast<utfchar16_t>(cp);
             }
             return result;
         }
 
         template <typename octet_iterator, typename u32bit_iterator>
-        octet_iterator utf32to8 (u32bit_iterator start, u32bit_iterator end, octet_iterator result)
+        octet_iterator utf32to8(u32bit_iterator start, u32bit_iterator end, octet_iterator result)
         {
             while (start != end)
                 result = utf8::unchecked::append(*(start++), result);
@@ -190,7 +220,7 @@ namespace utf8
         }
 
         template <typename octet_iterator, typename u32bit_iterator>
-        u32bit_iterator utf8to32 (octet_iterator start, octet_iterator end, u32bit_iterator result)
+        u32bit_iterator utf8to32(octet_iterator start, octet_iterator end, u32bit_iterator result)
         {
             while (start < end)
                 (*result++) = utf8::unchecked::next(start);
@@ -203,16 +233,16 @@ namespace utf8
           class iterator {
             octet_iterator it;
             public:
-            typedef uint32_t value_type;
-            typedef uint32_t* pointer;
-            typedef uint32_t& reference;
+            typedef utfchar32_t value_type;
+            typedef utfchar32_t* pointer;
+            typedef utfchar32_t& reference;
             typedef std::ptrdiff_t difference_type;
             typedef std::bidirectional_iterator_tag iterator_category;
             iterator () {}
             explicit iterator (const octet_iterator& octet_it): it(octet_it) {}
             // the default "big three" are OK
             octet_iterator base () const { return it; }
-            uint32_t operator * () const
+            utfchar32_t operator * () const
             {
                 octet_iterator temp = it;
                 return utf8::unchecked::next(temp);

tests/CMakeLists.txt

@@ -1,19 +1,26 @@
-add_executable(negative ${PROJECT_SOURCE_DIR}/tests/negative.cpp)
-add_executable(cpp11 ${PROJECT_SOURCE_DIR}/tests/test_cpp11.cpp)
-add_executable(cpp17 ${PROJECT_SOURCE_DIR}/tests/test_cpp17.cpp)
-add_executable(apitests ${PROJECT_SOURCE_DIR}/tests/apitests.cpp)
+cmake_minimum_required (VERSION 3.5)
+project(utfcpptests LANGUAGES CXX)
+enable_testing()
 
-add_executable(noexceptionstests ${PROJECT_SOURCE_DIR}/tests/noexceptionstests.cpp)
+add_library(${PROJECT_NAME} INTERFACE)
 
-target_link_libraries(negative PRIVATE utf8::cpp)
-target_link_libraries(cpp11 PRIVATE utf8::cpp)
-target_link_libraries(cpp17 PRIVATE utf8::cpp)
-target_link_libraries(apitests PRIVATE utf8::cpp)
-target_link_libraries(noexceptionstests PRIVATE utf8::cpp)
+include_directories("${PROJECT_SOURCE_DIR}/../source")
 
-target_compile_options(${PROJECT_NAME} INTERFACE
-  $<$<CXX_COMPILER_ID:MSVC>:/W4>
-  $<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-Wall -Wextra -Wpedantic -Wconversion>)
+if (MSVC)
+    # warning level 4
+    add_compile_options(/W4)
+else()
+    # additional warnings
+    add_compile_options(-Wall -Wextra -Wpedantic -Wconversion -Wsign-conversion)
+endif()
+
+add_executable(negative negative.cpp)
+add_executable(cpp11 test_cpp11.cpp)
+add_executable(cpp17 test_cpp17.cpp)
+add_executable(cpp20 test_cpp20.cpp)
+add_executable(apitests apitests.cpp)
+
+add_executable(noexceptionstests noexceptionstests.cpp)
 
 target_compile_options(noexceptionstests PUBLIC -fno-exceptions)
 
@@ -35,9 +42,17 @@ set_target_properties(cpp17
                       CXX_STANDARD_REQUIRED YES
                       CXX_EXTENSIONS NO)
 
-add_test(negative_test negative ${PROJECT_SOURCE_DIR}/tests/test_data/utf8_invalid.txt)
+set_target_properties(cpp20
+                      PROPERTIES
+                      CXX_STANDARD 20
+                      CXX_STANDARD_REQUIRED YES
+                      CXX_EXTENSIONS NO)
+
+
+add_test(negative_test negative ${PROJECT_SOURCE_DIR}/test_data/utf8_invalid.txt)
 add_test(cpp11_test cpp11)
 add_test(cpp17_test cpp17)
+add_test(cpp20_test cpp20)
 add_test(api_test apitests)
 add_test(noexceptions_test noexceptionstests)
 

tests/docker/Dockerfile

@@ -1,4 +1,4 @@
-FROM debian:buster-slim
+FROM gcc:12.2
 
 RUN  apt-get update \
   && apt-get install -y make g++ cmake git \

tests/test_checked_api.h

@@ -47,6 +47,22 @@ TEST(CheckedAPITests, test_append)
     EXPECT_EQ (c[1], 0);
 }
 
+TEST(CheckedAPITests, test_append16)
+{
+    utfchar16_t u[5] = {0,0};
+    append16(0x0448, u);
+    EXPECT_EQ (u[0], 0x0448);
+    EXPECT_EQ (u[1], 0x0000);
+
+    append16(0x65e5, u);
+    EXPECT_EQ (u[0], 0x65e5);
+    EXPECT_EQ (u[1], 0x0000);
+
+    append16(0x10346, u);
+    EXPECT_EQ (u[0], 0xd800);
+    EXPECT_EQ (u[1], 0xdf46);
+}
+
 TEST(CheckedAPITests, test_next)
 {
     const char* twochars = "\xe6\x97\xa5\xd1\x88";
@@ -71,6 +87,19 @@ TEST(CheckedAPITests, test_next)
     EXPECT_EQ (w, threechars + 9);
 }
 
+TEST(CheckedAPITests, test_next16)
+{
+    const utfchar16_t u[3] = {0x65e5, 0xd800, 0xdf46};
+    const utfchar16_t* w = u;
+    utf8::utfchar32_t cp = next16(w, w + 3);
+    EXPECT_EQ (cp, 0x65e5);
+    EXPECT_EQ (w, u + 1);
+
+    cp = next16(w, w + 2);
+    EXPECT_EQ (cp, 0x10346);
+    EXPECT_EQ (w, u + 3);
+}
+
 TEST(CheckedAPITests, test_peek_next)
 {
     const char* const cw = "\xe6\x97\xa5\xd1\x88";
@@ -171,7 +200,9 @@ TEST(CheckedAPITests, test_replace_invalid)
 TEST(CheckedAPITests, test_find_invalid)
 {
     char utf_invalid[] = "\xe6\x97\xa5\xd1\x88\xfa";
-    char* invalid = find_invalid(utf_invalid, utf_invalid + 6);
+    const char* invalid = find_invalid(utf_invalid, utf_invalid + 6);
+    EXPECT_EQ (invalid, utf_invalid + 5);
+    invalid = find_invalid(utf_invalid);
     EXPECT_EQ (invalid, utf_invalid + 5);
 }
 
@@ -180,9 +211,13 @@ TEST(CheckedAPITests, test_is_valid)
     char utf_invalid[] = "\xe6\x97\xa5\xd1\x88\xfa";
     bool bvalid = is_valid(utf_invalid, utf_invalid + 6);
     EXPECT_FALSE (bvalid);
+    bvalid = is_valid(utf_invalid);
+    EXPECT_FALSE (bvalid);
     char utf8_with_surrogates[] = "\xe6\x97\xa5\xd1\x88\xf0\x9d\x84\x9e";
     bvalid = is_valid(utf8_with_surrogates, utf8_with_surrogates + 9);
     EXPECT_TRUE (bvalid);
+    bvalid = is_valid(utf8_with_surrogates);
+    EXPECT_TRUE (bvalid);
 }
 
 TEST(CheckedAPITests, test_starts_with_bom)

tests/test_cpp11.cpp

@@ -37,11 +37,24 @@ TEST(CPP11APITests, test_append)
     EXPECT_EQ (u.length(), 4);
 }
 
+TEST(CPP11APITests, test_append16)
+{
+    u16string u;
+    append16(0x0448, u);
+    EXPECT_EQ (u[0], char16_t(0x0448));
+    EXPECT_EQ (u.length(), 1);
+}
+
 TEST(CPP11APITests, test_utf16to8)
 {
     u16string utf16string = {0x41, 0x0448, 0x65e5, 0xd834, 0xdd1e};
     string u = utf16to8(utf16string);
     EXPECT_EQ (u.size(), 10);
+
+    u16string h16 = u"h!";
+    string h8;
+    utf8::unchecked::utf16to8(h16.begin(), h16.end(), std::back_inserter(h8));
+    EXPECT_EQ (h8, "h!");
 }
 
 TEST(CPP11APITests, test_utf8to16)

tests/test_cpp17.cpp

@@ -10,8 +10,8 @@ using namespace std;
 TEST(CPP17APITests, test_utf16to8)
 {
     u16string utf16string = {0x41, 0x0448, 0x65e5, 0xd834, 0xdd1e};
-    u16string_view utf16stringview(u16string);
-    string u = utf16to8(utf16string);
+    u16string_view utf16stringview(utf16string);
+    string u = utf16to8(utf16stringview);
     EXPECT_EQ (u.size(), 10);
 }
 

tests/test_cpp20.cpp

@@ -0,0 +1,77 @@
+#include "../extern/ftest/ftest.h"
+#define UTF_CPP_CPLUSPLUS 202002L
+#include "utf8.h"
+#include <string>
+using namespace utf8;
+using namespace std;
+
+TEST(CPP20APITests, test_utf16tou8)
+{
+    u16string utf16string = {0x41, 0x0448, 0x65e5, 0xd834, 0xdd1e};
+    u16string_view utf16stringview{utf16string};
+    u8string u = utf16tou8(utf16string);
+    EXPECT_EQ (u.size(), 10);
+    u = utf16tou8(utf16stringview);
+    EXPECT_EQ (u.size(), 10);
+}
+
+TEST(CPP20APITests, tes20t_utf8to16)
+{
+    u8string utf8_with_surrogates{u8"\xe6\x97\xa5\xd1\x88\xf0\x9d\x84\x9e"};
+    u16string utf16result = utf8to16(utf8_with_surrogates);
+    EXPECT_EQ (utf16result.size(), 4);
+    EXPECT_EQ (utf16result[2], 0xd834);
+    EXPECT_EQ (utf16result[3], 0xdd1e);
+}
+
+TEST(CPP20APITests, test_utf32tou8)
+{
+    u32string utf32string = {0x448, 0x65E5, 0x10346};
+    u32string_view utf32stringview{utf32string};
+    u8string utf8result = utf32tou8(utf32stringview);
+    EXPECT_EQ (utf8result.size(), 9);
+}
+
+TEST(CPP20APITests, test_utf8to32)
+{
+    u8string twochars = u8"\xe6\x97\xa5\xd1\x88";
+    u32string utf32result = utf8to32(twochars);
+    EXPECT_EQ (utf32result.size(), 2);
+}
+
+TEST(CPP20APITests, test_find_invalid)
+{
+    u8string utf_invalid = u8"\xe6\x97\xa5\xd1\x88\xfa";
+    auto invalid = find_invalid(utf_invalid);
+    EXPECT_EQ (invalid, 5);
+}
+
+TEST(CPP20APITests, test_is_valid)
+{
+    u8string utf_invalid = u8"\xe6\x97\xa5\xd1\x88\xfa";
+    bool bvalid = is_valid(utf_invalid);
+    EXPECT_FALSE (bvalid);
+    u8string utf8_with_surrogates = u8"\xe6\x97\xa5\xd1\x88\xf0\x9d\x84\x9e";
+    bvalid = is_valid(utf8_with_surrogates);
+    EXPECT_TRUE (bvalid);
+}
+
+TEST(CPP20APITests, test_replace_invalid)
+{
+    u8string invalid_sequence = u8"a\x80\xe0\xa0\xc0\xaf\xed\xa0\x80z";
+    u8string replace_invalid_result = replace_invalid(invalid_sequence, u8'?');
+    bool bvalid = is_valid(replace_invalid_result);
+    EXPECT_TRUE (bvalid);
+    const u8string fixed_invalid_sequence = u8"a????z";
+    EXPECT_EQ(fixed_invalid_sequence, replace_invalid_result);
+}
+
+TEST(CPP20APITests, test_starts_with_bom)
+{
+    u8string byte_order_mark = u8"\xef\xbb\xbf";
+    bool bbom = starts_with_bom(byte_order_mark);
+    EXPECT_TRUE (bbom);
+    u8string threechars = u8"\xf0\x90\x8d\x86\xe6\x97\xa5\xd1\x88";
+    bool no_bbom = starts_with_bom(threechars);
+    EXPECT_FALSE (no_bbom);
+}

tests/test_unchecked_api.h

@@ -40,6 +40,22 @@ TEST(UnCheckedAPITests, test_append)
     EXPECT_EQ (u[4], 0);
 }
 
+TEST(UnCheckedAPITests, test_append16)
+{
+    unsigned short u[5] = {0,0};
+    utf8::unchecked::append16(0x0448, u);
+    EXPECT_EQ (u[0], 0x0448);
+    EXPECT_EQ (u[1], 0x0000);
+
+    utf8::unchecked::append16(0x65e5, u);
+    EXPECT_EQ (u[0], 0x65e5);
+    EXPECT_EQ (u[1], 0x0000);
+
+    utf8::unchecked::append16(0x10346, u);
+    EXPECT_EQ (u[0], 0xd800);
+    EXPECT_EQ (u[1], 0xdf46);
+}
+
 TEST(UnCheckedAPITests, test_next)
 {
     const char* twochars = "\xe6\x97\xa5\xd1\x88";
@@ -64,6 +80,19 @@ TEST(UnCheckedAPITests, test_next)
     EXPECT_EQ (w, threechars + 9);
 }
 
+TEST(UnCheckedAPITests, test_next16)
+{
+    const utf8::utfchar16_t u[3] = {0x65e5, 0xd800, 0xdf46};
+    const utf8::utfchar16_t* w = u;
+    utf8::utfchar32_t cp = utf8::unchecked::next16(w);
+    EXPECT_EQ (cp, 0x65e5);
+    EXPECT_EQ (w, u + 1);
+
+    cp = utf8::unchecked::next16(w);
+    EXPECT_EQ (cp, 0x10346);
+    EXPECT_EQ (w, u + 3);
+}
+
 TEST(UnCheckedAPITests, test_peek_next)
 {
     const char* const cw = "\xe6\x97\xa5\xd1\x88";
@@ -137,6 +166,11 @@ TEST(UnCheckedAPITests, test_utf16to8)
     string utf8result;
     utf8::unchecked::utf16to8(utf16string, utf16string + 5, back_inserter(utf8result));
     EXPECT_EQ (utf8result.size(), 10);
+
+    utf8result.clear();
+    unsigned short highsurrogateonly[] = {0xd800};
+    utf8::unchecked::utf16to8(highsurrogateonly, highsurrogateonly + 1, back_inserter(utf8result));
+    EXPECT_TRUE(true); // we didn't crash
 }
 
 TEST(UnCheckedAPITests, test_utf8to16)

utf8cppConfig.cmake.in

@@ -1,6 +1,8 @@
 @PACKAGE_INIT@
 
-include("${CMAKE_CURRENT_LIST_DIR}/utf8cppTargets.cmake")
-check_required_components( "utf8cpp" )
+include("${CMAKE_CURRENT_LIST_DIR}/@PROJECT_NAME@Targets.cmake")
+check_required_components("@PROJECT_NAME@")
 
-add_library(utf8::cpp ALIAS utf8cpp)
+if(NOT TARGET utf8::cpp)
+    add_library(utf8::cpp ALIAS utf8cpp::utf8cpp)
+endif()