Linux程序员手册 第3部分
更新日期： 2020-06-09

名称

mbstowcs-将多字节字符串转换为宽字符字符串

语法

#include <stdlib.h>

size_t mbstowcs(wchar_t *dest, const char *src, size_t n);

说明

如果dest不为NULL，则mbstowcs()函数将多字节字符串src转换为以dest开始的宽字符字符串。最多将n个宽字符写入dest。字符串src中的字符序列应从初始移位状态开始。转换可能由于以下三个原因而停止：

1.

遇到无效的多字节序列。在这种情况下，将返回(size_t)-1。

2.

n个非Laq \ 0aq宽字符已存储在dest。在这种情况下，返回了写入dest的宽字符数，但是此时的移位状态丢失了。

3.

多字节字符串已完全转换，包括终止的空字符(aq \ 0aq)。在这种情况下，将返回写入dest的宽字符数，但不包括终止的空宽字符。

程序员必须确保目标处至少有n个宽字符的空间。

如果dest为NULL，则n将被忽略，并且转换按上述方式进行，只是不将转换后的宽字符写出到内存中并且不存在长度限制。

为了避免上述情况2，程序员应确保n大于或等于mbstowcs(NULL，src，0)+1。

返回值

mbstowcs()函数返回组成宽字符字符串的转换部分的宽字符数，不包括终止的空宽字符。如果遇到无效的多字节序列，则返回(size_t)-1。

属性

有关本节中使用的术语的说明，请参见attribute(7)。

遵循规范

POSIX.1-2001，POSIX.1-2008，C99。

备注

mbstowcs()的行为取决于当前语言环境的LC_CTYPE类别。

函数mbsrtowcs(3)为相同的功能提供了更好的接口。

示例

下面的程序说明了mbstowcs()的用法，以及一些宽字符分类功能。运行示例如下：

$ ./t_mbstowcs de_DE.UTF-8 Grüße!
Length of source string (excluding terminator):
    8 bytes
    6 multibyte characters

Wide character string is: Grüße! (6 characters)
    G alpha upper
    r alpha lower
    ü alpha lower
    ß alpha lower
    e alpha lower
    ! !alpha

Program source

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

int
main(int argc, char *argv[])
{
    size_t mbslen;      /* Number of multibyte characters in source */
    wchar_t *wcs;       /* Pointer to converted wide character string */
    wchar_t *wp;

    if (argc < 3) {
        fprintf(stderr, "Usage: %s <locale> <string>\n", argv[0]);
        exit(EXIT_FAILURE);
    }

    /* Apply the specified locale */

    if (setlocale(LC_ALL, argv[1]) == NULL) {
        perror("setlocale");
        exit(EXIT_FAILURE);
    }

    /* Calculate the length required to hold argv[2] converted to
       a wide character string */

    mbslen = mbstowcs(NULL, argv[2], 0);
    if (mbslen == (size_t) -1) {
        perror("mbstowcs");
        exit(EXIT_FAILURE);
    }

    /* Describe the source string to the user */

    printf("Length of source string (excluding terminator):\n");
    printf("    %zu bytes\n", strlen(argv[2]));
    printf("    %zu multibyte characters\n\n", mbslen);

    /* Allocate wide character string of the desired size.  Add 1
       to allow for terminating null wide character (Laq##代码##aq). */

    wcs = calloc(mbslen + 1, sizeof(wchar_t));
    if (wcs == NULL) {
        perror("calloc");
        exit(EXIT_FAILURE);
    }

    /* Convert the multibyte character string in argv[2] to a
       wide character string */

    if (mbstowcs(wcs, argv[2], mbslen + 1) == (size_t) -1) {
        perror("mbstowcs");
        exit(EXIT_FAILURE);
    }

    printf("Wide character string is: %ls (%zu characters)\n",
            wcs, mbslen);

    /* Now do some inspection of the classes of the characters in
       the wide character string */

    for (wp = wcs; *wp != 0; wp++) {
        printf("    %lc ", (wint_t) *wp);

        if (!iswalpha(*wp))
            printf("!");
        printf("alpha ");

        if (iswalpha(*wp)) {
            if (iswupper(*wp))
                printf("upper ");

            if (iswlower(*wp))
                printf("lower ");
        }

        putchar(aq\naq);
    }

    exit(EXIT_SUCCESS);
}

另外参见

mblen(3)，mbsrtowcs(3)，mbtowc(3)，wcstombs(3)，wctomb(3)

出版信息

这个页面是Linux手册页项目5.08版的一部分。有关项目的说明、有关报告错误的信息以及此页面的最新版本，请访问https://www.kernel.org/doc/man-pages/。