LAL  7.2.0.1-a5e7375
StringInput.h
Go to the documentation of this file.
1 /*
2 * Copyright (C) 2007 Jolien Creighton, Peter Shawhan
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation; either version 2 of the License, or
7 * (at your option) any later version.
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
13 *
14 * You should have received a copy of the GNU General Public License
15 * along with with program; see the file COPYING. If not, write to the
16 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
17 * MA 02110-1301 USA
18 */
19 
20 #ifndef _STRINGINPUT_H
21 #define _STRINGINPUT_H
22 
23 #include <lal/LALStdlib.h>
24 #include <lal/LALStdio.h>
25 
26 #if defined(__cplusplus)
27 extern "C" {
28 #elif 0
29 } /* so that editors will match preceding brace */
30 #endif
31 
32 
33 /**
34  * \defgroup StringInput_h Header StringInput.h
35  * \ingroup lal_std
36  * \author Creighton, T. D.
37  *
38  * \brief Provides routines to parse \c CHARVectors into other LAL datatypes.
39  *
40  * ### Synopsis ###
41  *
42  * \code
43  * #include "StringInput.h"
44  * \endcode
45  *
46  * This header provides prototypes for routines that construct
47  * LAL data structures using the data from a character string. As in
48  * standard C, a \e string is a block of non-null bytes of arbitrary
49  * length, terminated by a null byte <tt>'\0'</tt>, and referred to by a
50  * value of type <tt>CHAR *</tt> pointing to the first byte in the string.
51  * It is not to be confused with a \c CHARVector, a LAL structure
52  * referring to a block of data of a specified length, which may or may
53  * not contain one or more instances of <tt>'\0'</tt>.
54  *
55  * In general, the routines under this header will have string inputs of
56  * type <tt>const CHAR *</tt> (in order to allow, for instance, string
57  * literals to be used as inputs), but will allocate \c CHARVector
58  * structures to store string outputs. Unless otherwise specified, these
59  * outputs are guaranteed to contain at least one <tt>'\0'</tt> character,
60  * so their \c data fields are valid strings. It is the
61  * responsibility of the calling routine to ensure that the string input
62  * contains a terminating <tt>'\0'</tt> within the memory segment pointed
63  * to by the <tt>CHAR *</tt> input, in order to avoid segmentation
64  * violation.
65  *
66  * These routines are intended to work in conjunction with the functions
67  * in <tt>StreamInput.h</tt> to add LAL robustness to otherwise ad-hoc data
68  * input routines. However, the functions in \ref StringInput.h are
69  * fully LAL-compliant and use only LAL types, so they are included in
70  * \c liblal proper.
71  *
72  * ### Constants ###
73  *
74  * The following constants are format strings that can be used by the
75  * various C <tt>scanf()</tt> or <tt>printf()</tt> functions to parse or
76  * write sequences of characters corresponding to base LAL datatypes.
77  * Since the C datatypes (\c short, \c int, \c long,
78  * <tt>long long</tt>, \c float, \c double, etc.) do not have fixed
79  * mappings to LAL base datatypes (\c INT2, \c INT4, \c INT8,
80  * \c REAL4, \c REAL8, etc.), the appropriate format strings for
81  * each LAL datatype must be determined at configuration time and set at
82  * compile time.
83  *
84  * These format strings give only the conversion character preceded by
85  * any length modifier according to the type (\c short, \c long,
86  * etc.). In particular they do \e not contain the initial
87  * <tt>'%'</tt> character that initiates the conversion specification.
88  * However, being <tt>\#define</tt>d string literals, they can be combined
89  * with <tt>"%"</tt> string literals or more complicated format strings
90  * through implicit concatenation. Thus to scan \c string for a
91  * \c UINT4 number \c n one would write:
92  * \code
93  * sscanf( string, "%" LAL_UINT4_FORMAT, &n );
94  * \endcode
95  * Similarly, to print a \c REAL8 number \c x with 12 digits
96  * following the decimal place, one could use the following:
97  * \code
98  * printf( "%.12" LAL_REAL8_FORMAT, x );
99  * \endcode
100  * Of course, floating-point numbers are more commonly printed using the
101  * <tt>"%e"</tt> conversion specifier, which does not generally require
102  * type-dependent length modifiers.
103  *
104  * <table>
105  * <tr><th>Name</th><th>Usual value</th></tr>
106  * <tr><td>#LAL_INT2_FORMAT</td><td><tt>"hd"</tt></td></tr>
107  * <tr><td>#LAL_INT4_FORMAT</td><td><tt>"d"</tt> or <tt>"ld"</tt></td></tr>
108  * <tr><td>#LAL_INT8_FORMAT</td><td><tt>"ld"</tt> or <tt>"lld"</tt></td></tr>
109  * <tr><td>#LAL_UINT2_FORMAT</td><td><tt>"hu"</tt></td></tr>
110  * <tr><td>#LAL_UINT4_FORMAT</td><td><tt>"u"</tt> or <tt>"lu"</tt></td></tr>
111  * <tr><td>#LAL_UINT8_FORMAT</td><td><tt>"lu"</tt> or <tt>"llu"</tt></td></tr>
112  * <tr><td>#LAL_REAL4_FORMAT</td><td><tt>"f"</tt></td></tr>
113  * <tr><td>#LAL_REAL8_FORMAT</td><td><tt>"lf"</tt></td></tr>
114  * </table>
115  *
116  */
117 /** @{ */
118 
119 /** \name Error Codes */ /** @{ */
120 #define STRINGINPUTH_ENUL 1 /**< Unexpected null pointer in arguments */
121 #define STRINGINPUTH_EOUT 2 /**< Output handle points to a non-null pointer */
122 #define STRINGINPUTH_EMEM 3 /**< Memory allocation error */
123 /** @} */
124 /** \cond DONT_DOXYGEN */
125 #define STRINGINPUTH_MSGENUL "Unexpected null pointer in arguments"
126 #define STRINGINPUTH_MSGEOUT "Output handle points to a non-null pointer"
127 #define STRINGINPUTH_MSGEMEM "Memory allocation error"
128 /** \endcond */
129 
130 /**
131  * This structure stores a number of null-terminated strings of arbitrary
132  * length. The entire list is stored flattened in a \c CHARVector,
133  * and individual tokens are pointed to by a <tt>CHAR *[]</tt> handle.
134  */
135 typedef struct tagTokenList {
136  UINT4 nTokens; /**< The number of tokens in the list */
137  CHAR **tokens; /**< A list of pointers to the individual tokens;
138  * the elements <tt>tokens[0..nTokens-1]</tt> point to tokens, and
139  * the element <tt>tokens[nTokens]</tt> is explicitly \c NULL (as is
140  the convention for an \c argv argument list */
142  /**< The flattened list of tokens, separated by (and terminated with) <tt>'\0'</tt> characters */
143 } TokenList;
144 
145 /** @} */
146 
147 /* Function prototypes. */
148 
149 void
151  TokenList ** list,
152  const CHAR * string, const CHAR * delimiters);
153 
155 
156 
157 int
159  const CHAR * string, const CHAR * delimiters);
160 
161 void XLALDestroyTokenList(TokenList * list);
162 
163 void
164 LALStringToU2(LALStatus * status, UINT2 * value, const CHAR * string,
165  CHAR ** endptr);
166 
167 void
168 LALStringToU4(LALStatus * status, UINT4 * value, const CHAR * string,
169  CHAR ** endptr);
170 
171 void
172 LALStringToU8(LALStatus * status, UINT8 * value, const CHAR * string,
173  CHAR ** endptr);
174 
175 void
176 LALStringToI2(LALStatus * status, INT2 * value, const CHAR * string,
177  CHAR ** endptr);
178 
179 void
180 LALStringToI4(LALStatus * status, INT4 * value, const CHAR * string,
181  CHAR ** endptr);
182 
183 void
184 LALStringToI8(LALStatus * status, INT8 * value, const CHAR * string,
185  CHAR ** endptr);
186 
187 void
188 LALStringToS(LALStatus * status, REAL4 * value, const CHAR * string,
189  CHAR ** endptr);
190 
191 void
192 LALStringToD(LALStatus * status, REAL8 * value, const CHAR * string,
193  CHAR ** endptr);
194 
195 void
196 LALStringToC(LALStatus * status, COMPLEX8 * value, const CHAR * string,
197  CHAR ** endptr);
198 
199 void
200 LALStringToZ(LALStatus * status, COMPLEX16 * value, const CHAR * string,
201  CHAR ** endptr);
202 
203 #if 0
204 { /* so that editors will match succeeding brace */
205 #elif defined(__cplusplus)
206 }
207 #endif
208 
209 #endif /* _STRINGINPUT_H */
UINT4 nTokens
The number of tokens in the list.
Definition: StringInput.h:136
void LALStringToD(LALStatus *status, REAL8 *value, const CHAR *string, CHAR **endptr)
int16_t INT2
Two-byte signed integer.
CHARVector * list
The flattened list of tokens, separated by (and terminated with) &#39;\0&#39; characters. ...
Definition: StringInput.h:141
void LALStringToI8(LALStatus *status, INT8 *value, const CHAR *string, CHAR **endptr)
void LALStringToI2(LALStatus *status, INT2 *value, const CHAR *string, CHAR **endptr)
void LALStringToC(LALStatus *status, COMPLEX8 *value, const CHAR *string, CHAR **endptr)
void LALStringToS(LALStatus *status, REAL4 *value, const CHAR *string, CHAR **endptr)
This structure stores a number of null-terminated strings of arbitrary length.
Definition: StringInput.h:135
void LALStringToZ(LALStatus *status, COMPLEX16 *value, const CHAR *string, CHAR **endptr)
char CHAR
One-byte signed integer, see Headers LAL(Atomic)Datatypes.h for more details.
void LALStringToU2(LALStatus *status, UINT2 *value, const CHAR *string, CHAR **endptr)
float complex COMPLEX8
Single-precision floating-point complex number (8 bytes total)
void LALDestroyTokenList(LALStatus *status, TokenList **list)
Definition: StringToken.c:241
float REAL4
Single precision real floating-point number (4 bytes).
void XLALDestroyTokenList(TokenList *list)
See StringToken.c for documentation.
Definition: StringToken.c:262
void LALStringToU8(LALStatus *status, UINT8 *value, const CHAR *string, CHAR **endptr)
uint64_t UINT8
Eight-byte unsigned integer; on some platforms this is equivalent to unsigned long int instead...
Vector of type CHAR, see DATATYPE-Vector types for more details.
Definition: LALDatatypes.h:73
double REAL8
Double precision real floating-point number (8 bytes).
LAL status structure, see The LALStatus structure for more details.
Definition: LALDatatypes.h:947
int XLALCreateTokenList(TokenList **list, const CHAR *string, const CHAR *delimiters)
Split given input string into a list of &#39;tokens&#39; separated by any of the characters given in &#39;delimit...
Definition: StringToken.c:168
uint32_t UINT4
Four-byte unsigned integer.
uint16_t UINT2
Two-byte unsigned integer.
double complex COMPLEX16
Double-precision floating-point complex number (16 bytes total)
int32_t INT4
Four-byte signed integer.
int64_t INT8
Eight-byte signed integer; on some platforms this is equivalent to long int instead.
CHAR ** tokens
A list of pointers to the individual tokens; the elements tokens[0..nTokens-1] point to tokens...
Definition: StringInput.h:137
void LALStringToU4(LALStatus *status, UINT4 *value, const CHAR *string, CHAR **endptr)
void LALStringToI4(LALStatus *status, INT4 *value, const CHAR *string, CHAR **endptr)
void LALCreateTokenList(LALStatus *status, TokenList **list, const CHAR *string, const CHAR *delimiters)
Definition: StringToken.c:76