### Example of Use

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Demonstrates the usage of the utf8::unchecked::iterator with various operations.

```APIDOC
## Example of Use

```cpp
char* threechars = "\xf0\x90\x8d\x86\xe6\x97\xa5\xd1\x88";
utf8::unchecked::iterator<char*> un_it(threechars);
utf8::unchecked::iterator<char*> un_it2 = un_it;
assert (un_it2 == un_it);
assert (*un_it == 0x10346);
assert (*(++un_it) == 0x65e5);
assert ((*un_it++) == 0x65e5);
assert (*un_it == 0x0448);
assert (un_it != un_it2);
utf8::::unchecked::iterator<char*> un_endit (threechars + 9);  
assert (++un_it == un_endit);
assert (*(--un_it) == 0x0448);
assert ((*un_it--) == 0x0448);
assert (*un_it == 0x65e5);
assert (--un_it == utf8::unchecked::iterator<char*>(threechars));
assert (*un_it == 0x10346);
```
```

--------------------------------

### bool starts_with_bom(std::string_view s)

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Checks if a given `std::string_view` starts with a UTF-8 byte order mark (BOM).

```APIDOC
## bool starts_with_bom(std::string_view s)

### Description
Checks whether a string starts with a UTF-8 byte order mark (BOM).

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **s** (std::string_view): A UTF-8 encoded string.

### Request Example
```cpp
string byte_order_mark = {char(0xef), char(0xbb), char(0xbf)};
string_view byte_order_mark_view(byte_order_mark);
bool bbom = starts_with_bom(byte_order_mark_view);
assert (bbom);
string_view threechars = "\xf0\x90\x8d\x86\xe6\x97\xa5\xd1\x88";
bool no_bbom = starts_with_bom(threechars);
assert (!no_bbom);
```

### Response
#### Success Response (200)
- **return value** (bool): `true` if the string starts with a UTF-8 byte order mark; `false` if not.

#### Response Example
```json
{
  "example": true
}
```
```

--------------------------------

### bool starts_with_bom(const std::string& s)

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Checks if a given `std::string` starts with a UTF-8 byte order mark (BOM).

```APIDOC
## bool starts_with_bom(const std::string& s)

### Description
Checks whether a string starts with a UTF-8 byte order mark (BOM).

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **s** (const std::string&): A UTF-8 encoded string.

### Request Example
```cpp
string byte_order_mark = {char(0xef), char(0xbb), char(0xbf)};
bool bbom = starts_with_bom(byte_order_mark);
assert (bbom == true);
string threechars = "\xf0\x90\x8d\x86\xe6\x97\xa5\xd1\x88";
bool no_bbom = starts_with_bom(threechars);
assert (no_bbom == false);
```

### Response
#### Success Response (200)
- **return value** (bool): `true` if the string starts with a UTF-8 byte order mark; `false` if not.

#### Response Example
```json
{
  "example": true
}
```
```

--------------------------------

### Get Prior UTF-8 Code Point

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

This function moves an iterator backward to the beginning of the previous UTF-8 code point and returns its 32-bit representation. Use the `start` iterator as a safeguard against going past the beginning of the sequence. Be aware that this function may skip superfluous trail octets and might not detect all invalid UTF-8 sequences.

```cpp
template <typename octet_iterator>
utfchar32_t prior(octet_iterator& it, octet_iterator start);

char* twochars = "\xe6\x97\xa5\xd1\x88";
unsigned char* w = twochars + 3;
int cp = prior (w, twochars);
assert (cp == 0x65e5);
assert (w == twochars);
```

--------------------------------

### Catch utf8::exception in C++

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Example of how to catch a general utf8::exception. This is useful for handling any errors originating from the UTF CPP library.

```cpp
try {
  code_that_uses_utf_cpp_library();
}
catch(const utf8::exception& utfcpp_ex) {
  cerr << utfcpp_ex.what();
}
```

--------------------------------

### utf8::prior

Source: https://context7.com/nemtrif/utfcpp/llms.txt

Moves the bidirectional iterator backward to the start of the previous UTF-8 code point and returns its 32-bit value. `start` acts as a boundary. Throws `utf8::not_enough_room` or `utf8::invalid_utf8`.

```APIDOC
## utf8::prior

### Description
Decrements a bidirectional iterator to the start of the previous UTF-8 encoded code point and returns its 32-bit value. `start` is a safety boundary to prevent going past the beginning. Throws `utf8::not_enough_room` if already at `start`, or `utf8::invalid_utf8` on malformed sequences.

### Parameters
- `it` (iterator) - The current iterator position (will be decremented).
- `start` (iterator) - The beginning iterator of the sequence, used as a boundary.

### Returns
- `uint32_t` - The decoded 32-bit Unicode code point.

### Throws
- `utf8::not_enough_room` - If the iterator is already at `start`.
- `utf8::invalid_utf8` - If the sequence is malformed.

### Example
```cpp
#include "utf8.h"
#include <string>
#include <cassert>

