### Install utf8proc Headers and Libraries

Source: https://github.com/juliastrings/utf8proc/blob/master/CMakeLists.txt

Installs the utf8proc header file and the target library to specified destinations based on installation directories.

```cmake
include(GNUInstallDirs)
install(FILES utf8proc.h DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}")
install(TARGETS utf8proc
    EXPORT utf8proc-targets
    ARCHIVE DESTINATION "${CMAKE_INSTALL_LIBDIR}"
    LIBRARY DESTINATION "${CMAKE_INSTALL_LIBDIR}"
    RUNTIME DESTINATION "${CMAKE_INSTALL_BINDIR}"
  )
```

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

### Install pkg-config and CMake Configuration Files

Source: https://github.com/juliastrings/utf8proc/blob/master/CMakeLists.txt

Generates and installs pkg-config and CMake configuration files for the utf8proc library, enabling easier integration with other build systems.

```cmake
configure_file(libutf8proc.pc.cmakein libutf8proc.pc @ONLY)
install(FILES "${CMAKE_CURRENT_BINARY_DIR}/libutf8proc.pc" DESTINATION "${CMAKE_INSTALL_LIBDIR}/pkgconfig")
install(EXPORT utf8proc-targets FILE utf8proc-targets.cmake DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/utf8proc" NAMESPACE utf8proc::)
include(CMakePackageConfigHelpers)
configure_package_config_file(
    "${CMAKE_CURRENT_SOURCE_DIR}/cmake/utf8proc-config.cmake.in"
    "${CMAKE_CURRENT_BINARY_DIR}/utf8proc-config.cmake"
    INSTALL_DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/utf8proc"
    NO_SET_AND_CHECK_MACRO
  )
write_basic_package_version_file(
    "${CMAKE_CURRENT_BINARY_DIR}/utf8proc-config-version.cmake"
    COMPATIBILITY SameMajorVersion
  )
install(FILES
    "${CMAKE_CURRENT_BINARY_DIR}/utf8proc-config.cmake"
    "${CMAKE_CURRENT_BINARY_DIR}/utf8proc-config-version.cmake"
    DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/utf8proc"
  )
```

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

### Linking Manually

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/README.md

Example commands for manually compiling and linking utf8proc with an application.

```bash
gcc -c utf8proc.c -o utf8proc.o
gcc app.c utf8proc.o -o app
```

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

### Linking with pkg-config

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/README.md

Example command to compile an application using utf8proc with pkg-config for flag retrieval.

```bash
gcc app.c $(pkg-config --cflags --libs libutf8proc) -o app
```

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

### Normalizing Line Endings Example

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/configuration.md

This example demonstrates how to normalize all types of newline sequences to a consistent form (LF in this case) using UTF8PROC_NULLTERM, UTF8PROC_NLF2LF, and UTF8PROC_STRIPCC.

```c
#include "utf8proc.h"
#include <stdio.h>

int main() {
    // Input with various line endings
    const utf8proc_uint8_t *input = (utf8proc_uint8_t *)"Line1\r\nLine2\nLine3\rLine4";
    utf8proc_uint8_t *output;
    
    // Convert all newlines to LF
    utf8proc_ssize_t result = utf8proc_map(
        input,
        -1,
        &output,
        UTF8PROC_NULLTERM | UTF8PROC_NLF2LF | UTF8PROC_STRIPCC
    );
    
    if (result >= 0) {
        printf("Normalized: %s\n", (char *)output);
        utf8proc_free(output);
    }
    
    return 0;
}
```

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

### Linking with CMake

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/README.md

Example CMake code to find and link the utf8proc library for a target.

```cmake
find_package(utf8proc 2.9.0 REQUIRED)
target_link_libraries(myapp PRIVATE utf8proc::utf8proc)
```

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

### Build Options Configuration

Source: https://github.com/juliastrings/utf8proc/blob/master/CMakeLists.txt

Configures build options for the utf8proc library. These options control features like installation, testing, and fuzzing.

```cmake
option(UTF8PROC_INSTALL "Enable installation of utf8proc" On)
option(UTF8PROC_ENABLE_TESTING "Enable testing of utf8proc" Off)
option(LIB_FUZZING_ENGINE "Fuzzing engine to link against" Off)
```

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

### Compile with CMake

Source: https://github.com/juliastrings/utf8proc/blob/master/README.md

Example of how to compile the utf8proc library using CMake. This is the recommended approach for Windows users and provides a structured build process.

