libs/src/str/strparse.3

   1 .\"(c) Copyright 1992, 1993 by Panagiotis Tsirigotis
   2 .\"All rights reserved.  The file named COPYRIGHT specifies the terms
   3 .\"and conditions for redistribution.
   4 .\"
   5 .\" $Id: strparse.3,v 1.1.1.1 2003/02/19 17:29:27 bbraun Exp $
   6 .TH STRPARSE 3X "30 September 1992"
   7 .SH NAME
   8 str_parse, str_endparse, str_component, str_separator, str_nextpos
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 .ft B
  13 #include "str.h"
  14 .LP
  15 .ft B
  16 str_h str_parse( str, separ, flags, errnop )
  17 char *str ;
  18 char *separ ;
  19 int flags ;
  20 int *errnop ;
  21 .LP
  22 .ft B
  23 void str_endparse( handle )
  24 str_h handle ;
  25 .LP
  26 .ft B
  27 char *str_component( handle )
  28 str_h handle ;
  29 .LP
  30 .ft B
  31 int str_setstr( handle, newstr )
  32 str_h handle ;
  33 char *newstr ;
  34 .LP
  35 .ft B
  36 int str_separator( handle, separ )
  37 str_h handle ;
  38 char *separ ;
  39 .LP
  40 .ft B
  41 char *str_nextpos( handle )
  42 str_h handle ;
  43 .LP
  44 extern int str_errno ;
  45 .SH DESCRIPTION
  46 .LP
  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.
  50 .LP
  51 .B str_component()
  52 returns successive substrings of the string.
  53 .B str_parse()
  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:
  59 .TP 20
  60 .SB STR_RETURN_ERROR
  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.
  64 .TP
  65 .SB STR_NULL_START
  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.
  68 .TP
  69 .SB STR_NULL_END
  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.
  72 .TP
  73 .SB STR_MALLOC
  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.
  78 .LP
  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.
  82 If \fIerrnop\fR
  83 is
  84 .SM NULL
  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
  88 .SM NULL.
  89 In this case, a subsequent
  90 .B str_setstr()
  91 should be used to specify the string to be processed.
  92 .LP
  93 .B str_component()
  94 returns successive substrings from the string associated with the
  95 parser specified by \fIhandle\fR.
  96 .LP
  97 .B str_endparse()
  98 destroys the parser specified by \fIhandle\fR.
  99 .LP
 100 .B str_setstr()
 101 changes the processed string to \fInewstr\fP.
 102 .LP
 103 .B str_separator()
 104 replaces the list of separator characters with \fIsepar\fR.
 105 Processing continues from the current position.
 106 .LP
 107 .B str_nextpos()
 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
 111 .SM NUL
 112 ).
 113 .SH "RETURN VALUES"
 114 .LP
 115 .B str_parse()
 116 returns a parser handle or
 117 .SM NULL
 118 if something goes wrong and \fIflags\fR & \fBSTR_RETURN_ERROR\fR is true.
 119 Possible \fIstr_errno\fR values:
 120 .RS
 121 .TP 20
 122 .SB STR_ENULLSEPAR
 123 \fIsepar\fR is
 124 .SM NULL
 125 .TP
 126 .SB STR_ENOMEM
 127 the program ran out of memory
 128 .RE
 129 .LP
 130 .B str_component()
 131 returns a pointer to the next substring or
 132 .SM NULL
 133 if something goes wrong and \fIflags\fR & \fBSTR_RETURN_ERROR\fR is true.
 134 .LP
 135 .B str_setstr()
 136 returns
 137 .SB STR_OK
 138 on success or
 139 .SB STR_ERR
 140 on failure.
 141 .LP
 142 .B str_separator()
 143 returns
 144 .SB STR_OK
 145 on success or
 146 .SB STR_ERR
 147 on failure.
 148 .LP
 149 .B str_nextpos()
 150 returns a pointer or
 151 .SM NULL
 152 if the end of string has been reached.
 153 .SH BUGS
 154 .B str_component()
 155 modifies the string unless \fBSTR_MALLOC\fR is
 156 set in the parser.
 157 .LP
 158 There should be only one parser active on a specific string. If there
 159 is more than
 160 one, they all must use the \fBSTR_MALLOC\fR option.
 161