int main() {
    std::string text = "\xe6\x97\x85\xd1\x88";  // '日ш'
    auto it = text.end();

    uint32_t cp2 = utf8::prior(it, text.begin());
    assert(cp2 == 0x0448);  // 'ш' — last code point
    assert(it == text.begin() + 3);

    uint32_t cp1 = utf8::prior(it, text.begin());
    assert(cp1 == 0x65e5);  // '日' — first code point
    assert(it == text.begin());
}
```
```

--------------------------------

### Set Minimum CMake Version and Project Name

Source: https://github.com/nemtrif/utfcpp/blob/master/bench/CMakeLists.txt

Specifies the minimum required CMake version and defines the project name. This is a standard starting point for most CMake projects.

```cmake
cmake_minimum_required (VERSION 3.5)
project(utfcppbench LANGUAGES CXX)
```

--------------------------------

### Move Backward and Decode Previous UTF-8 Code Point with utf8::prior

Source: https://context7.com/nemtrif/utfcpp/llms.txt

Decrements a bidirectional iterator to the start of the previous UTF-8 code point and returns its value. `start` acts as a boundary. Throws exceptions for invalid sequences or exceeding the boundary.

```cpp
#include "utf8.h"
#include <string>
#include <cassert>

int main() {
    std::string text = "\xe6\x97\xa5\xd1\x88";  // '日ш'
    auto it = text.end();

    // Walk backward through code points
    uint32_t cp2 = utf8::prior(it, text.begin());
    assert(cp2 == 0x0448);  // 'ш' — last code point
    assert(it == text.begin() + 3);

    uint32_t cp1 = utf8::prior(it, text.begin());
    assert(cp1 == 0x65e5);  // '日' — first code point
    assert(it == text.begin());
}
```

--------------------------------

### UTF-8 Iterator Usage Example

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Demonstrates the usage of the utf8::iterator class for iterating through a UTF-8 encoded C-style string. It shows initialization, comparison, dereferencing, and increment/decrement operations.

```cpp
char* threechars = "\xf0\x90\x8d\x86\xe6\x97\xa5\xd1\x88";
utf8::iterator<char*> it(threechars, threechars, threechars + 9);
utf8::iterator<char*> it2 = it;
assert (it2 == it);
assert (*it == 0x10346);
assert (*(++it) == 0x65e5);
assert ((*it++) == 0x65e5);
assert (*it == 0x0448);
assert (it != it2);
utf8::iterator<char*> endit (threechars + 9, threechars, threechars + 9);  
assert (++it == endit);
assert (*(--it) == 0x0448);
assert ((*it--) == 0x0448);
assert (*it == 0x65e5);
assert (--it == utf8::iterator<char*>(threechars, threechars, threechars + 9));
assert (*it == 0x10346);
```

--------------------------------

### Unchecked Append UTF-8 Example

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Appends a 32-bit code point to a UTF-8 sequence using the unchecked::append function. This is a faster but less safe alternative to utf8::append, as it does not validate the code point.

```cpp
unsigned char u[5] = {0,0,0,0,0};
unsigned char* end = unchecked::append(0x0448, u);
assert (u[0] == 0xd1 && u[1] == 0x88 && u[2] == 0 && u[3] == 0 && u[4] == 0);
```

--------------------------------

### Unchecked Append UTF-16 Example

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Appends a 32-bit code point to a UTF-16 sequence using the unchecked::append16 function. This is a faster but less safe alternative to utf8::append16, as it does not validate the code point.

```cpp
unsigned short u[5] = {0,0};
utf8::unchecked::append16(0x0448, u);
assert(u[0], 0x0448);
assert(u[1], 0x0000);
```

--------------------------------

### Peek Next UTF-8 Code Point

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Use this function to get the code point for the next UTF-8 sequence without advancing the iterator. Ensure the iterator does not reach the end during extraction to avoid `utf8::not_enough_room` exceptions.

```cpp
template <typename octet_iterator>
utfchar32_t peek_next(octet_iterator it, octet_iterator end);

char* twochars = "\xe6\x97\xa5\xd1\x88";
char* w = twochars;
int cp = peek_next(w, twochars + 6);
assert (cp == 0x65e5);
assert (w == twochars);
```

--------------------------------

### Get Next UTF-8 Code Point (C++)

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Reads a UTF-8 encoded code point from an iterator, returning its 32-bit representation and advancing the iterator. Throws `utf8::not_enough_room` if the end of the sequence is reached prematurely or `utf8::invalid_utf8` for malformed sequences.

```cpp
template <typename octet_iterator>
utfchar32_t next(octet_iterator& it, octet_iterator end);
```

```cpp
char* twochars = "\xe6\x97\xa5\xd1\x88";
char* w = twochars;
int cp = next(w, twochars + 6);
assert (cp == 0x65e5);
assert (w == twochars + 3);
```

--------------------------------

### Define Benchmark Executable

Source: https://github.com/nemtrif/utfcpp/blob/master/bench/CMakeLists.txt

Creates an executable target named 'benchmark' from the 'benchmark.cpp' source file. This is the main program for running benchmarks.

```cmake
add_executable(benchmark benchmark.cpp)
```

--------------------------------

