wcstok, wcstok_s

在標頭檔案 `<wchar.h>` 中定義
	(1)
wchar_t* wcstok( wchar_t* str, const wchar_t* delim, wchar_t** ptr );			(自 C95 起) (直到 C99)
wchar_t* wcstok( wchar_t* restrict str, const wchar_t* restrict delim, wchar_t** restrict ptr );			(C99 起)
wchar_t* wcstok_s( wchar_t* restrict str, rsize_t* restrict strmax, const wchar_t* restrict delim, wchar_t** restrict ptr);		(2)	(C11 起)

1) 在 str 指向的空終止寬字串中查詢下一個標記。分隔符由 delim 指向的空終止寬字串標識。

此函式設計為多次呼叫，以從同一個字串中獲取連續的標記。

如果 str != NULL，則此呼叫被視為此特定寬字串的第一次 wcstok 呼叫。該函式搜尋第一個不在 delim 中的寬字元。

如果未找到此類寬字元，則 str 中根本沒有標記，函式返回一個空指標。
如果找到此類寬字元，則它是標記的開頭。然後函式從該點開始搜尋第一個在 delim 中的寬字元。

如果未找到此類寬字元，則 str 只有一個標記，並且未來對 wcstok 的呼叫將返回空指標。
如果找到此類寬字元，則它被替換為空寬字元 L'\0'，並且解析器狀態（通常是指向後續寬字元的指標）儲存在使用者提供的位置 *ptr 中。

函式然後返回指向標記開頭的指標。

如果 str == NULL，則此呼叫被視為對 wcstok 的後續呼叫：函式從上次呼叫中斷的地方繼續，使用相同的 *ptr。其行為與將指向最後一個檢測到的標記後面的寬字元的指標作為 str 傳遞相同。

2) 與 (1) 相同，除了每一步都將 str 中剩餘的字元數寫入 *strmax。重複呼叫（使用空 str）必須將 strmax 和 ptr 都與上次呼叫儲存的值一起傳遞。此外，以下錯誤在執行時被檢測到並呼叫當前安裝的約束處理程式函式，而不將任何內容儲存到 ptr 指向的物件中。

strmax、delim 或 ptr 是空指標。
在非初始呼叫（使用空 str）上，*ptr 是空指標。
在第一次呼叫時，*strmax 為零或大於 RSIZE_MAX / sizeof(wchar_t)。
搜尋標記的末尾到達源字串的末尾（由 *strmax 的初始值測量），但未遇到空終止符。

與所有邊界檢查函式一樣，只有當實現定義了 __STDC_LIB_EXT1__ 並且使用者在包含 <wchar.h> 之前將 __STDC_WANT_LIB_EXT1__ 定義為整數常量 1 時，才能保證 wcstok_s 可用。

str	-	指向要標記化的空終止寬字串的指標。
delim	-	指向標識分隔符的空終止寬字串的指標。
ptr	-	指向 wchar_t* 型別的物件的指標，`wcstok` 和 `wcstok_s` 都使用它來儲存解析器的內部狀態。
strmax	-	指向一個物件的指標，該物件最初儲存 str 的大小：wcstok_s 儲存剩餘要檢查的字元數。

[編輯] 返回值

返回指向下一個標記開頭的指標，如果沒有更多標記則返回空指標。

[編輯] 注意

此函式是破壞性的：它將 L'\0' 字元寫入字串 str 的元素中。特別是，寬字串字面量不能用作 wcstok 的第一個引數。

與 strtok 不同，wcstok 不更新靜態儲存：它將解析器狀態儲存在使用者提供的位置。

與大多數其他標記器不同，wcstok 中的分隔符可以為每個後續標記而不同，甚至可以取決於前一個標記的內容。

Windows CRT 中 wcstok_s 的實現與 C 標準不相容，它只是 wcstok 的別名。

[編輯] 示例

執行此程式碼

#include <stdio.h>
#include <wchar.h>
 
int main(void)
{
    wchar_t input[] = L"A bird came down the walk";
    printf("Parsing the input string '%ls'\n", input);
    wchar_t* buffer;
    wchar_t* token = wcstok(input, L" ", &buffer);
    while (token)
    {
        printf("%ls\n", token);
        token = wcstok(NULL, L" ", &buffer);
    }
 
    printf("Contents of the input string now: '");
    for (size_t n = 0; n < sizeof input / sizeof *input; ++n)
        input[n] ? printf("%lc", input[n]) : printf("\\0");
    puts("'");
}

輸出

Parsing the input string 'A bird came down the walk'
A
bird
came
down
the
walk
Contents of the input string now: 'A\0bird\0came\0down\0the\0walk\0'

[編輯] 參考

C11 標準 (ISO/IEC 9899:2011)

7.29.4.5.7 wcstok 函式 (p: 437-438)

K.3.9.2.3.1 wcstok_s 函式 (p: 645-646)

C99 標準 (ISO/IEC 9899:1999)

7.24.4.5.7 wcstok 函式 (p: 383-384)

[編輯] 另請參閱

strtokstrtok_s (C11)	查詢位元組字串中的下一個標記 (函式) [編輯]
C++ 文件 for wcstok

編譯器支援
語言
標頭檔案
型別支援
程式工具
變參函式支援
錯誤處理
動態記憶體管理
字串庫
演算法
數值
日期和時間工具
輸入/輸出支援
本地化支援
併發支援 (C11)
技術規範
符號索引

cppreference.com

名稱空間

變體

檢視

操作