wcsrtombs

项目
02/21/2013

将宽字符字符串转换为多字节字符字符串表示形式。此功能的一种较为安全的版本可用; wcsrtombs_s参见。

size_t wcsrtombs(
   char *mbstr,
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
size_t wcsrtombs(
   char (&mbstr)[size],
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
); // C++ only

参数

[out] mbstr
生成的已转换的多字节字符字符串的地址位置。
[in] wcstr
间接指向要转换的宽字符字符串的位置。
[in] count
将转换的字符数。
[in] mbstate
为 mbstate_t 转换状态对象的指针。

返回值

返回成功转换的字节数，不包括终止 null 字节 (如果有)，否则 a-1 为 null，如果错误。

备注

wcsrtombs 函数将宽字符字符串开始，在 mbstate包含的指定转换状态，在 wcstr点的转换值取消，为 mbstr地址。转换为每个字符将继续直到:在终止宽字符的空遇到后，那么，当非对应的字符遇到或，如下字符将以上 count包含的限制。如果 wcsrtombs 遇到宽字符 null 字符 (L' \ 0 ") 或前面，或者 count 发生，则将其强制转换为 8 位 0 并停止。

因此，在转换过程中，，因此，只有当 wcsrtombs 遇到一个宽字符 null 字符在 mbstr 的多字节字符字符串 null 结尾。如果顺序指向由 wcstr 和 mbstr 重叠， wcsrtombs 行为不确定。 wcsrtombs 受当前区域设置的 LC_TYPE 类别的影响。

wcsrtombs 功能与 wcstombs， _wcstombs_l 不同由其 restartability。转换状态中的 mbstate 存储的后续调用相同或其他可重新启动的功能。，混合使用可重新启动和 nonrestartable 函数时，结果是未定义的。例如，应用程序将使用 wcsrlen 而不是 wcsnlen，因此，如果以后对 wcsrtombs 使用了而不是 wcstombs。

如果 mbstr 参数是 NULL， wcsrtombs 在目标字符串的字节返回需的范围。如果 mbstate 为空，使用内部 mbstate_t 转换状态。如果字符序列 wchar 没有相应的多字节字符表示形式， a-1 返回，并且 errno 设置为 EILSEQ。

在 C++ 中，该函数具有调用的模板重载越+新，保证此功能副本。有关更多信息，请参见安全模板重载。

异常

wcsrtombs 功能是多线程安全性，只要在当前线程的函数不调用 setlocale ，则此函数执行时，并 mbstate 不为 null。

示例

// crt_wcsrtombs.cpp
// compile with: /W3
// This code example converts a wide
// character string into a multibyte
// character string.

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

int main()
{
    const wchar_t   wcString[] = 
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    countConverted = wcsrtombs(mbString, &wcsIndirectString,
                               MB_BUFFER_SIZE, &mbstate); // C4996
    // Note: wcsrtombs is deprecated; consider using wcsrtombs_s
    if (errno == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else 
    {
        printf( "The string was successfuly converted.\n" );
    }
}