Next: str_tokbq_init, Previous: str_tokbqenize_free, Up: Strings
split a quoted string at specified delimiters
#include <suplib/str.h>char *str_tokbq( char *string, const char *delim, const char *open_quote, const char *close_quote, char escape_char, int actions, struct str_tokbqdata *tbqd, int *error );
char *string
- the string to parse
const char *delim
- the set of characters that delimit tokens
const char *open_quote
- the set of characters that delimit opening quotes. e.g., ‘"'{[’
const char *close_quote
- the set of matching characters that delimit closing quotes. These must be in the same order as the opening characters in
open_quote
, e.g., ‘"'}]’char escape_char
- the escape character
int actions
- skip, restore, and escape modes
struct str_tokbqdata *tbqd
- state information
int *error
- returned error code
This routine works like strtok
, except that it
understands escaped characters and quoted strings. It handles
balanced quote characters (i.e. ‘[’ and ‘]’). It does
not handle nested quotes.
It can collapse consecutive delimiter characters, or generate empty
tokens. For example, if the delimiter is ‘,’, parsing of the
string ",,a" would return three tokens, the first two empty
strings. Additionally str_tokbq
can be instructed to
restore the parsed string to its initial state (normally it sticks
‘\0’ where the delimiter characters are).
str_tokbq
is invoked multiple times, once per token. Unlike
str_tok
, str_tokbq
stores all of its state
information externally, in a caller provided structure. This must
be initialized with str_tokbq_init
before the first call to
str_tokbq
. The contents are unique to each parsed string.
Delimiters, quote characters, and the escape character may be changed between calls.
Each invocation of str_tokbq
returns a pointer to the next
token. If no more tokens are available, it returns NULL
.
If skip mode is on an empty string is considered to have no tokens.
If skip mode is off, an empty string is considered to have a single
token.
The actions
flag is used to specify how to handle
consecutive delimiters, string restoration, and whether to
recognize escape sequence. The following flags (which may be
combined with |
are available:
STRTOK_ESCAPE
escape_char
parameter.
STRTOK_RESTORE str_tokbq replaces delimiter characters
str_tokbq
to restore the character from the previous
call. To fully restore the string to its original state, the
caller must either repeatedly invoke str_tokbq
until it
returns a NULL
or invoke the str_tokbq_restore
function.
STRTOK_SKIP
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’).
On error, str_tokbq
returns NULL
and stores an error
code in *error
. The following errors are recognized:
EINVAL