Debian Codegraph @

deps/libneon/src/ne_string.h

raw
1 /*
2 String utility functions
3 Copyright (C) 1999-2009, Joe Orton <[email protected]>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public
16 License along with this library; if not, write to the Free
17 Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
18 MA 02111-1307, USA
19
20 */
21
22 #ifndef NE_STRING_H
23 #define NE_STRING_H
24
25 #include "ne_defs.h"
26 #include "ne_alloc.h"
27
28 #include <stdarg.h>
29
30 NE_BEGIN_DECLS
31
32 /* ne_token and ne_qtoken return the next token in *str before either
33 * the next separator character 'sep' or the NUL terminator.
34 * ne_qtoken skips over any parts quoted using a pair of any one of
35 * the characters given in 'quotes'. After returning, *str will point
36 * to the next character after the separator, or NULL if no separator
37 * character was found.
38 *
39 * ne_qtoken will return NULL if unterminated quotes are found. */
40 char *ne_token(char **str, char sep);
41 char *ne_qtoken(char **str, char sep, const char *quotes);
42
43 /* Return portion of 'str' with any characters in 'whitespace' shaved
44 * off the beginning and end. Modifies str in-place. */
45 char *ne_shave(char *str, const char *whitespace);
46
47 /* Cleanse 'str' of non-printable (e.g. control) characters. 'str' is
48 * modified in-place, and returned. */
49 char *ne_strclean(char *str);
50
51 /* Encode 'len' bytes of 'text' to base64. Returns malloc-allocated
52 * NUL-terminated buffer which the caller must free(). */
53 char *ne_base64(const unsigned char *text, size_t len);
54
55 /* Decode NUL-terminated base64-encoded string 'data', placing
56 * malloc-allocated raw decoder output in '*out'. Returns length, or
57 * zero on decode error (in which case the content of *out is
58 * undefined). */
59 size_t ne_unbase64(const char *data, unsigned char **out);
60
61 /* Dynamically-allocated string buffer. A string buffer which grows
62 * dynamically . (Strings are zero-terminated still). A
63 * string buffer ne_buffer which grows dynamically with the string. */
64 typedef struct {
65 char *data; /* contents: NUL-terminated string */
66 size_t used; /* strlen(data) + 1 */
67 size_t length; /* number of bytes allocated */
68 } ne_buffer;
69
70 /* Create a new string buffer object. */
71 ne_buffer *ne_buffer_create(void);
72
73 /* Create a new string buffer object with at least 'size' bytes of
74 * allocated space. */
75 ne_buffer *ne_buffer_ncreate(size_t size);
76
77 /* Returns size of data in buffer, equiv to strlen(ne_buffer_data(buf)) */
78 #define ne_buffer_size(buf) ((buf)->used - 1)
79
80 /* Concatenate all given strings onto the end of the buffer. The
81 * strings must all be NUL-terminated, and MUST be followed by a NULL
82 * argument marking the end of the list. */
83 void ne_buffer_concat(ne_buffer *buf, ...)
84 ne_attribute_sentinel;
85
86 /* Append a NUL-terminated string 'str' to buf. */
87 void ne_buffer_zappend(ne_buffer *buf, const char *str);
88
89 /* Append 'len' bytes of 'data' to buf, where 'data' does not contain
90 * a NUL terminator. (A NUL terminator is appended to buf) */
91 void ne_buffer_append(ne_buffer *buf, const char *data, size_t len);
92
93 /* Append 'len' bytes of 'data' to buf. All non-ASCII bytes, and
94 * ASCII control characters, are escaped. (Note that this includes
95 * the NUL byte). */
96 void ne_buffer_qappend(ne_buffer *buf, const unsigned char *data, size_t len);
97
98 /* Print a string to the end of the buffer using printf-style format
99 * string 'format' and subsqeuent arguments. At most 'max' characters
100 * are appended; the number of characters appended (excluding the NUL
101 * terminator) is returned. Behaviour is undefined if 'max' is passed
102 * as zero. */
103 size_t ne_buffer_snprintf(ne_buffer *buf, size_t max,
104 const char *format, ...)
105 ne_attribute((format(printf, 3, 4)));
106
107 /* Append a literal, NUL-terminated constant string 'str' to buffer
108 * 'buf'. */
109 #define ne_buffer_czappend(buf, str) \
110 ne_buffer_append((buf), (str), sizeof((str)) - 1)
111
112 /* Clear the string buffer 'buf', making it equivalent to the empty
113 * string. */
114 void ne_buffer_clear(ne_buffer *buf);
115
116 /* Grow the allocated size of string buffer 'buf' to at least 'size'
117 * bytes. */
118 void ne_buffer_grow(ne_buffer *buf, size_t size);
119
120 /* Re-establish the 'used' invariant if the string buffer data field is
121 * altered directly. */
122 void ne_buffer_altered(ne_buffer *buf);
123
124 /* Destroy the string buffer object 'buf' without deallocating the
125 * data string. The data string must subsequently be freed using
126 * ne_free(). */
127 char *ne_buffer_finish(ne_buffer *buf);
128
129 /* Destroy a string buffer object. */
130 void ne_buffer_destroy(ne_buffer *buf);
131
132 /* Thread-safe strerror() wrapper; place system error for errno value
133 * 'errnum' in 'buffer', which is of length 'buflen'. Returns
134 * 'buffer'. */
135 char *ne_strerror(int errnum, char *buffer, size_t buflen);
136
137 /* ne_strnzcpy copies at most 'n'-1 bytes of 'src' to 'dest', and
138 * ensures that 'dest' is subsequently NUL-terminated. */
139 #define ne_strnzcpy(dest, src, n) do { size_t ne__nm1 = (n) - 1; \
140 strncpy(dest, src, ne__nm1); dest[ne__nm1] = '\0'; } while (0)
141
142 /* Return a malloc-allocated copy of 'data', of length 'len', with all
143 * non-ASCII bytes, and ASCII control characters escaped. (Note that
144 * the escaping includes the NUL byte). */
145 char *ne_strnqdup(const unsigned char *data, size_t len);
146
147 /* Return malloc-allocated concatenation of all NUL-terminated string
148 * arguments, up to a terminating NULL pointer. */
149 char *ne_concat(const char *str, ...)
150 ne_attribute_sentinel;
151
152 /* Wrapper for snprintf: always NUL-terminates returned buffer, and
153 * returns strlen(str). */
154 size_t ne_snprintf(char *str, size_t size, const char *fmt, ...)
155 ne_attribute((format(printf, 3, 4)));
156
157 /* Wrapper for vsnprintf. */
158 size_t ne_vsnprintf(char *str, size_t size, const char *fmt, va_list ap)
159 ne_attribute((format(printf, 3, 0)));
160
161 /* Implementations of strcasecmp and strncasecmp which behave as
162 * defined by the ANSI C strcasecmp() and strncasecmp() when in the
163 * POSIX locale; i.e. ignoring the process locale. */
164
165 /* Compares 's1' and 's2', ignoring differences in case. */
166 int ne_strcasecmp(const char *s1, const char *s2);
167 /* Compares up to 'n' characters of 's1' and 's2', ignoring
168 * differences in case. */
169 int ne_strncasecmp(const char *s1, const char *s2, size_t n);
170
171 /* Return lowercase 'c' as in POSIX locale; note difference from ANSI
172 * C semantics as both the argument and return value are unsigned
173 * char. */
174 #define ne_tolower(c) (ne_tolower_array()[(unsigned char)c])
175
176 const unsigned char *ne_tolower_array(void);
177
178 /* Convert an ASCII hexadecimal character in the ranges '0'..'9'
179 * 'a'..'f' 'A'..'F' to its numeric equivalent. */
180 #define NE_ASC2HEX(x) (((x) <= '9') ? ((x) - '0') : \
181 (ne_tolower((x)) + 10 - 'a'))
182
183 /* Convert an integer in the range 0..15 to the equivalent (lowercase)
184 * ASCII hexadecimal equivalent character, in the range '0..9,'a..f' */
185 #define NE_HEX2ASC(x) ((char) ((x) > 9 ? ((x) - 10 + 'a') : ((x) + '0')))
186
187 NE_END_DECLS
188
189 #endif /* NE_STRING_H */