diff options
Diffstat (limited to 'autoopts/ao_string_tokenize.3')
| -rw-r--r-- | autoopts/ao_string_tokenize.3 | 86 |
1 files changed, 86 insertions, 0 deletions
diff --git a/autoopts/ao_string_tokenize.3 b/autoopts/ao_string_tokenize.3 new file mode 100644 index 0000000..5c3e6a2 --- /dev/null +++ b/autoopts/ao_string_tokenize.3 @@ -0,0 +1,86 @@ +.TH ao_string_tokenize 3 2012-08-11 "" "Programmer's Manual" +.\" DO NOT EDIT THIS FILE (ao_string_tokenize.3) +.\" +.\" It has been AutoGen-ed August 11, 2012 at 09:44:56 AM by AutoGen 5.16.2 +.\" From the definitions ./funcs.def +.\" and the template file agman3.tpl +.SH NAME +ao_string_tokenize - tokenize an input string +.sp 1 +.SH SYNOPSIS + +#include <\fIyour-opts.h\fP> +.br +cc [...] -o outfile infile.c -l\fBopts\fP [...] +.sp 1 +token_list_t* \fBao_string_tokenize\fP(char const* \fIstring\fP); +.sp 1 +.SH DESCRIPTION +This function will convert one input string into a list of strings. +The list of strings is derived by separating the input based on +white space separation. However, if the input contains either single +or double quote characters, then the text after that character up to +a matching quote will become the string in the list. + +The returned pointer should be deallocated with \fBfree(3C)\fP when +are done using the data. The data are placed in a single block of +allocated memory. Do not deallocate individual token/strings. + +The structure pointed to will contain at least these two fields: +.sp +.IR "tkn_ct" +The number of tokens found in the input string. +.sp +.IR "tok_list" +An array of \fBtkn_ct + 1\fP pointers to substring tokens, with +the last pointer set to NULL. +.br + +There are two types of quoted strings: single quoted (\fB'\fP) and +double quoted (\fB"\fP). Singly quoted strings are fairly raw in that +escape characters (\fB\\\fP) are simply another character, except when +preceding the following characters: +.nf + \fB\\\fP double backslashes reduce to one + \fB'\fP incorporates the single quote into the string + \fB\n\fP suppresses both the backslash and newline character +.fi + +Double quote strings are formed according to the rules of string +constants in ANSI-C programs. +.TP +.IR string +string to be tokenized +.sp 1 +.SH RETURN VALUE +pointer to a structure that lists each token +.sp 1 +.SH ERRORS +NULL is returned and \fBerrno\fP will be set to indicate the problem: +.sp 1ize @bullet +.sp 1 +\fBEINVAL\fP \- There was an unterminated quoted string. +.sp 1 +\fBENOENT\fP \- The input string was empty. +.sp 1 +\fBENOMEM\fP \- There is not enough memory. +@end itemize +.sp 1 +.SH EXAMPLES +.nf +.in +5 +.nf + #include <stdlib.h> + int ix; + token_list_t* ptl = ao_string_tokenize(some_string) + for (ix = 0; ix < ptl->tkn_ct; ix++) + do_something_with_tkn(ptl->tkn_list[ix]); + free(ptl); +.fi +Note that everything is freed with the one call to \fBfree(3C)\fP. +.in -5 +.fi +.SH SEE ALSO +The \fIinfo\fP documentation for the -l\fIopts\fP library. +.br +configFileLoad(3), optionFileLoad(3), optionFindNextValue(3), optionFindValue(3), optionFree(3), optionGetValue(3), optionLoadLine(3), optionNextValue(3), optionOnlyUsage(3), optionProcess(3), optionRestore(3), optionSaveFile(3), optionSaveState(3), optionUnloadNested(3), optionVersion(3), pathfind(3), strequate(3), streqvcmp(3), streqvmap(3), strneqvcmp(3), strtransform(3), |