chiark / gitweb /
~mdw / mLib / blame_incremental
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (non-incremental) | history | HEAD
url: Allow `;' to separate key/value pairs in URL-encoded strings.
[mLib] / str.h
... / ...
CommitLineData
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
58extern 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
81extern 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
95extern 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
110extern 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
125extern 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
140extern 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
mLib utilities library