共用方式為


mbsrtowcs

將目前地區設定的多位元組字元字串轉換成對應的寬字元字串,並提供在多位元組字元中間重新啟動的功能。 此函式有更安全的版本可供使用;請參閱 mbsrtowcs_s

語法

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

參數

wcstr
用來儲存所產生之已轉換寬字元字串的位址。

mbstr
要轉換之多位元組字元字串位置的間接指標。

count
要轉換並儲存在 wcstr 中的最大字元數 (而不是位元組)。

mbstate
mbstate_t 轉換狀態物件的指標。 如果此值為 null 指標,會使用靜態內部轉換狀態物件。 由於內部 mbstate_t 物件不是安全線程,因此建議您一律傳遞自己的 mbstate 參數。

傳回值

傳回成功轉換的字元數,但不包含結束的 null 字元 (如果有的話)。 如果發生錯誤,則傳回 (size_t)-1,並將 設定 errnoEILSEQ

備註

mbsrtowcs 函式會透過 mbstr 中包含的轉換狀態,將 wcstr 所間接指向的多位元組字元字串,轉換成儲存在緩衝區中由 mbstate 所指向的寬字元。 每個字元的轉換會繼續,直到遇到終止的 Null 多位元組位元、遇到對應到目前地區設定中有效字元的多位元組序列,或直到字元轉換為止 count 。 如果 mbsrtowcs 在發生 count 之前或期間遇到 null 多位元組字元 ('\0'),則會將字元轉換成 16 位元結束的 null 字元並停止。

因此,如果 wcstr 在轉換期間遇到 null 多位元組字元,則 mbsrtowcs 的寬字元字串只能以 null 結束。 如果 mbstrwcstr 所指向的序列重疊,mbsrtowcs 的行為不明。 mbsrtowcs 會受到 LC_TYPE 目前地區設定的類別影響。

函式mbsrtowcs_mbstowcs_lmbstowcs 不同之處在於其可重新啟動性。 針對相同或其他可重新啟動的函式的後續呼叫,轉換狀態會儲存在 mbstate 中。 混合使用可重新啟動和不可重新啟動之函式的結果不明。 例如,如果後續使用 對 mbsrtowcs 的呼叫,則應用程式應該使用 mbsrlen 而非mbslen,而不是 mbstowcs

如果 wcstr 不是 Null 指標,如果轉換因為到達終止的 Null 字元而停止,所指向 mbstr 的指針對象就會被指派為 Null 指標。 否則,它會在最後一個已轉換的多位元組位元元之後指派位址,如果有的話。 它允許後續的函式呼叫重新啟動此呼叫停止的轉換。

wcstr如果自變數是 Null 指標,count則會忽略自變數,並以mbsrtowcs寬字元傳回目的字串所需的大小。 如果 mbstate 是 null 指標,函式會使用非安全執行緒靜態內部 mbstate_t 轉換狀態物件。 如果字元序列 mbstr 沒有對應的多位元組字元表示法,則會傳回 -1,並將 errno 設定為 EILSEQ

如果 mbstr 為 null 指標,則會叫用無效的參數處理常式,如參數驗證中所述。 若允許繼續執行,此函式會將 errno 設為 EINVAL,並傳回 -1。

在 C++ 中,這個函式具有樣板多載,可以叫用比這個函式更新且更安全的相對版本。 如需詳細資訊,請參閱安全範本多載

根據預設,此函式的全域狀態會限定於應用程式。 若要變更此行為,請參閱 CRT 中的全域狀態

例外狀況

mbsrtowcs只要此函式正在執行mbstate,而且自變數不是 Null 指標,函式在目前線程中就不會呼叫setlocale任何函式,函式就會是多線程安全。

需求

常式 必要的標頭
mbsrtowcs <wchar.h>

另請參閱

資料轉換
地區設定
多位元組字元序列的解譯
mbrtowc
mbtowc, _mbtowc_l
mbstowcs, _mbstowcs_l
mbsinit