```sh
mkdir build
cmake -S . -B build
cmake --build build
```

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

### utf8proc_charwidth() Usage Example

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/MANIFEST.md

Shows how to determine the display width of a character (codepoint) using utf8proc_charwidth. This is useful for text rendering and layout.

```c
#include <utf8proc.h>

// ...

int width = utf8proc_charwidth(0x0041); // Codepoint for 'A'

// 'width' will be 1 for most standard characters like 'A'
// Other values can be 0 (e.g., control characters) or 2 (e.g., wide East Asian characters)

```

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

### NFKC Normalization Example

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/api-reference/unicode-normalization.md

Demonstrates how to use utf8proc_NFKC to normalize a string, converting ligatures and compatibility characters into their decomposed and composed equivalents. The resulting string must be freed using utf8proc_free.

```c
#include "utf8proc.h"
#include <stdio.h>

int main() {
    const utf8proc_uint8_t *input = (utf8proc_uint8_t *)"file";  // ligature fi
    
    // Decompose and compose with compatibility
    utf8proc_uint8_t *nfkc = utf8proc_NFKC(input);
    if (nfkc) {
        printf("NFKC: %s\n", (char *)nfkc);  // becomes "file"
        utf8proc_free(nfkc);
    }
    
    return 0;
}
```

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

### utf8proc_map() Usage Example

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/MANIFEST.md

Demonstrates the basic usage of the utf8proc_map function for transforming UTF-8 strings with specified options. Ensure necessary imports and error handling are in place.

```c
#include <utf8proc.h>

// ...

size_t output_len;
utf8proc_int8_t *result = utf8proc_map(
    "input string",
    strlen("input string"),
    &output_len,
    UTF8PROC_COMPOSE | UTF8PROC_UNICODE);

// Handle result and output_len

```

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

### Compile with GNU Make on HP-UX

Source: https://github.com/juliastrings/utf8proc/blob/master/README.md

Instructions for compiling the utf8proc library on HP-UX using the aCC compiler and GNU Make. This example shows specific flags required for shared library compilation on that platform.

```sh
gmake CC=/opt/aCC/bin/aCC CFLAGS="+O2" PICFLAG="+z" C99FLAG="-Ae" WCFLAGS="+w" LDFLAG_SHARED="-b" SOFLAG="-Wl,+h"
```

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

### Usage of Custom Mapping with utf8proc_map_custom

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/types.md

Demonstrates how to use a custom mapping function (e.g., `uppercase_vowels`) with `utf8proc_map_custom`. This example converts a string to uppercase vowels and frees the resulting output buffer.

```c
// Usage with utf8proc_map_custom
const utf8proc_uint8_t *input = (utf8proc_uint8_t *)"hello";
utf8proc_uint8_t *output;
utf8proc_map_custom(input, -1, &output, UTF8PROC_NULLTERM,
                    uppercase_vowels, NULL);
// Result: "hEllO"
utf8proc_free(output);
```

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

### Get utf8proc Version

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/README.md

Retrieves the current version of the utf8proc library at runtime.

```c
const char *version = utf8proc_version();           // "2.11.3"
const char *unicode = utf8proc_unicode_version();   // "17.0.0"
```

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

### utf8proc_get_property() Usage Example

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/MANIFEST.md

Demonstrates retrieving all Unicode properties for a given codepoint using utf8proc_get_property. The function returns a pointer to a utf8proc_property_t structure.

```c
#include <utf8proc.h>

// ...

const utf8proc_property_t *prop = utf8proc_get_property(0x0041); // Codepoint for 'A'

// Access properties via 'prop', e.g., prop->category

```

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

### Get Unicode Version

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/api-reference/utility-functions.md

Retrieves the version of Unicode supported by the utf8proc library. Use this to understand the Unicode standard compliance.

```c
#include "utf8proc.h"
#include <stdio.h>

int main() {
    const char *unicode_ver = utf8proc_unicode_version();
    printf("Unicode version: %s\n", unicode_ver);
    // Output: Unicode version: 17.0.0
    
    return 0;
}
```

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

### Handling Unassigned Codepoints

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/errors.md

This example shows how to handle the UTF8PROC_ERROR_NOTASSIGNED error. It first attempts to process a string with the UTF8PROC_REJECTNA flag. If an unassigned codepoint is detected, it retries the operation without the flag.

