C++

參考

<cstdlib> (stdlib.h)

函式
<cstdlib>

wcstombs

size_t wcstombs (char* dest, const wchar_t* src, size_t max);
將寬字元字串轉換為多位元組字串
將 src 指向的序列中的寬字元翻譯成多位元組等效序列（儲存在 dest 指向的陣列中），直到翻譯的位元組數達到 max 或直到遇到一個轉換為 *空字元* 的寬字元為止。

如果成功翻譯了 max 個位元組，則儲存在 dest 中的結果字串將不會以空字元終止。

結果多位元組序列以初始移位狀態（如果有）開始。

此函式行為取決於所選的 C 語言環境的 LC_CTYPE 類別。

引數

dest
指向一個足夠長的 char 元素陣列的指標，該陣列能夠容納結果序列（最多 max 位元組）。
src
要翻譯的 C 寬字串。
max
要寫入 dest 的位元組數上限。
size_t 是一個無符號整數型別。

返回值

寫入 dest 的位元組數，不包括最終的空終止字元。
如果遇到一個不對應有效多位元組字元的寬字元，將返回一個 (size_t)-1 的值。
請注意，size_t 是一個無符號整數型別，因此可能返回的值中沒有小於零的。

示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
 
/* wcstombs example */
#include <stdio.h>      /* printf */
#include <stdlib.h>     /* wcstombs, wchar_t(C) */

int main() {
  const wchar_t str[] = L"wcstombs example";
  char buffer[32];
  int ret;

  printf ("wchar_t string: %ls \n",str);

  ret = wcstombs ( buffer, str, sizeof(buffer) );
  if (ret==32) buffer[31]='\0';
  if (ret) printf ("multibyte string: %s \n",buffer);

  return 0;
}

輸出

wchar_t string: wcstombs example 
multibyte string:  wcstombs example


資料競爭

該函式訪問 src 指向的陣列，並修改 dest 指向的陣列。
該函式還可能訪問和修改一個內部狀態物件，如果實現使用靜態物件，這可能導致併發呼叫此函式時出現數據競爭（請參閱 wcsrtombs 以瞭解可以使用外部狀態物件的替代方法）。
併發地更改 locale 設定也可能引入資料競爭。

異常 (C++)

無丟擲保證：此函式不會丟擲異常。

如果 dest 不指向足以容納翻譯後序列的陣列，或者 src 不是以空字元結尾的，或者不包含足夠多的寬字元以生成 max 個多位元組字元序列，則會導致 *未定義行為*。

另見

mblen
獲取多位元組字元的長度 (函式)
wctomb
將寬字元轉換為多位元組序列 (函式)
mbstowcs
將多位元組字串轉換為寬字串 (函式)