C 参考手册

位置:首页 > C 参考手册 >字符串库 >空终止宽字符串 > 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 )必须传递先前的调用用以存储值的 strmaxptr 。并且在运行时检测下列错误,并调用当前安装的制约处理函数:
  • strmaxdelimptr 为空指针
  • 在非首次调用(以空 str )时, *ptr 为空指针
  • 首次调用时, *strmax 为零或大于 RSIZE_MAX/sizeof(wchar_t)
  • 对记号的搜索抵达源字符串结尾(以 *strmax 的初值测量),而未遇到空终止符
同所有边界检查函数, wcstok_s 仅若实现定义了 __STDC_LIB_EXT1__ ,且用户在包含 wchar.h 前定义 __STDC_WANT_LIB_EXT1__ 为整数常量 1 才保证可用。

参数

str - 指向要记号化的空终止宽字符串的指针
delim - 指向标识分隔符的空终止宽字符串的指针
ptr - 指向 wchar_t* 类型对象的指针, wcstokwcstok_s 以之存储分析器的内部状态
strmax - 指向最初保有 str 大小的对象: wcstok_s 存储留待检验的字符数

返回值

返回指向下个记号起始的指针,或若无更多记号则为空指针。

注意

此函数是破坏性的:它写入 L'\0' 字符于字符串 str 的元素。特别是,宽字符串字面量不能用作 wcstok 的首参数。

不同于 strtokwcstok 不更新静态存储:它存储分析状态于用户提供的位置。

不同于大多数其他记号化器, wcstok 中的分隔符能对于后继记号不同,而且甚至能依赖于先前记号的内容。

示例

#include <wchar.h>
#include <stdio.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 standard (ISO/IEC 9899:2011):
  • 7.29.4.5.7 The wcstok function (p: 437-438)
  • K.3.9.2.3.1 The wcstok_s function (p: 645-646)
  • C99 standard (ISO/IEC 9899:1999):
  • 7.24.4.5.7 The wcstok function (p: 383-384)

参阅

查找字节字符串中的下一个记号
(函数)