```c
#include "utf8proc.h"
#include <stdio.h>

int main() {
    // Input with potential unassigned codepoint
    const utf8proc_uint8_t *input = (utf8proc_uint8_t *)"test";
    utf8proc_uint8_t *output;
    
    // First attempt: reject unassigned
    utf8proc_ssize_t result = utf8proc_map(
        input,
        -1,
        &output,
        UTF8PROC_NULLTERM | UTF8PROC_REJECTNA
    );
    
    if (result == UTF8PROC_ERROR_NOTASSIGNED) {
        fprintf(stderr, "Input contains unassigned codepoints\n");
        
        // Retry without rejecting unassigned
        result = utf8proc_map(
            input,
            -1,
            &output,
            UTF8PROC_NULLTERM  // No REJECTNA flag
        );
    }
    
    if (result >= 0) {
        printf("Success: %s\n", (char *)output);
        utf8proc_free(output);
    }
    
    return result < 0 ? 1 : 0;
}

```

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

### Custom Uppercase Vowels Function

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/types.md

An example custom mapping function that converts lowercase vowels to their uppercase equivalents. It returns the input codepoint unchanged if it's not a vowel.

```c
// Custom mapping that converts all vowels to uppercase
utf8proc_int32_t uppercase_vowels(utf8proc_int32_t cp, void *data) {
    switch (cp) {
        case 'a': return 'A';
        case 'e': return 'E';
        case 'i': return 'I';
        case 'o': return 'O';
        case 'u': return 'U';
        default: return cp;
    }
}
```

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

### Usage Example for utf8proc_grapheme_break

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/api-reference/grapheme-boundaries.md

Demonstrates how to use utf8proc_grapheme_break to check for permitted grapheme breaks between codepoints. It shows cases where a break is not permitted (e.g., letter and combining accent) and where it is permitted (e.g., two regular letters).

```c
#include "utf8proc.h"
#include <stdio.h>

int main() {
    // No break between 'a' and combining accent
    if (!utf8proc_grapheme_break('a', 0x0308)) {  // combining diaeresis
        printf("No grapheme break between 'a' and combining diaeresis\n");
    }
    
    // Break between two regular letters
    if (utf8proc_grapheme_break('a', 'b')) {
        printf("Grapheme break between 'a' and 'b'\n");
    }
    
    return 0;
}
```

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

### utf8proc_encode_char() Usage Example

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/MANIFEST.md

Shows how to encode a single Unicode codepoint into its UTF-8 byte sequence using utf8proc_encode_char. The function handles different byte lengths based on the codepoint value.

```c
#include <utf8proc.h>

// ...

char buffer[5]; // Max 4 bytes + null terminator
int len = utf8proc_encode_char(0x0041, buffer);

// 'buffer' now contains the UTF-8 representation of 'A'
// 'len' is the number of bytes written (1 in this case)

```

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

### utf8proc_category() Usage Example

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/MANIFEST.md

Illustrates how to get the Unicode general category for a codepoint using utf8proc_category. The function returns a value from the utf8proc_category_t enumeration.

```c
#include <utf8proc.h>

// ...

utf8proc_category_t category = utf8proc_category(0x0041); // Codepoint for 'A'

// 'category' now holds the Unicode category, e.g., UTF8PROC_CATEGORY_LU (Letter, uppercase)

```

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

### Compile and Link Static Library

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/library-overview.md

Instructions for compiling the utf8proc source file into an object file and then linking it with an application. This method is used when building a static library.

```c
#include "utf8proc.h"

// Compile: gcc -c utf8proc.c -o utf8proc.o
// Link: gcc app.c utf8proc.o -o app
```

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

### Get Unicode Category of a Codepoint

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/api-reference/character-properties.md

Use `utf8proc_category` to get the Unicode category enum for a codepoint. This is useful for classifying characters into predefined groups like uppercase, lowercase, or numbers.

```c
#include "utf8proc.h"
#include <stdio.h>

int main() {
    // Check category of various codepoints
    printf("'A' category: %d\n", utf8proc_category('A'));      // LU (1)
    printf("'a' category: %d\n", utf8proc_category('a'));      // LL (2)
    printf("'5' category: %d\n", utf8proc_category('5'));      // ND (9)
    printf("'$' category: %d\n", utf8proc_category('$'));      // SC (20)
    
    return 0;
}
```

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

### Build and Link Shared Library

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/library-overview.md

