git.ozlabs.org Git - ccan/blob - ccan/bytestring/bytestring.h

   1 /* Licensed under LGPLv2+ - see LICENSE file for details */
   2 #ifndef CCAN_BYTESTRING_H_
   3 #define CCAN_BYTESTRING_H_
   4
   5 #include "config.h"
   6
   7 #include <stdlib.h>
   8 #include <string.h>
   9 #include <stdbool.h>
  10 #include <assert.h>
  11
  12 #include <ccan/array_size/array_size.h>
  13 #include <ccan/mem/mem.h>
  14 #include <ccan/compiler/compiler.h>
  15
  16 struct bytestring {
  17         const char *ptr;
  18         size_t len;
  19 };
  20
  21 /**
  22  * bytestring - construct a new bytestring
  23  * @p: pointer to the content of the bytestring
  24  * @l: length of the bytestring
  25  *
  26  * Builds a new bytestring starting at p, of length l.
  27  *
  28  * Example:
  29  *      char x[5] = "abcde";
  30  *      struct bytestring bs = bytestring(x, 5);
  31  *      assert(bs.len == 5);
  32  */
  33 static inline CONST_FUNCTION struct bytestring
  34 bytestring(const char *p, size_t l)
  35 {
  36         struct bytestring bs = {
  37                 .ptr = p,
  38                 .len = l,
  39         };
  40
  41         return bs;
  42 }
  43
  44 #define bytestring_NULL         bytestring(NULL, 0)
  45
  46 /**
  47  * BYTESTRING - construct a bytestring from a string literal
  48  * @s: string literal
  49  *
  50  * Builds a new bytestring containing the given literal string, not
  51  * including the terminating \0 (but including any internal \0s).
  52  *
  53  * Example:
  54  *      assert(BYTESTRING("abc\0def").len == 7);
  55  */
  56 #define BYTESTRING(s) (bytestring((s), ARRAY_SIZE(s) - 1))
  57
  58 /**
  59  * BYTESTRING_INIT - bytestring initializer
  60  * @s: string literal
  61  *
  62  * Produces an initializer for a bytestring from a literal string.
  63  * The resulting bytestring will not include the terminating \0, but
  64  * will include any internal \0s.
  65  *
  66  * Example:
  67  *      static const struct bytestring CONSTANT = BYTESTRING_INIT("CONSTANT");
  68  */
  69 #define BYTESTRING_INIT(s) { .ptr = (s), .len = ARRAY_SIZE(s) - 1}
  70
  71 /**
  72  * bytestring_from_string - construct a bytestring from a NUL terminated string
  73  * @s: NUL-terminated string pointer
  74  *
  75  * Builds a new bytestring containing the given NUL-terminated string,
  76  * up to, but not including, the terminating \0.
  77  *
  78  * Example:
  79  *      assert(bytestring_from_string("abc\0def").len == 3);
  80  */
  81 static inline struct bytestring bytestring_from_string(const char *s)
  82 {
  83         if (!s)
  84                 return bytestring_NULL;
  85         return bytestring(s, strlen(s));
  86 }
  87
  88 /**
  89  * bytestring_eq - test if bytestrings have identical content
  90  * @a, @b: bytestrings
  91  *
  92  * Returns 1 if the given bytestrings have identical length and
  93  * content, 0 otherwise.
  94  */
  95 static inline bool bytestring_eq(struct bytestring a, struct bytestring b)
  96 {
  97         return memeq(a.ptr, a.len, b.ptr, b.len);
  98 }
  99
 100 /**
 101  * bytestring_byte - get a byte from a bytestring
 102  * @s: bytestring
 103  * @n: index
 104  *
 105  * Return the @n-th byte from @s.  Aborts (via assert) if @n is out of
 106  * range for the length of @s.
 107  */
 108 static inline char bytestring_byte(struct bytestring s, size_t n)
 109 {
 110         assert(n < s.len);
 111         return s.ptr[n];
 112 }
 113
 114 /**
 115  * bytestring_slice - extract a substring from a bytestring
 116  * @s: bytestring
 117  * @start, @end: indexes
 118  *
 119  * Return a sub-bytestring of @s, starting at byte index @start, and
 120  * running to, but not including byte @end.  If @end is before start,
 121  * returns a zero-length bytestring.  If @start is out of range,
 122  * return a zero length bytestring at the end of @s.
 123  *
 124  * Note that this doesn't copy or allocate anything - the returned
 125  * bytestring occupies (some of) the same memory as the given
 126  * bytestring.
 127  */
 128 static inline struct bytestring bytestring_slice(struct bytestring s,
 129                                                  size_t start, size_t end)
 130 {
 131         if (start > s.len)
 132                 start = s.len;
 133         if (end > s.len)
 134                 end = s.len;
 135         if (end < start)
 136                 end = start;
 137
 138         return bytestring(s.ptr + start, end - start);
 139 }
 140
 141 /**
 142  * bytestring_starts - test if the start of one bytestring matches another
 143  * @s, @prefix: bytestrings
 144  *
 145  * Returns true if @prefix appears as a substring at the beginning of
 146  * @s, false otherwise.
 147  */
 148 static inline bool bytestring_starts(struct bytestring s,
 149                                      struct bytestring prefix)
 150 {
 151         return memstarts(s.ptr, s.len, prefix.ptr, prefix.len);
 152 }
 153
 154 /**
 155  * bytestring_ends - test if the end of one bytestring matches another
 156  * @s, @suffix: bytestrings
 157  *
 158  * Returns true if @suffix appears as a substring at the end of @s,
 159  * false otherwise.
 160  */
 161 static inline bool bytestring_ends(struct bytestring s,
 162                                    struct bytestring suffix)
 163 {
 164         return memends(s.ptr, s.len, suffix.ptr, suffix.len);
 165 }
 166
 167 /**
 168  * bytestring_index - locate character in bytestring
 169  * @haystack: a bytestring
 170  * @needle: a character or byte value
 171  *
 172  * Returns a pointer to the first occurrence of @needle within
 173  * @haystack, or NULL if @needle does not appear in @haystack.
 174  */
 175 static inline const char *bytestring_index(struct bytestring haystack,
 176                                            char needle)
 177 {
 178         return memchr(haystack.ptr, needle, haystack.len);
 179 }
 180
 181 /**
 182  * bytestring_rindex - locate character in bytestring
 183  * @haystack: a bytestring
 184  * @needle: a character or byte value
 185  *
 186  * Returns a pointer to the last occurrence of @needle within
 187  * @haystack, or NULL if @needle does not appear in @haystack.
 188  */
 189 static inline const char *bytestring_rindex(struct bytestring haystack,
 190                                            char needle)
 191 {
 192         return memrchr(haystack.ptr, needle, haystack.len);
 193 }
 194
 195 /*
 196  * bytestring_bytestring - search for a bytestring in another bytestring
 197  * @haystack, @needle: bytestrings
 198  *
 199  * Returns a bytestring corresponding to the first occurrence of
 200  * @needle in @haystack, or bytestring_NULL if @needle is not found
 201  * within @haystack.
 202  */
 203 static inline struct bytestring bytestring_bytestring(struct bytestring haystack,
 204                                                       struct bytestring needle)
 205 {
 206         const char *p = memmem(haystack.ptr, haystack.len,
 207                                needle.ptr, needle.len);
 208         if (p)
 209                 return bytestring(p, needle.len);
 210         else
 211                 return bytestring_NULL;
 212 }
 213
 214 /**
 215  * bytestring_spn - search a bytestring for a set of bytes
 216  * @s: a bytestring
 217  * @accept: a bytestring containing a set of bytes to accept
 218  *
 219  * Returns the length, in bytes, of the initial segment of @s which
 220  * consists entirely of characters in @accept.
 221  */
 222 size_t bytestring_spn(struct bytestring s, struct bytestring accept);
 223
 224 /**
 225  * bytestring_cspn - search a bytestring for a set of bytes (complemented)
 226  * @s: a bytestring
 227  * @reject: a bytestring containing a set of bytes to reject
 228  *
 229  * Returns the length, in bytes, of the initial segment of @s which
 230  * consists entirely of characters not in @reject.
 231  */
 232 size_t bytestring_cspn(struct bytestring s, struct bytestring reject);
 233
 234 /**
 235  * bytestring_splitchr_first - split a bytestring on a single character delimiter
 236  * @whole: a bytestring
 237  * @delim: delimiter character
 238  *
 239  * Returns the first @delim delimited substring of @whole.
 240  */
 241 struct bytestring bytestring_splitchr_first(struct bytestring whole,
 242                                             char delim);
 243
 244 /**
 245  * bytestring_splitchr_next - split a bytestring on a single character delimiter
 246  * @whole: a bytestring
 247  * @delim: delimiter character
 248  * @prev: last substring
 249  *
 250  * Returns the next @delim delimited substring of @whole after @prev.
 251  */
 252 struct bytestring bytestring_splitchr_next(struct bytestring whole,
 253                                            char delim, struct bytestring prev);
 254
 255 #define bytestring_foreach_splitchr(_s, _w, _delim) \
 256         for ((_s) = bytestring_splitchr_first((_w), (_delim)); \
 257              (_s).ptr;                                         \
 258              (_s) = bytestring_splitchr_next((_w), (_delim), (_s)))
 259
 260 /**
 261  * bytestring_splitchrs_first - split a bytestring on a set of delimiter
 262  *                              characters
 263  * @whole: a bytestring
 264  * @delim: delimiter characters
 265  *
 266  * Returns the first substring of @whole delimited by any character in
 267  * @delim.
 268  */
 269 struct bytestring bytestring_splitchrs_first(struct bytestring whole,
 270                                              struct bytestring delim);
 271
 272 /**
 273  * bytestring_splitchr_next - split a bytestring on a set of delimiter
 274  *                            characters
 275  * @whole: a bytestring
 276  * @delim: delimiter character
 277  * @prev: last substring
 278  *
 279  * Returns the next @delim delimited substring of @whole after @prev.
 280  */
 281 struct bytestring bytestring_splitchrs_next(struct bytestring whole,
 282                                             struct bytestring delim,
 283                                             struct bytestring prev);
 284
 285 #define bytestring_foreach_splitchrs(_s, _w, _delim) \
 286         for ((_s) = bytestring_splitchrs_first((_w), (_delim)); \
 287              (_s).ptr;                                         \
 288              (_s) = bytestring_splitchrs_next((_w), (_delim), (_s)))
 289
 290 /**
 291  * bytestring_splitstr_first - split a bytestring on a delimiter string
 292  * @whole: a bytestring
 293  * @delim: delimiter substring
 294  *
 295  * Returns the first substring of @whole delimited by the substring in
 296  * @delim.
 297  */
 298 struct bytestring bytestring_splitstr_first(struct bytestring whole,
 299                                              struct bytestring delim);
 300
 301 /**
 302  * bytestring_splitstr_next - split a bytestring on a delimiter string
 303  * @whole: a bytestring
 304  * @delim: delimiter string
 305  * @prev: last substring
 306  *
 307  * Returns the next @delim delimited substring of @whole after @prev.
 308  */
 309 struct bytestring bytestring_splitstr_next(struct bytestring whole,
 310                                            struct bytestring delim,
 311                                            struct bytestring prev);
 312
 313 #define bytestring_foreach_splitstr(_s, _w, _delim) \
 314         for ((_s) = bytestring_splitstr_first((_w), (_delim)); \
 315              (_s).ptr;                                         \
 316              (_s) = bytestring_splitstr_next((_w), (_delim), (_s)))
 317
 318 #endif /* CCAN_BYTESTRING_H_ */