Next: str_tokq_restore, Previous: str_tokenize_free, Up: Strings
split a string at specified delimiters
#include <suplib/str.h>char *str_tokq( char *string, const char *delim, int skip, int restore, char **ptr, char *dchar );
char *string
- the string to parse
const char *delim
- the set of characters that delimit tokens
int skip
- true if consecutive delimiters are treated as a single delimiter
int restore
- true if
str_tokq
should restore the delimiter character from the previous invocationchar **ptr
- state information needed by
str_tokq
char *dchar
- state information needed by
str_tokq
This routine works like strtok
, except that it understands
escaped characters (with ‘\’ as the escape character) and quoted
strings. It also can be told not to skip over multiple
consecutive delimiter characters (e.g., if the delimiter is ‘,’,
the string ",,a" will return three tokens, the first two empty strings).
Additionally str_tokq
can be instructed to restore the parsed string
to its initial state (normally it sticks ‘\0’ where the delimiter
characters are).
The invoking routine calls str_tokq
multiple times, once per token.
The first call should be made with string
set to the address of the
string to parse. On subsequent calls it should be set to NULL
.
The delimiters may be changed on subsequent calls.
Each invocation of str_tokq
returns a pointer to the next
token. If no more tokens are available, it returns NULL
.
If skip mode is on (the parameter skip
is non-zero), an
empty string is considered to have no tokens. If skip mode is off,
an empty string is considered to have a single token.
If the parameter restore
is non-zero, str_tokq
will restore
the delimiter character which was replaced by a ‘\0’ on the
previous call. Thus, to fully restore the string to its original
state, str_tokq
must be invoked repeatedly until it
returns a NULL
.
Escaped characters are recognized anywhere in a string. Quotes need not be the first character in a token (e.g., ‘foo" "bar’) will be treated as one token, and can be either single (both forward and backwards) or double. To embed quotes in like-quoted strings, escape them (e.g., ‘foo"\""bar’).
Unlike strtok
, str_tokq
is set up to allow concurrent use on
multiple strings. To accomplish this, all internal state information
is kept in two user supplied locations. The first (parameter ptr
),
is used by strtok
to keep track of where it is in the string. The
second, dchar
, contains the delimiter character that ended the
token. Please note that the invoking function must pass the
addresses of these locations to str_tokq
. Here's some
sample code:
char *ptr, dchar, *tok; tok = str_tokq(string, ",", 0, 1, &ptr, &dchar); while (tok) { ... process tokens ... tok = str_tokq(NULL, ",", 0, 1, &ptr, &dchar); }
On error, str_tokq
returns NULL
and sets errno
accordingly. The following errors are recognized:
EINVAL