Instructions for building the utf8proc source file into a shared library and then compiling and linking an application against it. This method is used for dynamic linking.

```c
#include "utf8proc.h"

// Build shared library: gcc -shared -fPIC utf8proc.c -o libutf8proc.so
// Compile and link: gcc app.c -lutf8proc -o app
```

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

### Get utf8proc API Version

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/api-reference/utility-functions.md

Retrieves the current API version of the utf8proc library. This is useful for compatibility checks.

```c
#include "utf8proc.h"
#include <stdio.h>

int main() {
    const char *version = utf8proc_version();
    printf("utf8proc version: %s\n", version);
    // Output: utf8proc version: 2.11.3
    
    return 0;
}
```

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

### CMakeLists.txt for utf8proc Integration

Source: https://github.com/juliastrings/utf8proc/blob/master/test/app/CMakeLists.txt

This snippet demonstrates a basic CMakeLists.txt file for a C project that uses the utf8proc library. It ensures the correct CMake version, finds the required package, builds an executable, and links it against the utf8proc library.

```cmake
cmake_minimum_required(VERSION 3.16)
project(utf8proc-test)
find_package(utf8proc REQUIRED)
add_executable(app app.c)
target_link_libraries(app utf8proc::utf8proc)
```

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

### Basic Lowercasing Configuration

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/configuration.md

Use UTF8PROC_NULLTERM and UTF8PROC_CASEFOLD to convert text to lowercase for case-insensitive operations without stability constraints.

```c
UTF8PROC_NULLTERM | UTF8PROC_CASEFOLD
```

```c
utf8proc_uint8_t *lowercased;
utf8proc_map(input, -1, &lowercased, UTF8PROC_NULLTERM | UTF8PROC_CASEFOLD);
utf8proc_free(lowercased);
```

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

### Set Minimum CMake Version

Source: https://github.com/juliastrings/utf8proc/blob/master/CMakeLists.txt

Specifies the minimum version of CMake required to build the project. Ensure your CMake installation meets this requirement.

```cmake
cmake_minimum_required (VERSION 3.10)
```

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

### Expose Header Path

Source: https://github.com/juliastrings/utf8proc/blob/master/CMakeLists.txt

Configures include directories for the utf8proc target, making its headers accessible to dependent projects.

```cmake
target_include_directories(utf8proc PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}> $<INSTALL_INTERFACE:include>)
```

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

### utf8proc_iterate() Usage Example

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/MANIFEST.md

Illustrates how to iterate through a UTF-8 string to decode codepoints using utf8proc_iterate. This function returns the codepoint and its byte length.

```c
#include <utf8proc.h>

// ...

utf8proc_int32_t codepoint;
int size = utf8proc_iterate(
    "UTF-8 string",
    strlen("UTF-8 string"),
    &codepoint);

// Use codepoint and size

```

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

### Use utf8proc in a CMake Project

Source: https://github.com/juliastrings/utf8proc/blob/master/README.md

Demonstrates how to integrate the utf8proc library into a CMake-based C project. This involves finding the package and linking the library to your executable.

```cmake
add_executable (app app.c)
find_package (utf8proc 2.9.0 REQUIRED)
target_link_libraries (app PRIVATE utf8proc::utf8proc)
```

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

### Convert Codepoint to UTF-8 String

Source: https://github.com/juliastrings/utf8proc/blob/master/README.md

Example of converting a Unicode codepoint to its UTF-8 string representation using `utf8proc_encode_char`. The output is printed to standard output.

```c
// Convert codepoint `a` to utf8 string `str`
utf8proc_int32_t a = 223;
utf8proc_uint8_t str[16] = { 0 };
utf8proc_encode_char(a, str);
printf("%s\n", str);
// ß
```

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

### Get Error Message for Error Code

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/api-reference/utility-functions.md

Converts a negative error code returned by utf8proc functions into a human-readable error message. Essential for debugging.

```c
#include "utf8proc.h"
#include <stdio.h>

int main() {
    const utf8proc_uint8_t *invalid_utf8 = (utf8proc_uint8_t *)"\xFF\xFE";
    utf8proc_uint8_t *output;
    
    utf8proc_ssize_t result = utf8proc_map(
        invalid_utf8,
        2,
        &output,
        0
    );
    
    if (result < 0) {
        printf("Error: %s\n", utf8proc_errmsg(result));
        // Output: Error: Invalid UTF-8
    }
    
    return 0;
}
```

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

