chiark / gitweb /
url: Allow `;' to separate key/value pairs in URL-encoded strings.
[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_match@ --- *
114  *
115  * Arguments:   @const char *p@ = pointer to pattern string
116  *              @const char *s@ = string to compare with
117  *
118  * Returns:     Nonzero if the pattern matches the string.
119  *
120  * Use:         Does simple wildcard matching.  This is quite nasty and more
121  *              than a little slow.  Supports metacharacters `*', `?' and
122  *              '['.
123  */
124
125 extern int str_match(const char */*p*/, const char */*s*/);
126
127 /* --- @str_sanitize@ --- *
128  *
129  * Arguments:   @char *d@ = destination buffer
130  *              @const char *p@ = pointer to source string
131  *              @size_t sz@ = size of destination buffer
132  *
133  * Returns:     ---
134  *
135  * Use:         Writes a string into a buffer, being careful not to overflow
136  *              the buffer, to null terminate the result, and to prevent
137  *              nasty nonprintable characters ending up in the buffer.
138  */
139
140 extern void str_sanitize(char */*d*/, const char */*p*/, size_t /*sz*/);
141
142 /*----- That's all, folks -------------------------------------------------*/
143
144 #ifdef __cplusplus
145   }
146 #endif
147
148 #endif