include/neon/ne_string.h

   1 /*
   2    String utility functions
   3    Copyright (C) 1999-2005, Joe Orton <joe@manyfish.co.uk>
   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 BEGIN_NEON_DECLS
  31
  32 /* ne_token and ne_qtoken return the next token in *str between *str
  33  * and separator character 'sep' or the NUL terminator. ne_qtoken
  34  * skips over any parts quoted using a pair of any one of the
  35  * characters given in 'quotes'.  After returning, *str will point to
  36  * the next character after the separator, or NULL if no more
  37  * separator characters were found.
  38  *
  39  * ne_qtoken may 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. */
  45 char *ne_shave(char *str, const char *whitespace);
  46
  47 /* Cleanse 'str' of non-printable characters.  'str' is modified
  48  * in-place, and returned. */
  49 char *ne_strclean(char *str);
  50
  51 /* A base64 encoder: converts 'len' bytes of 'text' to base64.
  52  * Returns malloc-allocated buffer; caller must free(). */
  53 char *ne_base64(const unsigned char *text, size_t len);
  54
  55 /* Base64 decoder; decodes NUL-terminated base64-encoded string
  56  * 'data', places malloc-allocated raw data in '*out', returns length,
  57  * or zero on decode error (in which case *out is undefined). */
  58 size_t ne_unbase64(const char *data, unsigned char **out);
  59
  60 /* String buffer handling. (Strings are zero-terminated still).  A
  61  * string buffer ne_buffer * which grows dynamically with the
  62  * string. */
  63
  64 typedef struct {
  65     char *data; /* contents: null-terminated string. */
  66     size_t used; /* used bytes in buffer */
  67     size_t length; /* length of buffer */
  68 } ne_buffer;
  69
  70 /* Returns size of data in buffer, equiv to strlen(ne_buffer_data(buf)) */
  71 #define ne_buffer_size(buf) ((buf)->used - 1)
  72
  73 /* Concatenate all given strings onto the end of the buffer.  The
  74  * strings must all be NUL-terminated, and MUST be followed by a NULL
  75  * argument marking the end of the list.  */
  76 void ne_buffer_concat(ne_buffer *buf, ...);
  77
  78 /* Create a new ne_buffer. */
  79 ne_buffer *ne_buffer_create(void);
  80
  81 /* Create a new ne_buffer of given minimum size. */
  82 ne_buffer *ne_buffer_ncreate(size_t size);
  83
  84 /* Destroys (deallocates) a buffer */
  85 void ne_buffer_destroy(ne_buffer *buf);
  86
  87 /* Append a NUL-terminated string 'str' to buf. */
  88 void ne_buffer_zappend(ne_buffer *buf, const char *str);
  89
  90 /* Append 'len' bytes of 'data' to buf.  'data' does not need to be
  91  * NUL-terminated. The resultant string will have a NUL-terminator,
  92  * either way.  */
  93 void ne_buffer_append(ne_buffer *buf, const char *data, size_t len);
  94
  95 /* Append a literal constant string 'str' to buffer 'buf'. */
  96 #define ne_buffer_czappend(buf, str) \
  97 ne_buffer_append((buf), (str), sizeof((str)) - 1)
  98
  99 /* Empties the contents of buf; makes the buffer zero-length. */
 100 void ne_buffer_clear(ne_buffer *buf);
 101
 102 /* Grows the ne_buffer to a minimum size. */
 103 void ne_buffer_grow(ne_buffer *buf, size_t size);
 104
 105 void ne_buffer_altered(ne_buffer *buf);
 106
 107 /* Destroys a buffer, WITHOUT freeing the data, and returns the
 108  * data. */
 109 char *ne_buffer_finish(ne_buffer *buf);
 110
 111 /* Thread-safe strerror() wrapper; place system error for errno value
 112  * 'errnum' in 'buffer', which is of length 'buflen'.  Returns
 113  * 'buffer'. */
 114 char *ne_strerror(int errnum, char *buffer, size_t buflen);
 115
 116 /* ne_strnzcpy copies at most 'n'-1 bytes of 'src' to 'dest', and
 117  * ensures that 'dest' is subsequently NUL-terminated. */
 118 #define ne_strnzcpy(dest, src, n) do { \
 119 strncpy(dest, src, n-1); dest[n-1] = '\0'; } while (0)
 120
 121 /* Return malloc-allocated concatenation of all NUL-terminated string
 122  * arguments, up to a terminating NULL. */
 123 char *ne_concat(const char *str, ...);
 124
 125 #define NE_ASC2HEX(x) (((x) <= '9') ? ((x) - '0') : (tolower((x)) + 10 - 'a'))
 126 #define NE_HEX2ASC(x) ((char) ((x) > 9 ? ((x) - 10 + 'a') : ((x) + '0')))
 127
 128 /* Wrapper for snprintf: always NUL-terminates returned buffer, and
 129  * returns strlen(str). */
 130 size_t ne_snprintf(char *str, size_t size, const char *fmt, ...)
 131     ne_attribute((format(printf, 3, 4)));
 132
 133 /* Wrapper for vsnprintf. */
 134 size_t ne_vsnprintf(char *str, size_t size, const char *fmt, va_list ap)
 135     ne_attribute((format(printf, 3, 0)));
 136
 137 END_NEON_DECLS
 138
 139 #endif /* NE_STRING_H */