📚 Single header utf8 string functions for C and C++; Neil Henning (2015).
npm install utf8.csh
$ npm i utf8.c
`
And then include utf8.h as follows:
`c
// main.c
#include
int main() { / ... / }
`
Finally, compile while adding the path node_modules/utf8.c to your compiler's include paths.
`bash
$ clang -I./node_modules/utf8.c main.c # or, use gcc
$ gcc -I./node_modules/utf8.c main.c
`
You may also use a simpler approach with the cpoach tool, which automatically adds the necessary include paths of all the installed dependencies for your project.
`bash
$ cpoach clang main.c # or, use gcc
$ cpoach gcc main.c
`
Usage ##
The current supported platforms are Linux, macOS and Windows.
The current supported compilers are gcc, clang, MSVC's cl.exe, and clang-cl.exe.
Design ##
The utf8.h API matches the string.h API as much as possible by design. There are a few major differences though.
utf8.h uses char8_t in C++ 20 instead of char
Anywhere in the string.h or strings.h documentation where it refers to 'bytes' I have changed that to utf8 codepoints. For instance, utf8len will return the number of utf8 codepoints in a utf8 string - which does not necessarily equate to the number of bytes.
API function docs ##
`c
int utf8casecmp(const void src1, const void src2);
`
Return less than 0, 0, greater than 0 if src1 < src2, src1 == src2,
src1 > src2 respectively, case insensitive.
`c
void utf8cat(void dst, const void *src);
`
Append the utf8 string src onto the utf8 string dst.
`c
void utf8chr(const void src, utf8_int32_t chr);
`
Find the first match of the utf8 codepoint chr in the utf8 string src.
`c
int utf8cmp(const void src1, const void src2);
`
Return less than 0, 0, greater than 0 if src1 < src2,
src1 == src2, src1 > src2 respectively.
`c
void utf8cpy(void dst, const void *src);
`
Copy the utf8 string src onto the memory allocated in dst.
`c
size_t utf8cspn(const void src, const void reject);
`
Number of utf8 codepoints in the utf8 string src that consists entirely
of utf8 codepoints not from the utf8 string reject.
`c
void utf8dup(const void src);
`
Duplicate the utf8 string src by getting its size, mallocing a new buffer
copying over the data, and returning that. Or 0 if malloc failed.
`c
size_t utf8len(const void *str);
`
Number of utf8 codepoints in the utf8 string str,
excluding the null terminating byte.
`c
size_t utf8nlen(const void *str, size_t n);
`
Similar to utf8len, except that only at most n bytes of src are looked.
`c
int utf8ncasecmp(const void src1, const void src2, size_t n);
`
Return less than 0, 0, greater than 0 if src1 < src2, src1 == src2,
src1 > src2 respectively, case insensitive. Checking at most n
bytes of each utf8 string.
`c
void utf8ncat(void dst, const void *src, size_t n);
`
Append the utf8 string src onto the utf8 string dst,
writing at most n+1 bytes. Can produce an invalid utf8
string if n falls partway through a utf8 codepoint.
`c
int utf8ncmp(const void src1, const void src2, size_t n);
`
Return less than 0, 0, greater than 0 if src1 < src2,
src1 == src2, src1 > src2 respectively. Checking at most n
bytes of each utf8 string.
`c
void utf8ncpy(void dst, const void *src, size_t n);
`
Copy the utf8 string src onto the memory allocated in dst.
Copies at most n bytes. If n falls partway through a utf8
codepoint, or if dst doesn't have enough room for a null
terminator, the final string will be cut short to preserve
utf8 validity.
`c
void utf8pbrk(const void str, const void *accept);
`
Locates the first occurrence in the utf8 string str of any byte in the
utf8 string accept, or 0 if no match was found.
`c
void utf8rchr(const void src, utf8_int32_t chr);
`
Find the last match of the utf8 codepoint chr in the utf8 string src.
`c
size_t utf8size(const void *str);
`
Number of bytes in the utf8 string str,
including the null terminating byte.
`c
size_t utf8size_lazy(const void *str);
`
Similar to utf8size, except that the null terminating byte is excluded.
`c
size_t utf8nsize_lazy(const void *str, size_t n);
`
Similar to utf8size, except that only at most n bytes of src are looked and
the null terminating byte is excluded.
`c
size_t utf8spn(const void src, const void accept);
`
Number of utf8 codepoints in the utf8 string src that consists entirely
of utf8 codepoints from the utf8 string accept.
`c
void utf8str(const void haystack, const void *needle);
`
The position of the utf8 string needle in the utf8 string haystack.
`c
void utf8casestr(const void haystack, const void *needle);
`
The position of the utf8 string needle in the utf8 string haystack,
case insensitive.
`c
void utf8valid(const void str);
`
Return 0 on success, or the position of the invalid utf8 codepoint on failure.
`c
void utf8nvalid(const void str, size_t n);
`
Similar to utf8valid, except that only at most n bytes of src are looked.
`c
int utf8makevalid(void *str, utf8_int32_t replacement);
`
Return 0 on success. Makes the str valid by replacing invalid sequences with
the 1-byte replacement codepoint.
`c
void utf8codepoint(const void str, utf8_int32_t *out_codepoint);
`
Sets out_codepoint to the current utf8 codepoint in str, and returns the
address of the next utf8 codepoint after the current one in str.
`c
void utf8rcodepoint(const void str, utf8_int32_t *out_codepoint);
`
Sets out_codepoint to the current utf8 codepoint in str, and returns the
address of the previous utf8 codepoint before the current one in str.
`c
size_t utf8codepointsize(utf8_int32_t chr);
`
Returns the size of the given codepoint in bytes.
`c
void utf8catcodepoint(void utf8_restrict str, utf8_int32_t chr, size_t n);
`
Write a codepoint to the given string, and return the address to the next
place after the written codepoint. Pass how many bytes left in the buffer to
n. If there is not enough space for the codepoint, this function returns
null.
`c
int utf8islower(utf8_int32_t chr);
`
Returns 1 if the given character is lowercase, or 0 if it is not.
`c
int utf8isupper(utf8_int32_t chr);
`
Returns 1 if the given character is uppercase, or 0 if it is not.
`c
void utf8lwr(void *utf8_restrict str);
`
Transform the given string into all lowercase codepoints.
`c
void utf8upr(void *utf8_restrict str);
`
Transform the given string into all uppercase codepoints.
`c
utf8_int32_t utf8lwrcodepoint(utf8_int32_t cp);
`
Make a codepoint lower case if possible.
`c
utf8_int32_t utf8uprcodepoint(utf8_int32_t cp);
``