### Basic Error Checking in utf8proc

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/errors.md

Demonstrates how to check the return value of utf8proc functions for negative error codes and print an error message using utf8proc_errmsg().

```c
#include "utf8proc.h"
#include <stdio.h>

int main() {
    const utf8proc_uint8_t *input = (utf8proc_uint8_t *)"hello";
    utf8proc_uint8_t *output;
    
    utf8proc_ssize_t result = utf8proc_map(
        input,
        -1,
        &output,
        UTF8PROC_NULLTERM | UTF8PROC_CASEFOLD
    );
    
    if (result < 0) {
        // result is a negative error code
        fprintf(stderr, "Error: %s\n", utf8proc_errmsg(result));
        return 1;
    }
    
    printf("Success: %s\n", (char *)output);
    utf8proc_free(output);
    return 0;
}
```

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

### Get Unicode Properties for a Codepoint

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/api-reference/character-properties.md

Use `utf8proc_get_property` to retrieve a struct containing various Unicode properties for a given codepoint. This is useful for detailed character analysis.

```c
#include "utf8proc.h"
#include <stdio.h>

int main() {
    // Get properties for 'A'
    const utf8proc_property_t *props = utf8proc_get_property('A');
    
    printf("Codepoint: U+0041\n");
    printf("Category: %d\n", props->category);
    printf("Combining class: %d\n", props->combining_class);
    printf("Charwidth: %d\n", props->charwidth);
    printf("Bidi class: %d\n", props->bidi_class);
    
    return 0;
}
```

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

### Handle Errors

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/README.md

Demonstrates how to check the return value of utf8proc functions and handle specific error codes like out of memory or invalid UTF-8.

```c
utf8proc_ssize_t result = utf8proc_map(input, -1, &output, options);
if (result < 0) {
    switch (result) {
        case UTF8PROC_ERROR_NOMEM:
            // Handle out of memory
            break;
        case UTF8PROC_ERROR_INVALIDUTF8:
            // Handle invalid UTF-8
            break;
        // ... other cases
    }
}
```

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

### Enable Testing and Download Test Data

Source: https://github.com/juliastrings/utf8proc/blob/master/CMakeLists.txt

Enables CMake testing and downloads Unicode normalization and grapheme break test data for running tests.

```cmake
enable_testing()
file(MAKE_DIRECTORY data)
set(UNICODE_VERSION 17.0.0)
file(DOWNLOAD https://www.unicode.org/Public/${UNICODE_VERSION}/ucd/NormalizationTest.txt ${CMAKE_BINARY_DIR}/data/NormalizationTest.txt SHOW_PROGRESS)
file(DOWNLOAD https://www.unicode.org/Public/${UNICODE_VERSION}/ucd/auxiliary/GraphemeBreakTest.txt ${CMAKE_BINARY_DIR}/data/GraphemeBreakTest.txt SHOW_PROGRESS)
```

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

### Project Definition and Versioning

Source: https://github.com/juliastrings/utf8proc/blob/master/CMakeLists.txt

Defines the project name, API version, and the programming languages used. The API version should be consistent across related files like utf8proc.h and Makefile.

```cmake
# API version - be sure to update utf8proc.h and Makefile, too!
project (utf8proc VERSION 2.11.3 LANGUAGES C)
```

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

### Get Display Width of a Codepoint

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/api-reference/character-properties.md

Use `utf8proc_charwidth` to determine the display width of a codepoint, similar to `wcwidth`. It returns 0, 1, or 2, with 0 for non-printable characters.

```c
#include "utf8proc.h"
#include <stdio.h>

int main() {
    printf("Width of 'a': %d\n", utf8proc_charwidth('a'));           // 1
    printf("Width of 'é': %d\n", utf8proc_charwidth(0xE9));         // 1
    printf("Width of '中': %d\n", utf8proc_charwidth(0x4E2D));       // 2 (CJK)
    printf("Width of null: %d\n", utf8proc_charwidth(0));            // 0 (control)
    printf("Width of tab: %d\n", utf8proc_charwidth('\t'));          // 0 (control)
    
    return 0;
}
```

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

### Usage Example for utf8proc_grapheme_break_stateful

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/api-reference/grapheme-boundaries.md

Illustrates how to use utf8proc_grapheme_break_stateful to iterate through grapheme clusters in a UTF-32 string. It correctly identifies 'e' and its combining acute accent as a single grapheme cluster.

