chiark / gitweb /
Add global unihash table; use universal hashing instead of CRC.
[mLib] / str.h
1 /* -*-c-*-
2  *
3  * $Id: str.h,v 1.4 2000/10/08 09:43:34 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 /*----- Revision history --------------------------------------------------* 
31  *
32  * $Log: str.h,v $
33  * Revision 1.4  2000/10/08 09:43:34  mdw
34  * New quoted string handling and simple pattern matching.
35  *
36  * Revision 1.3  1999/12/10 23:42:04  mdw
37  * Change header file guard names.
38  *
39  * Revision 1.2  1999/05/26 20:52:57  mdw
40  * Add new `rest' argument for `str_split'.
41  *
42  * Revision 1.1  1999/05/17 20:37:01  mdw
43  * Some trivial string hacks.
44  *
45  */
46
47 #ifndef MLIB_STR_H
48 #define MLIB_STR_H
49
50 #ifdef __cplusplus
51   extern "C" {
52 #endif
53
54 /*----- Header files ------------------------------------------------------*/
55
56 #include <stddef.h>
57
58 /*----- Functions provided ------------------------------------------------*/
59
60 /* --- @str_qword@ --- *
61  *
62  * Arguments:   @char **pp@ = address of pointer into string
63  *              @unsigned f@ = various flags
64  *
65  * Returns:     Pointer to the next space-separated possibly-quoted word from
66  *              the string, or null.
67  *
68  * Use:         Fetches the next word from a string.  If the flag
69  *              @STRF_QUOTE@ is set, the `\' character acts as an escape, and
70  *              single and double quotes protect whitespace.
71  */
72
73 #define STRF_QUOTE 1u
74
75 extern char *str_qword(char **/*pp*/, unsigned /*f*/);
76
77 /* --- @str_qsplit@ --- *
78  *
79  * Arguments:   @char *p@ = pointer to string
80  *              @char *v[]@ = pointer to array to fill in
81  *              @size_t c@ = count of strings to fill in
82  *              @char **rest@ = where to store the remainder of the string
83  *              @unsigned f@ = flags for @str_qword@
84  *
85  * Returns:     Number of strings filled in.
86  *
87  * Use:         Fills an array with pointers to the individual words of a
88  *              string.  The string is modified in place to contain zero
89  *              bytes at the word boundaries, and the words have leading
90  *              and trailing space stripped off.  No more than @c@ words
91  *              are read; the actual number is returned as the value of the
92  *              function.  Unused slots in the array are populated with
93  *              null bytes.  If there's any string left, the address of the
94  *              remainder is stored in @rest@ (if it's non-null); otherwise
95  *              @rest@ is set to a null pointer.
96  */
97
98 extern size_t str_qsplit(char */*p*/, char */*v*/[], size_t /*c*/,
99                          char **/*rest*/, unsigned /*f*/);
100
101 /* --- @str_getword@ --- *
102  *
103  * Arguments:   @char **pp@ = address of pointer into string
104  *
105  * Returns:     Pointer to the next space-separated word from the string,
106  *              or null.
107  *
108  * Use:         Parses off space-separated words from a string.  This is a
109  *              compatibility veneer over @str_qword@.
110  */
111
112 extern char *str_getword(char **/*pp*/);
113
114 /* --- @str_split@ --- *
115  *
116  * Arguments:   @char *p@ = pointer to string
117  *              @char *v[]@ = pointer to array to fill in
118  *              @size_t c@ = count of strings to fill in
119  *              @char **rest@ = where to store the remainder of the string
120  *
121  * Returns:     Number of strings filled in.
122  *
123  * Use:         Fills an array with pointers to the individual words of a
124  *              string.  This is a compatibility veneer over @str_qsplit@.
125  */
126
127 extern size_t str_split(char */*p*/, char */*v*/[],
128                         size_t /*c*/, char **/*rest*/);
129
130 /* --- @str_match@ --- *
131  *
132  * Arguments:   @const char *p@ = pointer to pattern string
133  *              @const char *s@ = string to compare with
134  *
135  * Returns:     Nonzero if the pattern matches the string.
136  *
137  * Use:         Does simple wildcard matching.  This is quite nasty and more
138  *              than a little slow.  Supports metacharacters `*', `?' and
139  *              '['.
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