# utf8.h #
[![Build status](https://ci.appveyor.com/api/projects/status/phfjjahhs9j4gxvs?svg=true)](https://ci.appveyor.com/project/sheredom/utf8-h)
[![Build status](https://api.travis-ci.org/repositories/sheredom/utf8.h.svg)](https://travis-ci.org/sheredom/utf8.h)
A simple one header solution to supporting utf8 strings in C and C++.
Functions provided from the C header string.h but with a utf8* prefix instead of the str* prefix:
[API function docs](#api-function-docs)
string.h | utf8.h | complete
---------|--------|---------
strcat | utf8cat | ✔
strchr | utf8chr | ✔
strcmp | utf8cmp | ✔
strcoll | utf8coll |
strcpy | utf8cpy | ✔
strcspn | utf8cspn | ✔
strdup | utf8dup | ✔
strfry | utf8fry |
strlen | utf8len | ✔
strncat | utf8ncat | ✔
strncmp | utf8ncmp | ✔
strncpy | utf8ncpy | ✔
strpbrk | utf8pbrk | ✔
strrchr | utf8rchr | ✔
strsep | utf8sep |
strspn | utf8spn | ✔
strstr | utf8str | ✔
strtok | utf8tok |
strxfrm | utf8xfrm |
Functions provided from the C header strings.h but with a utf8* prefix instead of the str* prefix:
strings.h | utf8.h | complete
----------|--------|---------
strcasecmp | utf8casecmp | ~~✔~~
strncasecmp | utf8ncasecmp | ~~✔~~
strcasestr | utf8casestr | ~~✔~~
Functions provided that are unique to utf8.h:
utf8.h | complete
-------|---------
utf8codepoint | ✔
utf8size | ✔
utf8valid | ✔
utf8codepointsize | ✔
utf8catcodepoint | ✔
utf8isupper |
utf8islower |
utf8lwr |
utf8upr |
## Usage ##
Just include utf8.h in your code!
The current supported compilers are gcc, clang and msvc.
The current tested compiler versions are gcc 4.8.2, clang 3.5 and MSVC 18.0.21005.1.
## Design ##
The utf8.h API matches the string.h API as much as possible by design. There are a few major differences though.
I use void* instead of char* when passing around utf8 strings. My reasoning is that I really don't want people accidentally thinking they can use integer arthimetic on the pointer and always get a valid character like you would with an ASCII string. Having it as a void* forces a user to explicitly cast the utf8 string to char* such that the onus is on them not to break the code anymore!
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);
```
While ignoring the case of ASCII characters,
return less than 0, 0, greater than 0
if `src1 < src2`, `src1 == src2`, `src1 > src2` respectively.
```c
void *utf8cat(void *dst, const void *src);
```
Append the utf8 string `src` onto the utf8 string `dst`.
```c
void *utf8chr(const void *src, long 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, `malloc`ing 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
int utf8ncasecmp(const void *src1, const void *src2, size_t n);
```
While ignoring the case of ASCII characters, 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 *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 there is no terminating null byte in
the first `n` bytes of `src`, the string placed into `dst` will not be
null-terminated. If the size (in bytes) of `src` is less than `n`,
extra null terminating bytes are appended to `dst` such that at
total of `n` bytes are written. Can produce an invalid utf8
string if `n` falls partway through a utf8 codepoint.
```c
void *utf8pbrk(const void *str, const void *accept);
```
Locates the first occurence 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, int 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 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 instensitive.
```c
void *utf8valid(const void *str);
```
Return 0 on success, or the position of the invalid utf8 codepoint on failure.
```c
void *utf8codepoint(const void *str, long *out_codepoint);
```
Sets out_codepoint to the next utf8 codepoint in `str`,
and returns the address of the utf8 codepoint after the current one in `str`.
## Todo ##
- Implement utf8coll (akin to strcoll).
- Implement utf8fry (akin to strfry).
- ~~Add NULL pointer support. Should I NULL check the arguments to the API?~~
- Add Doxygen (or similar) to mimic the Unix man pages for string.h.
- Investigate adding dst buffer sizes for utf8cpy and utf8cat to catch overwrites (as suggested by [@FlohOfWoe](https://twitter.com/FlohOfWoe) in https://twitter.com/FlohOfWoe/status/618669237771608064)
- Investigate adding a utf8canon which would turn 'bad' utf8 sequences (like ASCII values encoded in 4-byte utf8 codepoints) into their 'good' equivalents (as suggested by [@KmBenzie](https://twitter.com/KmBenzie))
- Investigate changing to [Creative Commons Zero License](http://creativecommons.org/publicdomain/zero/1.0/legalcode.txt) (as suggested by [@mcclure111](https://twitter.com/mcclure111))
- ~~Add utf8casecmp and utf8ncasecmp to compare two strings case-insensitively (as insensitively suggested by [@daniel_collin](https://twitter.com/daniel_collin))~~
- Extend utf8casecmp range to consume non-ASCII case differences too (I don't even rightly know if there are any!)
## License ##
This is free and unencumbered software released into the public domain.
Anyone is free to copy, modify, publish, use, compile, sell, or
distribute this software, either in source code form or as a compiled
binary, for any purpose, commercial or non-commercial, and by any
means.
In jurisdictions that recognize copyright laws, the author or authors
of this software dedicate any and all copyright interest in the
software to the public domain. We make this dedication for the benefit
of the public
utf8.h.zip_C++_UTF8_utf8.h_utf8函数_字符处理
版权申诉
200 浏览量
2022-09-21
20:42:26
上传
评论
收藏 22KB ZIP 举报
JonSco
- 粉丝: 66
- 资源: 1万+
最新资源
- QuestionTwo.java
- QuestionOne.java
- OA办公自动化管理系统(Struts1.2+Hibernate3.0+Spring2+DWR).rar
- 简历-求职简历-word-文件-简历模版免费分享-应届生-高颜值简历模版-个人简历模版-简约大气-大学生在校生-求职-实习
- 南京邮电大学数学实验:熟练掌握 Matlab 软件的基本命令和操作
- 简历-求职简历-word-文件-简历模版免费分享-应届生-高颜值简历模版-个人简历模版-简约大气-大学生在校生-求职-实习
- 2017校招真题校园招聘真题算法题(37道)Python源码.zip
- 基于单片机protues仿真的多功能自动饮水机系统设计(仿真图、源代码、演示视频)
- 论文《一种修复流程挖掘事件日志中缺失活动标签的深度学习方法》翻译
- 智慧电厂相关资料发电控制的方式
资源上传下载、课程学习等过程中有任何疑问或建议,欢迎提出宝贵意见哦~我们会及时处理!
点击此处反馈