```c
#include "utf8proc.h"
#include <stdio.h>
#include <string.h>

// Iterate grapheme clusters in a UTF-32 string
int main() {
    // Example: "é" (e + combining acute accent) should be one grapheme
    utf8proc_int32_t str[] = {
        'e',      // U+0065
        0x0301,   // combining acute accent
        'x'       // U+0078
    };
    
    utf8proc_int32_t state = 0;
    int break_positions[4] = {0};  // Mark positions where breaks occur
    int break_count = 1;  // Start is always a break
    
    for (int i = 0; i < 2; i++) {
        if (utf8proc_grapheme_break_stateful(str[i], str[i+1], &state)) {
            break_positions[break_count++] = i + 1;
        }
    }
    
    printf("Grapheme clusters:\n");
    for (int i = 0; i < break_count - 1; i++) {
        printf("  Cluster %d: U+%04X to U+%04X\n",
            i,
            str[break_positions[i]],
            str[break_positions[i+1] - 1]
        );
    }
    
    return 0;
}
```

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

### Process String with Custom Options

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/README.md

Applies various transformations to a string using utf8proc_map with custom options. Handles potential errors and frees the output buffer.

```c
utf8proc_uint8_t *output;
utf8proc_ssize_t result = utf8proc_map(
    input, -1, &output,
    UTF8PROC_NULLTERM | UTF8PROC_STABLE | UTF8PROC_COMPOSE
);
if (result < 0) {
    printf("Error: %s\n", utf8proc_errmsg(result));
} else {
    printf("Result: %s\n", (char*)output);
    utf8proc_free(output);
}
```

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

### Get Unicode Category String for a Codepoint

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/api-reference/character-properties.md

Use `utf8proc_category_string` to obtain the two-letter string representation of a codepoint's Unicode category. This is helpful for displaying or comparing category codes.

```c
#include "utf8proc.h"
#include <stdio.h>

int main() {
    printf("'A' category: %s\n", utf8proc_category_string('A'));     // "Lu"
    printf("'a' category: %s\n", utf8proc_category_string('a'));     // "Ll"
    printf("',' category: %s\n", utf8proc_category_string(','));     // "Po"
    printf("U+2028 category: %s\n", utf8proc_category_string(0x2028)); // "Zl"
    
    return 0;
}
```

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

### Case Conversion Functions

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/MANIFEST.md

Provides functions for converting strings to lowercase, uppercase, and titlecase, as well as checking their case.

```C
#include <utf8proc.h>

// Example usage of case conversion functions
const char *str = "Hello World";
char *lower = utf8proc_tolower(str);
char *upper = utf8proc_toupper(str);
char *title = utf8proc_totitle(str);

// Example usage of case checking functions
bool is_lower = utf8proc_islower(str);
bool is_upper = utf8proc_isupper(str);

// Remember to free the allocated memory for converted strings
utf8proc_free(lower);
utf8proc_free(upper);
utf8proc_free(title);
```

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

### Utility Functions

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/MANIFEST.md

Provides utility functions for retrieving API version, Unicode version, error messages, and memory deallocation.

```C
#include <utf8proc.h>

// Get API version
const char *api_version = utf8proc_version();

// Get Unicode version
const char *unicode_version = utf8proc_unicode_version();

// Get error message for an error code
int error_code = 1; // Example error code
const char *error_msg = utf8proc_errmsg(error_code);

// Deallocate memory (e.g., from case conversion functions)
char *data_to_free = utf8proc_tolower("Test");
utf8proc_free(data_to_free);
```

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

### NFKC Normalization (Compatibility Composed)

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/configuration.md

Use for aggressive normalization for case-insensitive comparison, converting ligatures and variants. Caution: Loses formatting information.

```c
UTF8PROC_NULLTERM | UTF8PROC_STABLE | UTF8PROC_COMPOSE | UTF8PROC_COMPAT
```

```c
utf8proc_uint8_t *normalized = utf8proc_NFKC(input);
// or
utf8proc_map(input, -1, &output, 
             UTF8PROC_NULLTERM | UTF8PROC_STABLE | UTF8PROC_COMPOSE | UTF8PROC_COMPAT);
```

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

### Find Character Properties

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/README.md

Retrieves properties, category, and width for a given Unicode codepoint.

```c
const utf8proc_property_t *prop = utf8proc_get_property(codepoint);
utf8proc_category_t cat = utf8proc_category(codepoint);
int width = utf8proc_charwidth(codepoint);
```

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

