1
.\"(c) Copyright 1992, 1993 by Panagiotis Tsirigotis
2
.\"All rights reserved. The file named COPYRIGHT specifies the terms
3
.\"and conditions for redistribution.
5
.\" $Id: strparse.3,v 1.1.1.1 2003/02/19 17:29:27 bbraun Exp $
6
.TH STRPARSE 3X "30 September 1992"
8
str_parse, str_endparse, str_component, str_separator, str_nextpos
16
str_h str_parse( str, separ, flags, errnop )
23
void str_endparse( handle )
27
char *str_component( handle )
31
int str_setstr( handle, newstr )
36
int str_separator( handle, separ )
41
char *str_nextpos( handle )
44
extern int str_errno ;
47
These functions are useful for parsing strings. In this context
48
parsing means breaking the string into substrings. The substrings are
49
separated by a list of possible separator characters.
52
returns successive substrings of the string.
54
creates and initializes a string parser with the string
55
that will be processed, \fIstr\fR, the list of possible separator
56
characters, \fIsepar\fR, and flags that control how the parser
57
works. The \fIflags\fR argument is formed by ORing one or more of
58
the following constants:
61
If something goes wrong return a value that indicates that an error occured
62
(e.g. out of memory). The default is for the program to be terminated
63
with an appropriate error message.
66
If \fIstr\fR starts with a separator then a zero-length string will be returned
67
the first time \fBstr_component()\fR is called.
70
If \fIstr\fR ends with a separator then a zero-length string will be returned
71
by \fBstr_component()\fR when the substrings of \fIstr\fR are exhausted.
74
The strings returned by \fBstr_component()\fR will be in malloc'ed memory.
75
By default the substrings are part of \fIstr\fR.
76
If this option is not used \fIstr\fR will be modified
77
by \fBstr_component()\fR.
79
Finally, \fBSTR_NOFLAGS\fR may be used to specify no flags.
80
The \fIerrnop\fR argument points to an integer where the string processing
81
functions will deposit an error code if an error occurs.
85
the error codes will be placed in \fIstr_errno\fR.
86
This is useful only if \fBSTR_RETURN_ERROR\fR is used in \fIflags\fR.
87
It is possible that \fIstr\fP is
89
In this case, a subsequent
91
should be used to specify the string to be processed.
94
returns successive substrings from the string associated with the
95
parser specified by \fIhandle\fR.
98
destroys the parser specified by \fIhandle\fR.
101
changes the processed string to \fInewstr\fP.
104
replaces the list of separator characters with \fIsepar\fR.
105
Processing continues from the current position.
108
returns a pointer to the rest of the string. The previous character
109
is a separator character (if \fBSTR_MALLOC\fR is not set, then the
110
previous character is
116
returns a parser handle or
118
if something goes wrong and \fIflags\fR & \fBSTR_RETURN_ERROR\fR is true.
119
Possible \fIstr_errno\fR values:
127
the program ran out of memory
131
returns a pointer to the next substring or
133
if something goes wrong and \fIflags\fR & \fBSTR_RETURN_ERROR\fR is true.
152
if the end of string has been reached.
155
modifies the string unless \fBSTR_MALLOC\fR is
158
There should be only one parser active on a specific string. If there
160
one, they all must use the \fBSTR_MALLOC\fR option.