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.