### Add Character Width Test (Non-Windows)

Source: https://github.com/juliastrings/utf8proc/blob/master/CMakeLists.txt

Adds an executable for character width testing and a corresponding CMake test, excluding Windows platforms due to missing wcwidth function.

```cmake
if (NOT WIN32)
  # no wcwidth function on Windows
  add_executable(charwidth test/tests.h test/tests.c utf8proc.h test/charwidth.c)
  target_link_libraries(charwidth utf8proc)
  add_test(utf8proc.testcharwidth charwidth)
endif()
```

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

### Getting Error Messages with utf8proc_errmsg

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/errors.md

This function takes an error code returned by utf8proc functions and uses utf8proc_errmsg to retrieve a human-readable error message. The message is then printed to standard error.

```c
#include "utf8proc.h"
#include <stdio.h>

void log_error(utf8proc_ssize_t errcode) {
    if (errcode < 0) {
        const char *msg = utf8proc_errmsg(errcode);
        fprintf(stderr, "[ERROR %ld] %s\n", errcode, msg);
    }
}

```

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

### Define Static Library Compilation

Source: https://github.com/juliastrings/utf8proc/blob/master/CMakeLists.txt

Adds a compile definition to build utf8proc as a static library, particularly for MSVC targets.

```cmake
target_compile_definitions(utf8proc PUBLIC "UTF8PROC_STATIC")
if (MSVC)
  set_target_properties(utf8proc PROPERTIES OUTPUT_NAME "utf8proc_static")
endif()
```

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

### Utility Functions

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/MANIFEST.md

Provides essential helper functions for interacting with the utf8proc library, including retrieving version information, error messages, and managing library memory.

```APIDOC
## Utility Functions

### Description
Helper functions and utilities for the utf8proc library.

### Functions
- **utf8proc_version()**: Get the API version string.
- **utf8proc_unicode_version()**: Get the Unicode version supported by the library.
- **utf8proc_errmsg()**: Get the error message for a given error code.
- **utf8proc_free()**: Deallocate utf8proc memory.

### Data
- **utf8proc_utf8class**: An array for UTF-8 byte classification.
```

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

### Set Target Properties

Source: https://github.com/juliastrings/utf8proc/blob/master/CMakeLists.txt

Configures properties for the utf8proc target, including position-independent code and versioning.

```cmake
set_target_properties (utf8proc PROPERTIES
  POSITION_INDEPENDENT_CODE ON
  VERSION "${SO_MAJOR}.${SO_MINOR}.${SO_PATCH}"
  SOVERSION ${SO_MAJOR}
)
```

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

### Determine UTF-8 Sequence Length

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/api-reference/utility-functions.md

This C code snippet demonstrates how to use the `utf8proc_utf8class` array to determine the length of a UTF-8 character sequence based on its first byte. It shows examples for ASCII, 2-byte, 3-byte sequences, and continuation bytes.

```c
#include "utf8proc.h"
#include <stdio.h>

int main() {
    unsigned char byte;
    
    // Check first byte of UTF-8 sequence
    byte = 0x41;  // 'A'
    printf("'A' (0x41) sequence length: %d\n", utf8proc_utf8class[byte]);  // 1
    
    byte = 0xC2;  // Start of 2-byte sequence
    printf("0xC2 sequence length: %d\n", utf8proc_utf8class[byte]);  // 2
    
    byte = 0xE0;  // Start of 3-byte sequence
    printf("0xE0 sequence length: %d\n", utf8proc_utf8class[byte]);  // 3
    
    byte = 0x80;  // Continuation byte
    printf("0x80 (continuation) sequence length: %d\n", utf8proc_utf8class[byte]);  // 0
    
    return 0;
}
```

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

### Add Grapheme and Normalization Tests

Source: https://github.com/juliastrings/utf8proc/blob/master/CMakeLists.txt

Adds executables for grapheme break and normalization tests, linking them to utf8proc and defining corresponding CMake tests with data files.

```cmake
add_executable(graphemetest test/tests.h test/tests.c utf8proc.h test/graphemetest.c)
target_link_libraries(graphemetest utf8proc)
add_executable(normtest test/tests.h test/tests.c utf8proc.h test/normtest.c)
target_link_libraries(normtest utf8proc)
add_test(utf8proc.testgraphemetest graphemetest data/GraphemeBreakTest.txt)
add_test(utf8proc.testnormtest normtest data/NormalizationTest.txt)
```

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