### next

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Given an iterator to the beginning of a UTF-8 sequence, this function returns the code point and advances the iterator to the next position. It can throw `utf8::not_enough_room` or `utf8::invalid_utf8` exceptions.

```APIDOC
## next

### Description
Given the iterator to the beginning of the UTF-8 sequence, it returns the code point and moves the iterator to the next position.

### Signature
```cpp
template <typename octet_iterator>
utfchar32_t next(octet_iterator& it, octet_iterator end);
```

### Parameters
* `octet_iterator` (Input Iterator): An input iterator.
* `it` (Reference to Input Iterator): A reference to an iterator pointing to the beginning of an UTF-8 encoded code point. After the function returns, it is incremented to point to the beginning of the next code point.
* `end` (Input Iterator): End of the UTF-8 sequence to be processed.

### Return Value
The 32 bit representation of the processed UTF-8 code point.

### Exceptions
* `utf8::not_enough_room`: Thrown if `it` gets equal to `end` during the extraction of a code point.
* `utf8::invalid_utf8`: Thrown in case of an invalid UTF-8 sequence.

### Example
```cpp
char* twochars = "\xe6\x97\xa5\xd1\x88";
char* w = twochars;
int cp = next(w, twochars + 6);
assert (cp == 0x65e5);
assert (w == twochars + 3);
```
```

--------------------------------

### Get Previous UTF-8 Code Point (Unchecked)

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Decrements an iterator to the beginning of the previous UTF-8 code point and returns its value. Offers no boundary checking.

```cpp
template <typename octet_iterator>
utfchar32_t prior(octet_iterator& it);
```

```cpp
char* twochars = "\xe6\x97\xa5\xd1\x88";
char* w = twochars + 3;
int cp = unchecked::prior (w);
assert (cp == 0x65e5);
assert (w == twochars);
```

--------------------------------

### bool starts_with_bom(octet_iterator it, octet_iterator end)

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Checks if an octet sequence, defined by iterators, begins with a UTF-8 byte order mark (BOM).

```APIDOC
## bool starts_with_bom (octet_iterator it, octet_iterator end)

### Description
Checks whether an octet sequence starts with a UTF-8 byte order mark (BOM).

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **it** (octet_iterator): Beginning of the octet sequence to check.
- **end** (octet_iterator): Pass-end of the sequence to check.

### Request Example
```cpp
unsigned char byte_order_mark[] = {0xef, 0xbb, 0xbf};
bool bbom = starts_with_bom(byte_order_mark, byte_order_mark + sizeof(byte_order_mark));
assert (bbom == true);
```

### Response
#### Success Response (200)
- **return value** (bool): `true` if the sequence starts with a UTF-8 byte order mark; `false` if not.

#### Response Example
```json
{
  "example": true
}
```
```

--------------------------------

### Get Next UTF-16 Code Point (Unchecked)

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Retrieves the next code point from a UTF-16 sequence and advances the iterator. Use when UTF-16 validity is guaranteed for performance.

```cpp
template <typename word_iterator>
utfchar32_t next16(word_iterator& it);
```

```cpp
const unsigned short u[3] = {0x65e5, 0xd800, 0xdf46};
const unsigned short* w = u;
int cp = unchecked::next16(w);
assert (cp, 0x65e5);
assert (w, u + 1);
```

--------------------------------

### Include Project Source Directories

Source: https://github.com/nemtrif/utfcpp/blob/master/bench/CMakeLists.txt

Adds the 'source' directory from the parent directory to the include paths. This allows the compiler to find header files in that location.

```cmake
include_directories("${PROJECT_SOURCE_DIR}/../source")
```

--------------------------------

### Get Next UTF-8 Code Point (Unchecked)

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Retrieves the next code point from a UTF-8 sequence and advances the iterator. Use when UTF-8 validity is guaranteed for performance.

```cpp
template <typename octet_iterator>
utfchar32_t next(octet_iterator& it);
```

```cpp
char* twochars = "\xe6\x97\xa5\xd1\x88";
char* w = twochars;
int cp = unchecked::next(w);
assert (cp == 0x65e5);
assert (w == twochars + 3);
```

--------------------------------

### bool is_valid(octet_iterator start, octet_iterator end)

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Checks whether a sequence of octets is a valid UTF-8 string using iterators. Returns true if valid, false otherwise.

```APIDOC
## bool is_valid(octet_iterator start, octet_iterator end)

### Description
Checks whether a sequence of octets is a valid UTF-8 string.

### Parameters
#### Path Parameters
- **start** (octet_iterator) - Required - An iterator pointing to the beginning of the UTF-8 string to test for validity.
- **end** (octet_iterator) - Required - An iterator pointing to pass-the-end of the UTF-8 string to test for validity.

### Return Value
`true` if the sequence is a valid UTF-8 string; `false` if not.

### Example
```cpp
char utf_invalid[] = "\xe6\x97\xa5\xd1\x88\xfa";
bool bvalid = is_valid(utf_invalid, utf_invalid + 6);
assert (bvalid == false);
```
```

--------------------------------

### Include UTF8-CPP Library

Source: https://context7.com/nemtrif/utfcpp/llms.txt

