wchar

wchar 模块提供了宽字符处理相关的接口，包括多字节字符与宽字符之间的转换、宽字符串的比较与转换等功能。

头文件清单

#include "open_source/musl/include/wchar.h"

接口清单

接口名称	功能简述
mbsnrtowcs	多字节序列转换为宽字符（有最大长度限制）
wcscoll_l	采用目前区域的字符排列次序来比较宽字符串
wcsnlen	返回多字节字符的长度（有最大长度限制）
wcsnrtombs	把数组中存储的编码转换为多字节字符（有最大长度限制）
wcsxfrm_l	根据程序当前的区域选项中的LC_COLLATE来转换宽字符串的前n个字符

Functions

mbsnrtowcs

函数声明

size_t mbsnrtowcs(wchar_t *__restrict, const char **__restrict, size_t, size_t, mbstate_t *__restrict)

头文件清单

#include "open_source/musl/include/wchar.h"

功能说明

将多字节字符序列转换为宽字符序列，受最大输入字节长度限制
当输入指针指向NULL时，转换状态被重置为初始状态
转换过程中遇到无效多字节序列时停止转换

入参

名称	参数类型	详细说明	约束取值范围
src	const char **__restrict	指向待转换的多字节字符串的间接指针	非空指针，指向有效的多字节字符串
nms	size_t	从源字符串中最多处理的多字节字节数	`0 ~ SIZE_MAX`
len	size_t	目标宽字符数组的最大容量（宽字符数）	`0 ~ SIZE_MAX`
ps	mbstate_t *__restrict	多字节转换状态指针	`NULL` 或有效的mbstate_t指针

出参

名称	数据类型	输出说明
dst	wchar_t *__restrict	存储转换结果的宽字符数组；可为`NULL`，为NULL时仅计算所需长度
src	const char **__restrict	更新为未转换部分的地址；转换失败或遇到空字符时不更新

返回值

返回值	文字含义	触发场景
size_t (非负)	成功转换的宽字符数（不含终止空字符）	转换成功完成
(size_t)-1	转换遇到无效多字节序列	输入包含无效的多字节字符，errno设为EILSEQ

wcscoll_l

函数声明

int wcscoll_l(const wchar_t *, const wchar_t *, locale_t)

头文件清单

#include "open_source/musl/include/wchar.h"

功能说明

根据指定区域设置（locale）的字符排列次序来比较两个宽字符串
比较结果受区域设置的LC_COLLATE类别影响
当区域设置为"C"或"POSIX"时，等价于wcscmp

入参

名称	参数类型	详细说明	约束取值范围
ws1	const wchar_t *	第一个待比较的宽字符串指针	非空指针，指向有效的宽字符串
ws2	const wchar_t *	第二个待比较的宽字符串指针	非空指针，指向有效的宽字符串
loc	locale_t	指定的区域设置对象	有效的locale_t对象

返回值

返回值	文字含义	触发场景
小于0的整数	ws1小于ws2	根据区域排列规则ws1排在ws2之前
0	ws1等于ws2	两个宽字符串在指定区域规则下相等
大于0的整数	ws1大于ws2	根据区域排列规则ws1排在ws2之后

wcsnlen

函数声明

size_t wcsnlen(const wchar_t *, size_t)

头文件清单

#include "open_source/musl/include/wchar.h"

功能说明

计算宽字符串的长度，受最大长度限制
扫描宽字符串中的字符个数，直到遇到空宽字符或达到最大长度限制
不会读取超过maxlen个宽字符

入参

名称	参数类型	详细说明	约束取值范围
s	const wchar_t *	待计算长度的宽字符串指针	非空指针，指向有效的宽字符串
maxlen	size_t	允许扫描的最大宽字符数	`0 ~ SIZE_MAX`

返回值

返回值	文字含义	触发场景
size_t	宽字符串的长度或maxlen	若在maxlen个字符内遇到空宽字符，返回实际长度；否则返回maxlen

wcsnrtombs

函数声明

size_t wcsnrtombs(char *__restrict, const wchar_t **__restrict, size_t, size_t, mbstate_t *__restrict)

头文件清单

#include "open_source/musl/include/wchar.h"

功能说明

将宽字符序列转换为多字节字符序列，受最大输入宽字符长度限制
当输入指针指向NULL时，转换状态被重置为初始状态
转换过程中遇到无法转换的宽字符时停止转换

入参

名称	参数类型	详细说明	约束取值范围
src	const wchar_t **__restrict	指向待转换的宽字符串的间接指针	非空指针，指向有效的宽字符串
nwc	size_t	从源字符串中最多处理的宽字符数	`0 ~ SIZE_MAX`
len	size_t	目标多字节字符数组的最大容量（字节数）	`0 ~ SIZE_MAX`
ps	mbstate_t *__restrict	多字节转换状态指针	`NULL` 或有效的mbstate_t指针

出参

名称	数据类型	输出说明
dst	char *__restrict	存储转换结果的多字节字符数组；可为`NULL`，为NULL时仅计算所需长度
src	const wchar_t **__restrict	更新为未转换部分的地址；转换失败或遇到空宽字符时不更新

返回值

返回值	文字含义	触发场景
size_t (非负)	成功转换的多字节字节数（不含终止空字节）	转换成功完成
(size_t)-1	转换遇到无法表示的多字节字符	输入包含无法转换的宽字符，errno设为EILSEQ

wcsxfrm_l

函数声明

size_t wcsxfrm_l(wchar_t *__restrict, const wchar_t *__restrict, size_t, locale_t)

头文件清单

#include "open_source/musl/include/wchar.h"

功能说明

根据指定区域设置的LC_COLLATE类别转换宽字符串，使转换后的字符串通过wcscmp比较的结果与原字符串通过wcscoll_l比较的结果一致
转换后的字符串可用于后续的wcscmp比较以替代wcscoll_l
当n为0且dest为NULL时，仅返回所需的转换后字符串长度

入参

名称	参数类型	详细说明	约束取值范围
src	const wchar_t *__restrict	待转换的宽字符串指针	非空指针，指向有效的宽字符串
n	size_t	目标宽字符数组的最大容量（宽字符数）	`0 ~ SIZE_MAX`
loc	locale_t	指定的区域设置对象	有效的locale_t对象

出参

名称	数据类型	输出说明
dest	wchar_t *__restrict	存储转换结果的宽字符数组；可为`NULL`，为NULL时仅计算所需长度

返回值

返回值	文字含义	触发场景
size_t	转换后的宽字符串长度（不含终止空字符）	转换成功完成；若返回值大于等于n，则dest中内容未完整存储