### Utility Functions

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/README.md

Helper functions for retrieving version information, error messages, and freeing resources.

```APIDOC
## utf8proc_version()

### Description
Retrieves the current version of the utf8proc library.

### Method
(Not specified, likely a C function call)

### Endpoint
(Not applicable, C function)

### Parameters
(Not specified in source)

### Request Example
```c
const char *version = utf8proc_version();
```

### Response
Returns a string representing the library version (e.g., "2.11.3").

## utf8proc_unicode_version()

### Description
Retrieves the Unicode version supported by the library.

### Method
(Not specified, likely a C function call)

### Endpoint
(Not applicable, C function)

### Parameters
(Not specified in source)

### Request Example
```c
const char *unicode_version = utf8proc_unicode_version();
```

### Response
Returns a string representing the supported Unicode version (e.g., "17.0.0").

## utf8proc_errmsg()

### Description
Retrieves the error message for the last utf8proc operation.

### Method
(Not specified, likely a C function call)

### Endpoint
(Not applicable, C function)

### Parameters
(Not specified in source)

### Request Example
(Not applicable, C function)

### Response
Returns a string describing the last error.

## utf8proc_free()

### Description
Frees memory allocated by utf8proc functions.

### Method
(Not specified, likely a C function call)

### Endpoint
(Not applicable, C function)

### Parameters
(Not specified in source)

### Request Example
(Not applicable, C function)

### Response
(Not specified in source)
```

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

### utf8proc Version Constants

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/configuration.md

Define and compare version constants for utf8proc to ensure compatibility with specific features or behaviors.

```c
#define UTF8PROC_VERSION_MAJOR 2
#define UTF8PROC_VERSION_MINOR 11
#define UTF8PROC_VERSION_PATCH 3
```

```c
#if UTF8PROC_VERSION_MAJOR >= 2 && UTF8PROC_VERSION_MINOR >= 9
// Use features available in 2.9+
#endif
```

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

### Case-Insensitive Comparison Configuration

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/README.md

Flags for performing case-insensitive comparisons. Combines normalization and case folding.

```c
UTF8PROC_STABLE | UTF8PROC_COMPOSE | UTF8PROC_COMPAT | UTF8PROC_CASEFOLD | UTF8PROC_IGNORE
```

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

### Add Test Executables

Source: https://github.com/juliastrings/utf8proc/blob/master/CMakeLists.txt

Adds various test executables (case, custom, iterate, misc, printproperty, valid, maxdecomposition) linked against the utf8proc library.

```cmake
add_executable(case test/tests.h test/tests.c utf8proc.h test/case.c)
target_link_libraries(case utf8proc)
add_executable(custom test/tests.h test/tests.c utf8proc.h test/custom.c)
target_link_libraries(custom utf8proc)
add_executable(iterate test/tests.h test/tests.c utf8proc.h test/iterate.c)
target_link_libraries(iterate utf8proc)
add_executable(misc test/tests.h test/tests.c utf8proc.h test/misc.c)
target_link_libraries(misc utf8proc)
add_executable(printproperty test/tests.h test/tests.c utf8proc.h test/printproperty.c)
target_link_libraries(printproperty utf8proc)
add_executable(valid test/tests.h test/tests.c utf8proc.h test/valid.c)
target_link_libraries(valid utf8proc)
add_executable(maxdecomposition test/tests.h test/tests.c utf8proc.h test/maxdecomposition.c)
target_link_libraries(maxdecomposition utf8proc)
```

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

### Case-Insensitive Comparison (NFKC_Casefold)

Source: https://github.com/juliastrings/utf8proc/blob/master/_autodocs/configuration.md

Use to prepare strings for case-insensitive comparison by normalizing case, compatibility, and ignorables. This is the most aggressive transformation.

```c
UTF8PROC_NULLTERM | UTF8PROC_STABLE | UTF8PROC_COMPOSE | UTF8PROC_COMPAT | UTF8PROC_CASEFOLD | UTF8PROC_IGNORE
```

```c
utf8proc_uint8_t *folded1 = utf8proc_NFKC_Casefold(str1);
utf8proc_uint8_t *folded2 = utf8proc_NFKC_Casefold(str2);
if (strcmp((char *)folded1, (char *)folded2) == 0) {
    // Strings are equal (case-insensitive)
}
utf8proc_free(folded1);
utf8proc_free(folded2);
```