Include the main header file for the UTF8-CPP library. To force a specific C++ standard level, define UTF_CPP_CPLUSPLUS before including the header.

```cpp
#include "utf8.h"
```

```cpp
#define UTF_CPP_CPLUSPLUS 201703L  // Force C++17 API
#include "utf8.h"
```

--------------------------------

### UTF-8 Iterator with std::string

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Shows how to initialize a utf8::iterator using the begin and end iterators of a std::string. This allows STL algorithms to be used with UTF-8 encoded strings.

```cpp
std::string s = "example";
utf8::iterator i (s.begin(), s.begin(), s.end());
```

--------------------------------

### Calculate distance between UTF-8 code points (unchecked)

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Use this function to get the number of code points between two iterators in a UTF-8 sequence. It is faster but does not validate the UTF-8 sequence.

```cpp
template <typename octet_iterator>
typename std::iterator_traits<octet_iterator>::difference_type distance (octet_iterator first, octet_iterator last);
```

```cpp
char* twochars = "\xe6\x97\xa5\xd1\x88";
size_t dist = utf8::unchecked::distance(twochars, twochars + 5);
assert (dist == 2);
```

--------------------------------

### octet_iterator find_invalid(octet_iterator start, octet_iterator end)

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Detects an invalid sequence within a UTF-8 string using iterators. Returns an iterator to the first invalid octet or the end iterator if none are found.

```APIDOC
## octet_iterator find_invalid(octet_iterator start, octet_iterator end)

### Description
Detects an invalid sequence within a UTF-8 string.

### Parameters
#### Path Parameters
- **start** (octet_iterator) - Required - An iterator pointing to the beginning of the UTF-8 string to test for validity.
- **end** (octet_iterator) - Required - An iterator pointing to pass-the-end of the UTF-8 string to test for validity.

### Return Value
An iterator pointing to the first invalid octet in the UTF-8 string. In case none were found, equals `end`.

### Example
```cpp
char utf_invalid[] = "\xe6\x97\xa5\xd1\x88\xfa";
char* invalid = find_invalid(utf_invalid, utf_invalid + 6);
assert (invalid == utf_invalid + 5);
```
```

--------------------------------

### Detect UTF-8 Byte Order Mark (BOM)

Source: https://context7.com/nemtrif/utfcpp/llms.txt

Use `utf8::starts_with_bom` to check if a string begins with the UTF-8 BOM sequence (0xEF 0xBB 0xBF). This is useful for processing files saved with a BOM. Available for iterators, `std::string`, and `string_view`.

```cpp
#include "utf8.h"
#include <string>
#include <fstream>
#include <cassert>

// Read a UTF-8 file, skipping any BOM
std::string read_utf8_file(const std::string& path) {
    std::ifstream f(path, std::ios::binary);
    std::string content((std::istreambuf_iterator<char>(f)),
                         std::istreambuf_iterator<char>());
    if (utf8::starts_with_bom(content)) {
        content.erase(0, 3);  // Remove the 3-byte BOM
    }
    return content;
}

int main() {
    // Iterator form
    unsigned char bom[] = {0xef, 0xbb, 0xbf};
    assert(utf8::starts_with_bom(bom, bom + 3) == true);

    // std::string form
    std::string with_bom = {char(0xef), char(0xbb), char(0xbf), 'H', 'i'};
    assert(utf8::starts_with_bom(with_bom) == true);

    std::string no_bom = "Hello, World!";
    assert(utf8::starts_with_bom(no_bom) == false);

    // C++17 string_view form
    std::string_view sv(with_bom);
    assert(utf8::starts_with_bom(sv) == true);
}
```

--------------------------------

### Convert UTF-8 to UTF-16 (Pre-C++11)

Source: https://github.com/nemtrif/utfcpp/blob/master/README.md

Demonstrates converting a UTF-8 encoded string to UTF-16 using iterators and a back inserter for older C++ compilers.

```cpp
    vector<unsigned short> utf16line;
    utf8::utf8to16(line.begin(), end_it, back_inserter(utf16line));
```

--------------------------------

### utf8::starts_with_bom

Source: https://context7.com/nemtrif/utfcpp/llms.txt

Detects if a string begins with the UTF-8 Byte Order Mark (BOM) sequence (0xEF 0xBB 0xBF). This function is available for iterators, std::string, and string_view.

```APIDOC
## utf8::starts_with_bom

### Description
Checks whether a string begins with the UTF-8 BOM sequence (`0xEF 0xBB 0xBF`). Typically used when reading files that may have been saved with a BOM by Windows editors. Available in iterator (v2.3+), `std::string` (v3.0+), and `string_view` (v3.2+) forms.

### Method
`bool utf8::starts_with_bom(InputIterator first, InputIterator last)`
`bool utf8::starts_with_bom(const std::string& str)`
`bool utf8::starts_with_bom(std::string_view str)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```cpp
#include "utf8.h"
#include <string>
#include <fstream>
#include <cassert>

// Iterator form
unsigned char bom[] = {0xef, 0xbb, 0xbf};
assert(utf8::starts_with_bom(bom, bom + 3) == true);

// std::string form
std::string with_bom = {char(0xef), char(0xbb), char(0xbf), 'H', 'i'};
assert(utf8::starts_with_bom(with_bom) == true);

std::string no_bom = "Hello, World!";
assert(utf8::starts_with_bom(no_bom) == false);

// C++17 string_view form
std::string_view sv(with_bom);
assert(utf8::starts_with_bom(sv) == true);
```

