chiark / gitweb /
Commit as 2.1.0.
[mLib] / str.h
1 /* -*-c-*-
2  *
3  * $Id: str.h,v 1.5 2004/04/08 01:36:13 mdw Exp $
4  *
5  * Functions for hacking with strings
6  *
7  * (c) 1999 Straylight/Edgeware
8  */
9
10 /*----- Licensing notice --------------------------------------------------*
11  *
12  * This file is part of the mLib utilities library.
13  *
14  * mLib is free software; you can redistribute it and/or modify
15  * it under the terms of the GNU Library General Public License as
16  * published by the Free Software Foundation; either version 2 of the
17  * License, or (at your option) any later version.
18  *
19  * mLib is distributed in the hope that it will be useful,
20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
22  * GNU Library General Public License for more details.
23  *
24  * You should have received a copy of the GNU Library General Public
25  * License along with mLib; if not, write to the Free
26  * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
27  * MA 02111-1307, USA.
28  */
29
30 #ifndef MLIB_STR_H
31 #define MLIB_STR_H
32
33 #ifdef __cplusplus
34   extern "C" {
35 #endif
36
37 /*----- Header files ------------------------------------------------------*/
38
39 #include <stddef.h>
40
41 /*----- Functions provided ------------------------------------------------*/
42
43 /* --- @str_qword@ --- *
44  *
45  * Arguments:   @char **pp@ = address of pointer into string
46  *              @unsigned f@ = various flags
47  *
48  * Returns:     Pointer to the next space-separated possibly-quoted word from
49  *              the string, or null.
50  *
51  * Use:         Fetches the next word from a string.  If the flag
52  *              @STRF_QUOTE@ is set, the `\' character acts as an escape, and
53  *              single and double quotes protect whitespace.
54  */
55
56 #define STRF_QUOTE 1u
57
58 extern char *str_qword(char **/*pp*/, unsigned /*f*/);
59
60 /* --- @str_qsplit@ --- *
61  *
62  * Arguments:   @char *p@ = pointer to string
63  *              @char *v[]@ = pointer to array to fill in
64  *              @size_t c@ = count of strings to fill in
65  *              @char **rest@ = where to store the remainder of the string
66  *              @unsigned f@ = flags for @str_qword@
67  *
68  * Returns:     Number of strings filled in.
69  *
70  * Use:         Fills an array with pointers to the individual words of a
71  *              string.  The string is modified in place to contain zero
72  *              bytes at the word boundaries, and the words have leading
73  *              and trailing space stripped off.  No more than @c@ words
74  *              are read; the actual number is returned as the value of the
75  *              function.  Unused slots in the array are populated with
76  *              null bytes.  If there's any string left, the address of the
77  *              remainder is stored in @rest@ (if it's non-null); otherwise
78  *              @rest@ is set to a null pointer.
79  */
80
81 extern size_t str_qsplit(char */*p*/, char */*v*/[], size_t /*c*/,
82                          char **/*rest*/, unsigned /*f*/);
83
84 /* --- @str_getword@ --- *
85  *
86  * Arguments:   @char **pp@ = address of pointer into string
87  *
88  * Returns:     Pointer to the next space-separated word from the string,
89  *              or null.
90  *
91  * Use:         Parses off space-separated words from a string.  This is a
92  *              compatibility veneer over @str_qword@.
93  */
94
95 extern char *str_getword(char **/*pp*/);
96
97 /* --- @str_split@ --- *
98  *
99  * Arguments:   @char *p@ = pointer to string
100  *              @char *v[]@ = pointer to array to fill in
101  *              @size_t c@ = count of strings to fill in
102  *              @char **rest@ = where to store the remainder of the string
103  *
104  * Returns:     Number of strings filled in.
105  *
106  * Use:         Fills an array with pointers to the individual words of a
107  *              string.  This is a compatibility veneer over @str_qsplit@.
108  */
109
110 extern size_t str_split(char */*p*/, char */*v*/[],
111                         size_t /*c*/, char **/*rest*/);
112
113 /* --- @str_matchx@ --- *
114  *
115  * Arguments:   @const char *p@ = pointer to pattern string
116  *              @const char *s@ = string to compare with
117  *              @unsigned f@ = various flags
118  *
119  * Returns:     Nonzero if the pattern matches the string.
120  *
121  * Use:         Does simple wildcard matching.  This is quite nasty and more
122  *              than a little slow.  Supports metacharacters `*', `?' and
123  *              '['.
124  */
125
126 #define STRF_PREFIX 1u                  /* Accept if @s@ is exhausted during
127                                          *   the attempted match */
128
129 extern int str_matchx(const char */*p*/, const char */*s*/, unsigned /*f*/);
130
131 /* --- @str_match@ --- *
132  *
133  * Arguments:   @const char *p@ = pointer to pattern string
134  *              @const char *s@ = string to compare with
135  *
136  * Returns:     Nonzero if the pattern matches the string.
137  *
138  * Use:         Does simple wildcard matching.  Equivalent to @str_matchx@
139  *              with zero flags word.
140  */
141
142 extern int str_match(const char */*p*/, const char */*s*/);
143
144 /* --- @str_sanitize@ --- *
145  *
146  * Arguments:   @char *d@ = destination buffer
147  *              @const char *p@ = pointer to source string
148  *              @size_t sz@ = size of destination buffer
149  *
150  * Returns:     ---
151  *
152  * Use:         Writes a string into a buffer, being careful not to overflow
153  *              the buffer, to null terminate the result, and to prevent
154  *              nasty nonprintable characters ending up in the buffer.
155  */
156
157 extern void str_sanitize(char */*d*/, const char */*p*/, size_t /*sz*/);
158
159 /*----- That's all, folks -------------------------------------------------*/
160
161 #ifdef __cplusplus
162   }
163 #endif
164
165 #endif