| 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 */ |