### Response
#### Success Response (200)
Returns `true` if the string starts with a UTF-8 BOM, `false` otherwise.

#### Response Example
```json
{
  "example": "boolean (true/false)"
}
```
```

--------------------------------

### output_iterator replace_invalid(octet_iterator start, octet_iterator end, output_iterator out)

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Replaces all invalid UTF-8 sequences within a specified range with the default replacement character (U+FFFD). This function creates a new sequence with replacements, it does not modify the original range.

```APIDOC
## output_iterator replace_invalid(octet_iterator start, octet_iterator end, output_iterator out)

### Description
Replaces all invalid UTF-8 sequences within a specified range with the default replacement character (U+FFFD). This function creates a new sequence with replacements, it does not modify the original range.

### Parameters
#### Path Parameters
- **start** (octet_iterator) - Required - An iterator pointing to the beginning of the UTF-8 string to process.
- **end** (octet_iterator) - Required - An iterator pointing to the end of the UTF-8 string to process.
- **out** (output_iterator) - Required - An output iterator to the range where the result of replacement is stored. This range must not overlap with the input range `[start, end]`.

### Return Value
- **output_iterator** - An iterator pointing to the place after the UTF-8 string with replaced invalid sequences.

### Example
```cpp
char invalid_sequence[] = "a\x80\xe0\xa0\xc0\xaf\xed\xa0\x80z";
vector<char> replace_invalid_result;
replace_invalid (invalid_sequence, invalid_sequence + sizeof(invalid_sequence), back_inserter(replace_invalid_result)); // Uses default replacement U+FFFD
bvalid = is_valid(replace_invalid_result.begin(), replace_invalid_result.end());
assert (bvalid);
```
```

--------------------------------

### next16

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Given an iterator to the beginning of a UTF-16 sequence, this function returns the code point and advances the iterator to the next position. It can throw `utf8::not_enough_room` or `utf8::invalid_utf8` exceptions.

```APIDOC
## next16

### Description
Given the iterator to the beginning of the UTF-16 sequence, it returns the code point and moves the iterator to the next position.

### Signature
```cpp
template <typename word_iterator>
utfchar32_t next16(word_iterator& it, word_iterator end);
```

### Parameters
* `word_iterator` (Input Iterator): An input iterator.
* `it` (Reference to Input Iterator): A reference to an iterator pointing to the beginning of an UTF-16 encoded code point. After the function returns, it is incremented to point to the beginning of the next code point.
* `end` (Input Iterator): End of the UTF-16 sequence to be processed.

### Return Value
The 32 bit representation of the processed UTF-16 code point.

### Exceptions
* `utf8::not_enough_room`: Thrown if `it` gets equal to `end` during the extraction of a code point.
* `utf8::invalid_utf8`: Thrown in case of an invalid UTF-16 sequence.

### Example
```cpp
const unsigned short u[3] = {0x65e5, 0xd800, 0xdf46};
const unsigned short* w = u;
int cp = next16(w, w + 3);
assert (cp, 0x65e5);
assert (w, u + 1);
```
```

--------------------------------

### Define utf8::invalid_utf16 Exception

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Thrown by `utf16to8` if an invalid UTF-16 sequence is found. The `utf16_word()` member function returns the problematic UTF-16 code unit.

```cpp
class invalid_utf16 : public exception {
public:
    utfchar16_t utf16_word() const;
};
```

--------------------------------

### Check for UTF-8 BOM in std::string

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

This function checks if a given std::string starts with a UTF-8 Byte Order Mark (BOM). It's a convenient way to detect BOMs in string data, especially when dealing with file content.

```cpp
bool starts_with_bom(const std::string& s);
```

```cpp
string byte_order_mark = {char(0xef), char(0xbb), char(0xbf)};
bool bbom = starts_with_bom(byte_order_mark);
assert (bbom == true);
string threechars = "\xf0\x90\x8d\x86\xe6\x97\xa5\xd1\x88";
bool no_bbom = starts_with_bom(threechars);
assert (no_bbom == false);
```

--------------------------------

### Perform Fast UTF-8 Operations with `utf8::unchecked` Functions

Source: https://context7.com/nemtrif/utfcpp/llms.txt

Use functions in the `utf8::unchecked` namespace for high-performance UTF-8 processing when input validity is guaranteed. These functions omit checks and boundary enforcement, leading to undefined behavior on invalid input.

```cpp
#include "utf8.h"
#include <cassert>

