Merge V4 branch into main (#110)

* Redefined and renamed types for code units.

* Remove -Wsign-conversion from test builds.

* find_invalid and is_valid that work with C-style strings.

* Lifted the C++11 requirement for some functions
 that take std::string as an argument.

* Support for C++20 u8string

Issue #89

* Update test docker image to 4.0.0

* Update Dockerfile to run tests with a recent gcc compiler.

* Make some internal helper functions non-template

* Add append16 function

Support for appending codepoints to existing utf16 encoded strings.

See #91

* next16

* Tests and documentation for next16

* Rewrite CMakeLists

Drop the existing CMake structure and write the new one from scratch. The root CMakeLists.txt is used for installing the package without building and running tests. Testing is done via a separate CMakeLists.txt in the tests directory.

* Remove "samples" directory.

The content of that file is already in the documentation.

* Update README.md

Restructure the reference, add installation instructions, toc, other minor changes

.circleci/config.yml

@@ -3,11 +3,11 @@ version: 2
 jobs:
   build:
     docker:
-      - image: nemtrif/utf8cpp:3.1.3
+      - image: nemtrif/utf8cpp:4.0.0
     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
+      - run: mkdir -p tests/build
+      - run: cd tests/build && cmake ..
+      - run: cd tests/build && cmake --build .
+      - run: cd tests/build && ctest -VV

CMakeLists.txt

@@ -1,67 +1,48 @@
-cmake_minimum_required (VERSION 3.0.2...3.27)
-project (utf8cpp VERSION 3.2.5 LANGUAGES CXX)
+cmake_minimum_required (VERSION 3.5...3.27)
+project (utf8cpp 
+         VERSION 4.0.0
+         LANGUAGES CXX
+         DESCRIPTION "C++ portable library for working with utf-8 encoding")
 
-if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
-    set(IS_ROOT_PROJECT ON)
-else()
-    set(IS_ROOT_PROJECT OFF)
-endif()
+add_library(${PROJECT_NAME} INTERFACE)
 
-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})
+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
+)
 
-    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)
+install(DIRECTORY ${PROJECT_SOURCE_DIR}/source/utf8 DESTINATION include)

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"