wcstok_s.c File Reference

#include "safe_str_lib.h"

Include dependency graph for wcstok_s.c:

Functions
EXPORT wchar_t *	wcstok_s (wchar_t *restrict dest, rsize_t *restrict dmax, const wchar_t *restrict delim, wchar_t **restrict ptr)
	A sequence of calls to the wcstok_s function breaks the string pointed to by dest into a sequence of tokens, each of which is delimited by a character from the string pointed to by delim. More...

Function Documentation

wcstok_s()

EXPORT wchar_t* wcstok_s	(	wchar_t *restrict	dest,
		rsize_t *restrict	dmax,
		const wchar_t *restrict	delim,
		wchar_t **restrict	ptr
	)

A sequence of calls to the wcstok_s function breaks the string pointed to by dest into a sequence of tokens, each of which is delimited by a character from the string pointed to by delim.

The fourth argument points to a caller-provided char pointer into which the wcstok_s function stores information necessary for it to continue scanning the same string.

The first call in a sequence has a non-null first argument and dmax points to an object whose value is the number of elements in the character array pointed to by the first argument. The first call stores an initial value in the object pointed to by ptr and updates the value pointed to by dmax to reflect the number of elements that remain in relation to ptr. Subsequent calls in the sequence have a null first argument and the objects pointed to by dmax and ptr are required to have the values stored by the previous call in the sequence, which are then updated. The separator string pointed to by delim may be different from call to call.

The first call in the sequence searches the string pointed to by dest for the first character that is not contained in the current separator string pointed to by delim. If no such character is found, then there are no tokens in the string pointed to by dest and the wcstok_s function returns a null pointer. If such a character is found, it is the start of the first token.

The wcstok_s function then searches from there for the first character in dest that is contained in the current separator string. If no such character is found, the current token extends to the end of the string pointed to by dest, and subsequent searches in the same string for a token return a null pointer. If such a character is found, it is overwritten by a null character, which terminates the current token.

In all cases, the wcstok_s function stores sufficient information in the pointer pointed to by ptr so that subsequent calls, with a null pointer for dest and the unmodified pointer value for ptr, shall start searching just past the element overwritten by a null character (if any).

delim uses a STRTOK_DELIM_MAX_LEN of 16.

Remarks

SPECIFIED IN

• C11 standard (ISO/IEC 9899:2011): K.3.7.3.1 The wcstok_s function (p: 620-621) http://en.cppreference.com/w/c/string/byte/strok
• ISO/IEC TR 24731-1, Programming languages, environments and system software interfaces, Extensions to the C Library, Part I: Bounds-checking interfaces

Parameters

[in]	dest	pointer to string to tokenize
[out]	dmax	restricted maximum length of dest string
[in]	delim	pointer to delimiter string (len < 255)
[out]	ptr	returned pointer to token

Precondition

delim shall not be a null pointer.

ptr shall not be a null pointer.

dmax shall not be a null pointer.

*dmax shall not be 0.

If dest is a null pointer, then *ptr shall not be a null pointer.

dest must not be unterminated.

The value of *dmax shall not be greater than RSIZE_MAX_WSTR. The end of the token found shall occur within the first *dmax characters of dest for the first call, and shall occur within the first *dmax characters of where searching resumes on subsequent calls.

delim must not be longer than STRTOK_DELIM_MAX_LEN (default: 16).

Note

The mingw MINGW_HAS_SECURE_API declares it without the dmax argument and without restrict. Skip it there. wchar_t* wcstok_s(wchar_t *str, const wchar_t *delim, wchar_t **next_token)

C11 uses RSIZE_MAX, not RSIZE_MAX_WSTR.

Returns

The wcstok_s function returns a pointer to the first character of a token; or a null pointer if there is no token or there is a runtime-constraint violation. Each call modifies dest by substituting a wide NULL character for the first delimiter that occurs after the returned token. If there is a runtime-constraint violation, the strtok_s function does not indirect through the dest/delim pointers, and does not store a value in the object pointed to by ptr.

errno is set to: ESNULLP when dest/delim/ptr is NULL pointer ESZEROL when *dmax = 0 ESLEMAX when *dmax > RSIZE_MAX_WSTR ESUNTERM when unterminated string C11 just returns EINVAL

Remarks

Example to demonstrate usage of wcstok_s() to tokenize a string

// Approach1: sequential wcstok_s() calls
str1 = L",.:*one,two;three,;four*.*.five-six***"; // String to tokenize 
len = 38;
str2 = L",.;*"; // String of delimiters

p2tok = wcstok_s(str1, &len, str2, &p2str); 
// token: one, remaining: two;three,;four*.*.five-six***, len: 30

p2tok = wcstok_s(NULL, &len, str2, &p2str);
// token: two, remaining: three,;four*.*.five-six***, len: 26

p2tok = wcstok_s(NULL, &len, str2, &p2str);
// token: three,  remaining: ;four*.*.five-six***, len: 20

p2tok = wcstok_s(NULL, &len, str2, &p2str);
// token: four, remaining .*.five-six***, len: 14

p2tok = wcstok_s(NULL, &len, str2, &p2str);
// token: five-six, remaining: **, len: 2

 p2tok = wcstok_s(NULL, &len, str2, &p2str);
 // token: (null), remaining: **, len: 0

 // Approach2: Use of while loop with same entry data as used above
 p2tok = str1;
 while (p2tok && len) 
 {
   p2tok = wcstok_s(NULL, &len, str2, &p2str);
   printf("  token --   remaining --  len=0 \n", p2tok, p2str, (int)len );
 }