# mbrlen

< c‎ | string‎ | multibyte

定义于头文件 `<wchar.h>` |  |
size_t mbrlen( const char *s, size_t n, mbstate_t *ps ); |  | (C95 起) (C99 前)
size_t mbrlen( const char *restrict s, size_t n, mbstate_t *restrict ps ); |  | (C99 起)

给定当前转换状态 `ps` ，确定 `s` 所指向的剩余多字节字符的字节大小。

此函数等价于对于某个隐藏的 mbstate_t 类型对象 `internal` 调用 mbrtowc(NULL, s, n, ps?ps:&internal) ，除了只求值 `ps` 一次。

### 参数

s | - | 指向多字节字符串首元素的指针
n | - | s 中能检验的字节数限制
ps | - | 指向保有转换状态的对象的指针

### 返回值

应用下个首个可用者：

- ​0​ ，若接下来 `n` 个或更少字节组成空字符，或 `s` 为空指针。两种情况下都重置转换状态。
- 字节数 [1...n] ，这些字节组成合法的多字节字符。
- (size_t)-2 ，若接下来 `n` 个字节是可能合法的多字节字符的一部分，但在检验所有 `n` 个字节后仍不完整
- (size_t)-1 ，若出现编码错误。设置 errno 的值为 `EILSEQ` ；转换状态未指定。

### 示例

    #include <locale.h>
    #include <string.h>
    #include <stdio.h>
    #include <wchar.h>

    int main(void)
    {
        // 允许 mbrlen() 以 UTF-8 多字节编码工作
        setlocale(LC_ALL, "en_US.utf8");
        // UTF-8 窄多字节编码
        const char* str = u8"水";
        size_t sz = strlen(str);

        mbstate_t mb;
        memset(&mb, 0, sizeof mb);
        int len1 = mbrlen(str, 1, &mb);
        if(len1 == -2)
            printf("The first 1 byte of %s is an incomplete multibyte char"
                   " (mbrlen returns -2)\n", str);

        int len2 = mbrlen(str+1, sz-1, &mb);
        printf("The remaining %zu  bytes of %s hold %d bytes of the multibyte"
               " character\n", sz-1, str, len2);

        printf("Attempting to call mbrlen() in the middle of %s while in initial"
               " shift state returns %zd\n", str, mbrlen(str+1, sz-1, &mb));
    }

输出：

    The first 1 byte of 水 is an incomplete multibyte char (mbrlen returns -2)
    The remaining 2  bytes of 水 hold 2 bytes of the multibyte character
    Attempting to call mbrlen() in the middle of 水 while in initial shift state returns -1

### 引用

- C11 标准（ISO/IEC 9899:2011）：

  - 7.29.6.3.1 The mbrlen function (p: 442)

- C99 标准（ISO/IEC 9899:1999）：

  - 7.24.6.3.1 The mbrlen function (p: 388)

### 参阅

mbrtowc (C95) | 给定状态，将下一个多字节字符转换成宽字符 (函数)
mblen | 返回下一个多字节字符的字节数 (函数)