Merge pull request #7 from peelonet/modernization

Version 1.0.0

.github/workflows/build.yml

@@ -9,10 +9,10 @@ jobs:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
     steps:
-    - uses: actions/checkout@v2
-    - name: Build
-      uses: ashutoshvarma/action-cmake-build@master
-      with:
-        build-dir: ${{ runner.workspace }}/build
-        build-type: Release
-        run-test: true
+      - uses: actions/checkout@v4
+      - name: Build
+        uses: ashutoshvarma/action-cmake-build@master
+        with:
+          build-dir: ${{ runner.workspace }}/build
+          build-type: Release
+          run-test: true

.gitignore

@@ -1,3 +1,4 @@
+/.vscode
 /build
 /doxygen
 *.o

CMakeLists.txt

@@ -1,8 +1,8 @@
-CMAKE_MINIMUM_REQUIRED(VERSION 3.12)
+CMAKE_MINIMUM_REQUIRED(VERSION 3.6)
 
 PROJECT(
   PeeloUnicode
-  VERSION 0.2.0
+  VERSION 1.0.0
   DESCRIPTION "Header only C++ Unicode utilities."
   HOMEPAGE_URL "https://github.com/peelonet/peelo-unicode"
   LANGUAGES CXX

Doxyfile

@@ -858,7 +858,7 @@ EXCLUDE_PATTERNS       =
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories use the pattern */test/*
 
-EXCLUDE_SYMBOLS        = *::internal
+EXCLUDE_SYMBOLS        = *::utils
 
 # The EXAMPLE_PATH tag can be used to specify one or more files or directories
 # that contain example code fragments that are included (see the \include

LICENSE.md

@@ -1,13 +1,13 @@
-Copyright (c) 2018, peelo.net
+Copyright (c) 2018-2024, peelo.net
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:
 
-* Redistributions of source code must retain the above copyright notice, this
+- Redistributions of source code must retain the above copyright notice, this
   list of conditions and the following disclaimer.
 
-* Redistributions in binary form must reproduce the above copyright notice,
+- Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.
 

README.md

@@ -2,8 +2,113 @@
 
 ![Build](https://github.com/peelonet/peelo-unicode/workflows/Build/badge.svg)
 
-Collection of various Unicode related utility functions for C++17.
+Collection of simple to use [Unicode] utilities for C++17. Supports Unicode
+15.1.
 
 [Doxygen generated API documentation.][API]
 
+[Unicode]: https://en.wikipedia.org/wiki/Unicode
 [API]: https://peelonet.github.io/peelo-unicode/index.html
+
+## Character testing functions
+
+The library ships with Unicode version of [ctype.h] header, containing
+following functions inside `peelo::unicode::ctype` namespace:
+
+- `isalnum()`
+- `isalpha()`
+- `isblank()`
+- `iscntrl()`
+- `isdigit()`
+- `isgraph()`
+- `islower()`
+- `isprint()`
+- `ispunct()`
+- `isspace()`
+- `isupper()`
+- `isxdigit()`
+- `tolower()`
+- `toupper()`
+
+Additional functions not found in `ctype.h` are:
+
+- `isvalid()` - Tests whether given value is valid Unicode codepoint.
+- `isemoji()` - Tests whether given Unicode codepoint is an [emoji].
+
+[ctype.h]: https://en.cppreference.com/w/cpp/header/cctype
+[emoji]: https://en.wikipedia.org/wiki/Emoji
+
+### Example
+
+```cpp
+#include <iostream>
+#include <peelo/unicode/ctype.hpp>
+
+int
+main()
+{
+  using namespace peelo::unicode::ctype;
+
+  std::cout << isalnum(U'Ä') << std::endl;
+  std::cout << isdigit(U'൧') << std::endl;
+  std::cout << isgraph(U'€') << std::endl;
+  std::cout << ispunct(U'\u2001') << std::endl;
+  std::cout << std::hex;
+  std::cout << tolower(U'Ä') << std::endl;
+  std::cout << toupper(U'ä') << std::endl;
+}
+```
+
+## Character encodings
+
+The library also provides functions for encoding and decoding Unicode character
+encodings. Both validating and non-validating (where all encoding/decoding
+errors are ignored) functions are provided.
+
+Supported character encodings are:
+
+- [UTF-8]
+- [UTF-16BE][UTF-16]
+- [UTF-16LE][UTF-16]
+- [UTF-32BE][UTF-32]
+- [UTF-32LE][UTF-32]
+
+[UTF-8]: https://en.wikipedia.org/wiki/UTF-8
+[UTF-16]: https://en.wikipedia.org/wiki/UTF-16
+[UTF-32]: https://en.wikipedia.org/wiki/UTF-32
+
+### Example
+
+```cpp
+#include <peelo/unicode/encoding.hpp>
+
+int
+main()
+{
+  using namespace peelo::unicode::encoding;
+
+  // Decode UTF-8 input, ignoring any decoding errors.
+  std::u32string utf8_decoded = utf8::decode("\xe2\x82\xac");
+
+  // Encode it back to byte string, ignoring any encoding errors.
+  std::string utf8_encoded = utf8::encode(utf8_decoded);
+
+  // Decode UTF-32BE input with validation.
+  std::u32string utf32be_decoded;
+  if (utf32be::decode_validate("\x00\x00 \xac", utf32be_decoded))
+  {
+    // Given input is valid UTF-32BE.
+  } else {
+    // Given input is invalid UTF-32BE.
+  }
+
+  // Encode it back to byte string, with validation.
+  std::string utf32be_encoded;
+  if (utf32be::encode_validate(utf32be_decoded, utf32be_encoded))
+  {
+    // Given input contained only valid Unicode code points.
+  } else {
+    // Given input contained invalid Unicode code points.
+  }
+}
+```

include/peelo/unicode/ctype.hpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018-2020, peelo.net
+ * Copyright (c) 2018-2024, peelo.net
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -24,14 +24,14 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-#ifndef PEELO_UNICODE_CTYPE_HPP_GUARD
-#define PEELO_UNICODE_CTYPE_HPP_GUARD
+#pragma once
 
 #include <peelo/unicode/ctype/isalnum.hpp>
 #include <peelo/unicode/ctype/isalpha.hpp>
 #include <peelo/unicode/ctype/isblank.hpp>
 #include <peelo/unicode/ctype/iscntrl.hpp>
 #include <peelo/unicode/ctype/isdigit.hpp>
+#include <peelo/unicode/ctype/isemoji.hpp>
 #include <peelo/unicode/ctype/isgraph.hpp>
 #include <peelo/unicode/ctype/islower.hpp>
 #include <peelo/unicode/ctype/isprint.hpp>
@@ -42,5 +42,3 @@
 #include <peelo/unicode/ctype/isxdigit.hpp>
 #include <peelo/unicode/ctype/tolower.hpp>
 #include <peelo/unicode/ctype/toupper.hpp>
-
-#endif /* !PEELO_UNICODE_CTYPE_HPP_GUARD */

include/peelo/unicode/ctype/_utils.hpp

@@ -0,0 +1,68 @@
+/*
+ * Copyright (c) 2018-2024, peelo.net
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * * Redistributions of source code must retain the above copyright notice,
+ *   this list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright notice,
+ *   this list of conditions and the following disclaimer in the documentation
+ *   and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+#pragma once
+
+#include <array>
+#include <unordered_map>
+#include <utility>
+
+namespace peelo::unicode::ctype::utils
+{
+  using range = std::pair<char32_t, char32_t>;
+
+  template<std::size_t Size>
+  inline bool
+  table_lookup(const std::array<range, Size>& table, char32_t c)
+  {
+    const auto size = table.size();
+
+    for (std::size_t i = 0; i < size; ++i)
+    {
+      const auto& range = table[i];
+
+      if (c >= range.first && c <= range.second)
+      {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  inline char32_t
+  case_lookup(const std::unordered_map<char32_t, char32_t>& map, char32_t c)
+  {
+    const auto i = map.find(c);
+
+    if (i != std::end(map))
+    {
+      return i->second;
+    }
+
+    return c;
+  }
+}