wcsrtombs

發行項
02/28/2013

將寬字元字串轉換成它的多位元組字元的字串表示。更安全版本之這個函式是可使用; see 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 終止 null 位元組 (如果有的話)，否則為-1，如果發生錯誤的數目。

備註

wcsrtombs函式將轉換寬字元字串，包含在指定的轉換狀態從mbstate，在所指到的值間接wcstr，插入地址的mbstr。轉換將會繼續直到每個字元：在遇到 null 終止寬字元，在遇到非對應的字元之後或下一個字元會超過配額限制包含在count。如果wcsrtombs之前或當遇到寬字元的 null 字元 ('\ 0' L) count ，就會發生，它將其轉換為 8 位元 0，並停駐點。

因此，在多位元組字元字串mbstr是 null 結尾時，才wcsrtombs在轉換過程中遇到一個寬字元的 null 字元。如果所指的序列wcstr和mbstr重疊，行為的wcsrtombs尚未定義。 wcsrtombs會影響目前的地區設定中的 [LC_TYPE] 類別。

wcsrtombs函式會不同於wcstombs _wcstombs_l由其重新。轉換狀態儲存在mbstate進行後續的呼叫至相同或其他可重新啟動的功能。混合的重新啟動的和即可函式使用時，結果是未定義。例如，應用程式會使用wcsrlen而不是wcsnlen，如果的後續呼叫wcsrtombs而不是使用wcstombs。

如果mbstr引數是NULL， wcsrtombs會傳回所需的大小以位元組為單位的目的字串。如果mbstate為 null，內部mbstate_t用轉換狀態。如果字元順序wchar並沒有相對應的多位元組字元表示法，傳回-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" );
    }
}