int main() {
    const char* twochars = "\xe6\x97\xa5\xd1\x88";  // '日ш'

    // next: advance and decode
    const char* w = twochars;
    uint32_t cp = utf8::unchecked::next(w);
    assert(cp == 0x65e5 && w == twochars + 3);

    // peek_next: decode without advancing
    w = twochars;
    assert(utf8::unchecked::peek_next(w) == 0x65e5);
    assert(w == twochars);  // unchanged

    // prior: reverse decode
    w = twochars + 3;
    cp = utf8::unchecked::prior(w);
    assert(cp == 0x65e5 && w == twochars);

    // advance by N code points
    w = twochars;
    utf8::unchecked::advance(w, 2);
    assert(w == twochars + 5);

    // distance: count code points
    size_t dist = utf8::unchecked::distance(twochars, twochars + 5);
    assert(dist == 2);
}
```

```cpp
#include "utf8.h"
#include <vector>
#include <cassert>

int main() {
    // Validate first, then use unchecked conversions for performance
    const char* utf8_src = "\xe6\x97\xa5\xd1\x88\xf0\x9d\x84\x9e";
    assert(utf8::is_valid(utf8_src, utf8_src + 9));

    // UTF-8 → UTF-16
    std::vector<unsigned short> utf16;
    utf8::unchecked::utf8to16(utf8_src, utf8_src + 9, std::back_inserter(utf16));
    assert(utf16.size() == 4);
    assert(utf16[2] == 0xd834 && utf16[3] == 0xdd1e);  // surrogate pair

    // UTF-16 → UTF-8
    std::vector<unsigned char> utf8_back;
    utf8::unchecked::utf16to8(utf16.begin(), utf16.end(), std::back_inserter(utf8_back));
    assert(utf8_back.size() == 9);

    // UTF-8 → UTF-32
    std::vector<uint32_t> utf32;
    utf8::unchecked::utf8to32(utf8_src, utf8_src + 9, std::back_inserter(utf32));
    assert(utf32.size() == 3);

    // UTF-32 → UTF-8
    int utf32raw[] = {0x448, 0x65E5, 0x10346};
    std::vector<unsigned char> utf8_from32;
    utf8::unchecked::utf32to8(utf32raw, utf32raw + 3, std::back_inserter(utf8_from32));
    assert(utf8_from32.size() == 9);
}
```

--------------------------------

### output_iterator replace_invalid(octet_iterator start, octet_iterator end, output_iterator out, utfchar32_t replacement)

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Replaces all invalid UTF-8 sequences within a specified range with a given replacement character. This function creates a new sequence with replacements, it does not modify the original range.

```APIDOC
## output_iterator replace_invalid(octet_iterator start, octet_iterator end, output_iterator out, utfchar32_t replacement)

### Description
Replaces all invalid UTF-8 sequences within a specified range with a given replacement character. This function creates a new sequence with replacements, it does not modify the original range.

### Parameters
#### Path Parameters
- **start** (octet_iterator) - Required - An iterator pointing to the beginning of the UTF-8 string to process.
- **end** (octet_iterator) - Required - An iterator pointing to the end of the UTF-8 string to process.
- **out** (output_iterator) - Required - An output iterator to the range where the result of replacement is stored. This range must not overlap with the input range `[start, end]`.
- **replacement** (utfchar32_t) - Required - A Unicode code point for the replacement marker.

### Return Value
- **output_iterator** - An iterator pointing to the place after the UTF-8 string with replaced invalid sequences.

### Example
```cpp
char invalid_sequence[] = "a\x80\xe0\xa0\xc0\xaf\xed\xa0\x80z";
vector<char> replace_invalid_result;
replace_invalid (invalid_sequence, invalid_sequence + sizeof(invalid_sequence), back_inserter(replace_invalid_result), '?');
bvalid = is_valid(replace_invalid_result.begin(), replace_invalid_result.end());
assert (bvalid);
char* fixed_invalid_sequence = "a????z";
assert (std::equal(replace_invalid_result.begin(), replace_invalid_result.end(), fixed_invalid_sequence));
```
```

--------------------------------

### Get Next UTF-16 Code Point (C++)

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Reads a UTF-16 encoded code point from an iterator, returning its 32-bit representation and advancing the iterator. Throws `utf8::not_enough_room` if the end of the sequence is reached prematurely or `utf8::invalid_utf8` for malformed sequences.

```cpp
template <typename word_iterator>
utfchar32_t next16(word_iterator& it, word_iterator end);
```

```cpp
const unsigned short u[3] = {0x65e5, 0xd800, 0xdf46};
const unsigned short* w = u;
int cp = next16(w, w + 3);
assert (cp, 0x65e5);
assert (w, u + 1);
```

--------------------------------

### Convert UTF-8 to UTF-16 (C++11 and later)

Source: https://github.com/nemtrif/utfcpp/blob/master/README.md

Shows the modern C++11 approach to converting a UTF-8 encoded string to UTF-16 using a direct function call that returns a `u16string`.

```cpp
    u16string utf16line = utf8::utf8to16(line);
```

--------------------------------

### Set C++ Standard for Benchmark Executable

Source: https://github.com/nemtrif/utfcpp/blob/master/bench/CMakeLists.txt

Configures the benchmark executable to use C++11 standard, ensuring it's required and disabling compiler extensions. This guarantees consistent language behavior across different compilers.

```cmake
set_target_properties(benchmark
                      PROPERTIES
                      CXX_STANDARD 11
                      CXX_STANDARD_REQUIRED YES
                      CXX_EXTENSIONS NO)
