当前位置： C语言 -- 标准库 -- <uchar.h> -- mbrtoc16

mbrtoc16函数

概要： 
#include <uchar.h>
size_t mbrtoc16(char16_t * restrict pc16,
      const char * restrict s, size_t n,
      mbstate_t * restrict ps);
描述：

如果参数s是空指针，mbrtoc16函数等价于

mbrtoc16(NULL, "", 1, ps)

这种情况下，参数pc16和参数n的值将被忽略。


如果参数s不是空指针，函数从参数s指向的字节开始检查最多n个字节，以确定构成一个多字节字符所需的字节数(包括移位序列)。如果函数确定多字节字符是完整并且有效的，函数将确定对应宽字符的值；如果参数pc16不是空指针，函数将存储第一个（或者唯一的）宽字符的值到参数pc16指向的对象中。后续调用函数将存储连续的宽字符，而不会消耗任何额外的输入，直至所有宽字符都已存储。如果对应的宽字符是空宽字符，结果状态将是初始转换状态。

参数：
char16_t * restrict pc16

指向char16_t类型对象的指针。

如果参数pc16是空指针，函数不会存储转换后的结果宽字符，但仍然会返回对应的多字节字符的字节数；如果参数pc16不是空指针，函数将存储转换后的结果宽字符，并返回对应的多字节字符的字节数。

const char * restrict s

指向多字节字符第一个字节的指针。

size_t n

最多检查的字节数。

宏MB_CUR_MAX定义了当前语言环境下构成一个多字节字符的最大字节数。

mbstate_t * restrict ps

指向mbstate_t类型对象的指针，该对象描述了多字节字符序列的当前转换状态，函数会根据需要对其进行更改。

如果参数ps是空指针，函数会使用内部mbstate_t对象，该对象在程序启动时初始化为初始转换状态；这种情况下，mbrtoc16函数不要求避免与其它mbrtoc16函数调用发生数据竞争。实现应像没有库函数使用ps空指针调用mbrtoc16函数一样。

返回值：

如果接下来的n个字节或者更少字节构成的多字节字符对应的宽字符是空宽字符，函数返回0。

如果接下来的n个字节或者更少字节构成有效的多字节字符，函数返回多字节字符的字节数，其值域区间为[1,n]。

如果前一次调用生成的下一个字符已经被存储（本次调用没有输入字节被消耗。），函数返回(size_t)(-3)。

如果接下来的n个字节不能构成完整的多字节字符(但可能是有效的。)，并且所有n个字节都已经被处理（没有值被存储。），函数返回(size_t)(-2)。

注：当参数n值至少为MB_CUR_MAX时，这种情况只有在参数s指向冗余移位序列（redundant shift sequences）时才会发生（实现存在依赖状态的编码。）。

如果接下来的n个字节或者更少字节不能构成完整且有效的多字节字符，将发生编码错误；宏EILSEQ存入errno，并且转换状态是不明确的，函数返回(size_t)(-1)。

范例： 
1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
/*函数mbrtoc16范例*/

#include <locale.h>
#include <stdlib.h>
#include <uchar.h>
#include <wchar.h>

#define LENGTH 10

int main(void)
{
    setlocale(LC_CTYPE, "");

    const char str[] = u8"中国CN";
    static mbstate_t mbs;
    char *strBegin = str;       //指向存储UTF-8字符串数组的指针。
    char16_t wArr[LENGTH];
    char16_t *wPtr = wArr;      //指向存储转换后16位字符的数组的指针。
    size_t number;              //有效多字节字符的字节数。

    /*转换前。*/
    wprintf(L"转换前UTF-8字符串占有%d个字节。\n", sizeof(str)/sizeof(str[0]));

    /*将UTF-8字符转换为16位字符。*/
    while(number = mbrtoc16(wPtr, strBegin, MB_CUR_MAX, &mbs))
    {
        if(number == (size_t)(-1))
        {
            wprintf(L"非法序列。\n");
            break;
        }
        else if(number == (size_t)(-2))
        {
            wprintf(L"不完整的多字节字符。\n");
            break;
        }
        else if(number == (size_t)(-3))
        {
            wprintf(L"字符已经存储。\n");
            ++wPtr;
        }
        else
        {
            strBegin += number;
            ++wPtr;
        }
    }

    /*转换后。*/
    wprintf(L"转换后得到%d个16位宽字符。\n", (wPtr-wArr+1));
    
    return 0;
}
输出：

转换前UTF-8字符串占有9个字节。

转换后得到5个16位宽字符。

注：使用ideone编译。

相关内容：
c16rtomb 将16位宽字符转换为多字节字符序列的函数。
mbrtoc32 将多字节字符序列转换为32位宽字符的函数。
c32rtomb 将32位宽字符转换为多字节字符序列的函数。