utf8proc Documentation

utf8proc provides a CMake Config-file package. To use it in your project, use find_package and link against the utf8proc::utf8proc target.

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

You can install utf8proc by downloading a release or compiling from source.

Using Make

For GNU/Linux and MacOS, use make to compile.

• make: Compiles the library.
• make install: Installs the library and header (defaults to /usr/local/lib and /usr/local/bin). Use make prefix=/some/dir to specify a custom installation path.
• make check: Runs tests.
• make clean: Removes generated files.

Using CMake

For Windows or CMake-based workflows, use the following commands:

mkdir build
cmake -S . -B build
cmake --build build

Use utf8proc_encode_char to convert a 32-bit integer codepoint into a UTF-8 encoded byte array.

// 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);
// ß

Use utf8proc_iterate to traverse a UTF-8 string and extract codepoints.

// Convert string `str` to pointer to codepoint `a`
utf8proc_uint8_t str[] = "ß";
utf8proc_int32_t a;
utf8proc_iterate(str, -1, &a);
printf("%d\n", a);
// 223

The utf8proc_map function is the primary way to transform strings. To perform case-folding, use the UTF8PROC_CASEFOLD flag. Note that utf8proc_map allocates memory for the result, which must be freed using utf8proc_free.

// Convert "ß"  (U+00DF) to its casefold variant "ss"
utf8proc_uint8_t str[] = "ß";
utf8proc_uint8_t *fold_str;
utf8proc_map(str, 0, &fold_str, UTF8PROC_NULLTERM | UTF8PROC_CASEFOLD);
printf("%s\n", fold_str);
// ss
utf8proc_free(fold_str);

You can use helper functions like utf8proc_NFD and utf8proc_NFC to perform normalization. These functions allocate memory that must be manually released with utf8proc_free.

// Decompose "\u00e4\u00f6\u00fc" = "äöü" into "a\u0308o\u0308u\u0308" (= "äöü" via combining char U+0308)
utf8proc_uint8_t input[] = {0xc3, 0xa4, 0xc3, 0xb6, 0xc3, 0xbc}; // "\u00e4\u00f6\u00fc" = "äöü" in UTF-8
utf8proc_uint8_t *nfd= utf8proc_NFD(input); // = {0x61, 0xcc, 0x88, 0x6f, 0xcc, 0x88, 0x75, 0xcc, 0x88}

// Compose "a\u0308o\u0308u\u0308" into "\u00e4\u00f6\u00fc" (= "äöü" via precomposed characters)
utf8proc_uint8_t *nfc= utf8proc_NFC(nfd);

utf8proc_free(nfd);
utf8proc_free(nfc);

utf8proc supports Unicode 17.0.0. Normalization is performed using specific flag combinations:

• Normalization Form C (NFC): STABLE, COMPOSE
• Normalization Form D (NFD): STABLE, DECOMPOSE
• Normalization Form KC (NFKC): STABLE, COMPOSE, COMPAT
• Normalization Form KD (NFKD): STABLE, DECOMPOSE, COMPAT