Next: , Previous: str_tokenize_free, Up: Strings


4.8 str_tokq

split a string at specified delimiters

Synopsis

     #include <suplib/str.h>
     
     
     
char *str_tokq( char *string, const char *delim, int skip, int restore, char **ptr, char *dchar );

Parameters

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 invocation
char **ptr
state information needed by str_tokq
char *dchar
state information needed by str_tokq

Description

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);
     }

Errors

On error, str_tokq returns NULL and sets errno accordingly. The following errors are recognized:

EINVAL
There were unbalanced quotes or the last character in the string was an escape character (i.e., no character to escape).