```

--------------------------------

### Unchecked STL Iterator Adapter for UTF-8 Strings

Source: https://context7.com/nemtrif/utfcpp/llms.txt

Use `utf8::unchecked::iterator` for faster iteration over strings that have already been validated for UTF-8 encoding. It does not perform range or validity checks, making it suitable for performance-sensitive loops. This example demonstrates forward and backward iteration, as well as usage with `std::string`.

```cpp
#include "utf8.h"
#include <string>
#include <cassert>

int main() {
    const char* threechars = "\xf0\x90\x8d\x86\xe6\x97\xa5\xd1\x88";
    // U+10346, U+65E5, U+0448 — 9 bytes total

    utf8::unchecked::iterator<const char*> it(threechars);
    utf8::unchecked::iterator<const char*> end(threechars + 9);

    assert(*it == 0x10346);
    assert(*(++it) == 0x65e5);
    assert(*(++it) == 0x0448);
    ++it;
    assert(it == end);

    // Backward iteration
    --it;
    assert(*it == 0x0448);

    // With std::string
    std::string s = "Hello";
    utf8::unchecked::iterator<std::string::const_iterator> sit(s.begin());
    utf8::unchecked::iterator<std::string::const_iterator> send(s.end());
    int count = 0;
    for (; sit != send; ++sit) ++count;
    assert(count == 5);
}
```

--------------------------------

### Convert UTF-32 to UTF-8 (std::u32string_view to std::u8string)

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Converts a UTF-32 encoded `std::u32string_view` to a UTF-8 encoded `std::u8string`. Requires C++20. Throws `utf8::invalid_code_point` on invalid input.

```cpp
std::u8string utf32to8(const std::u32string_view& s);

```

```cpp
u32string utf32string = {0x448, 0x65E5, 0x10346};
u32string_view utf32stringview(utf32string);
u8string utf8result = utf32to8(utf32stringview);
assert (utf8result.size() == 9);

```

--------------------------------

### Convert UTF-32 to UTF-8 using utf8::utf32to8

Source: https://context7.com/nemtrif/utfcpp/llms.txt

Converts UTF-32 data to UTF-8. Supports C++11 API with std::u32string, C++17 string_view, and iterator-based conversions. Throws utf8::invalid_code_point for invalid Unicode ranges.

```cpp
#include "utf8.h"
#include <string>
#include <vector>
#include <cassert>

int main() {
    // C++11 API
    std::u32string utf32 = {0x0448, 0x65E5, 0x10346};
    // 'ш' (2 bytes) + '日' (3 bytes) + Gothic letter (4 bytes)
    std::string utf8 = utf8::utf32to8(utf32);
    assert(utf8.size() == 9);

    // C++17 string_view
    std::u32string_view sv(utf32);
    std::string utf8_sv = utf8::utf32to8(sv);
    assert(utf8_sv == utf8);

    // Iterator API: from raw int array
    int raw32[] = {0x448, 0x65E5, 0x10346};
    std::vector<unsigned char> out;
    utf8::utf32to8(raw32, raw32 + 3, std::back_inserter(out));
    assert(out.size() == 9);
}
```

--------------------------------

### Advance UTF-8 Iterator by N Code Points with utf8::advance

Source: https://context7.com/nemtrif/utfcpp/llms.txt

Advances a UTF-8 iterator forward or backward by a specified number of code points. Throws `utf8::not_enough_room` or `utf8::invalid_code_point` if the range is exceeded.

```cpp
#include "utf8.h"
#include <string>
#include <cassert>

int main() {
    std::string text = "\xe6\x97\xa5\xd1\x88";  // '日ш' — 5 bytes, 2 code points
    auto it = text.begin();

    utf8::advance(it, 2, text.end());
    assert(it == text.end());  // moved forward 2 code points

    utf8::advance(it, -2, text.begin());
    assert(it == text.begin());  // moved backward 2 code points

    // Skip to the 3rd code point in a longer string
    std::string lorem = "Hello, 世界!";
    auto pos = lorem.begin();
    utf8::advance(pos, 7, lorem.end());  // jump to '世'
    uint32_t cp = utf8::next(pos, lorem.end());
    assert(cp == 0x4e16);  // '世'
}
```

--------------------------------

### Convert UTF-32 to UTF-8 (std::u32string to std::u8string)

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Converts a UTF-32 encoded `std::u32string` to a UTF-8 encoded `std::u8string`. Requires C++20. Throws `utf8::invalid_code_point` on invalid input.

```cpp
std::u8string utf32to8(const std::u32string& s);

```

```cpp
u32string utf32string = {0x448, 0x65E5, 0x10346};
u8string utf8result = utf32to8(utf32string);
assert (utf8result.size() == 9);

```

--------------------------------

### Convert UTF-16 to UTF-8 (std::u16string_view)

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Converts a UTF-16 encoded `std::u16string_view` to a UTF-8 encoded `std::string`. Requires a C++17 compliant compiler. Throws `utf8::invalid_utf16` for invalid sequences.

```cpp
std::string utf16to8(std::u16string_view s);
```

```cpp
u16string utf16string = {0x41, 0x0448, 0x65e5, 0xd834, 0xdd1e};
u16string_view utf16stringview(u16string);
string u = utf16to8(utf16string);
assert (u.size() == 10);
```

--------------------------------

### utf8to32 (u8string_view version)

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Converts a UTF-8 encoded std::u8string_view to std::u32string. Throws `utf8::invalid_utf8` on invalid input.

```APIDOC
## std::u32string utf8to32(const std::u8string_view& s)

### Description
Converts a UTF-8 encoded string to UTF-32.

### Parameters
#### Path Parameters
- **s** (const std::u8string_view&) - Required - A UTF-8 encoded string view.

### Response
#### Success Response (200)
- **return value** (std::u32string) - A UTF-32 encoded string.

### Exceptions
- `utf8::invalid_utf8`: Thrown if the input UTF-8 string is invalid.
```

--------------------------------

### Configure Compiler Warnings for MSVC and GCC/Clang

Source: https://github.com/nemtrif/utfcpp/blob/master/bench/CMakeLists.txt

Sets compiler warning levels. For MSVC, it sets warning level 4. For other compilers like GCC and Clang, it enables additional warnings for stricter code checking.

```cmake
if (MSVC)
    # warning level 4
    add_compile_options(/W4)
else()
    # additional warnings
    add_compile_options(-Wall -Wextra -Wpedantic -Wconversion -Wsign-conversion)
endif()
```

--------------------------------

### Define utf8::not_enough_room Exception

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Indicates that the end of a decoded UTF-8 sequence was reached before a complete code point could be determined. This exception inherits from `utf8::exception`.

```cpp
class not_enough_room : public exception {};
```

--------------------------------

### utf8::next16

Source: https://context7.com/nemtrif/utfcpp/llms.txt

Reads the next UTF-16 code point, handling surrogate pairs, and returns its 32-bit Unicode value. Advances the iterator. Throws `utf8::not_enough_room` on truncated sequences.

```APIDOC
## utf8::next16

### Description
Reads a UTF-16 encoded code point at the current iterator, handling surrogate pairs, and returns its 32-bit Unicode value. Throws `utf8::not_enough_room` on truncated sequences.

### Parameters
- `it` (iterator) - The current iterator position.
- `end` (iterator) - The end iterator of the sequence.

### Returns
- `uint32_t` - The decoded 32-bit Unicode code point.

### Throws
- `utf8::not_enough_room` - If the sequence is truncated.

### Example
```cpp
#include "utf8.h"
#include <cassert>

int main() {
    const unsigned short u[] = {0x65e5, 0xD800, 0xDF46}; // '日' + supplementary char
    const unsigned short* w = u;

    uint32_t cp1 = utf8::next16(w, w + 3);
    assert(cp1 == 0x65e5);  // '日'
    assert(w == u + 1);     // advanced 1 word

    uint32_t cp2 = utf8::next16(w, w + 3);
    assert(cp2 == 0x10346); // Gothic letter (surrogate pair decoded)
    assert(w == u + 3);     // advanced 2 words
}
```
```

--------------------------------

### Use Unchecked UTF-8 Iterator

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Demonstrates the usage of the unchecked UTF-8 iterator for iterating through a C-style string containing UTF-8 encoded characters. This version offers no validity or range checks, prioritizing speed.

```cpp
char* threechars = "\xf0\x90\x8d\x86\xe6\x97\xa5\xd1\x88";
utf8::unchecked::iterator<char*> un_it(threechars);
utf8::unchecked::iterator<char*> un_it2 = un_it;
assert (un_it2 == un_it);
assert (*un_it == 0x10346);
assert (*(++un_it) == 0x65e5);
assert ((*un_it++) == 0x65e5);
assert (*un_it == 0x0448);
assert (un_it != un_it2);
utf8::::unchecked::iterator<char*> un_endit (threechars + 9);  
assert (++un_it == un_endit);
assert (*(--un_it) == 0x0448);
assert ((*un_it--) == 0x0448);
assert (*un_it == 0x65e5);
assert (--un_it == utf8::unchecked::iterator<char*>(threechars));
assert (*un_it == 0x10346);
```

--------------------------------

### Define utf8::exception Base Class

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

The base class for all exceptions thrown by the UTF CPP library. Use this to catch any library-specific exceptions.

```cpp
class exception : public std::exception {};
```

--------------------------------

### Convert UTF-32 to UTF-8 using Iterators

Source: https://github.com/nemtrif/utfcpp/blob/master/API_REFERENCE.md

Converts a UTF-32 encoded string to UTF-8 using input and output iterators. Throws `utf8::invalid_code_point` on invalid input.

```cpp
template <typename octet_iterator, typename u32bit_iterator>
octet_iterator utf32to8 (u32bit_iterator start, u32bit_iterator end, octet_iterator result);

```

```cpp
int utf32string[] = {0x448, 0x65E5, 0x10346, 0};
vector<unsigned char> utf8result;
utf32to8(utf32string, utf32string + 3, back_inserter(utf8result));
assert (utf8result.size() == 9);

```