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;
 207
 208         /* Allow needle.ptr == NULL, without memmem sanitizer complaining */
 209         if (needle.len == 0)
 210                 return bytestring(haystack.ptr, 0);
 211
 212         p = memmem(haystack.ptr, haystack.len, needle.ptr, needle.len);
 213         if (p)
 214                 return bytestring(p, needle.len);
 215         else
 216                 return bytestring_NULL;
 217 }
 218
 219 /**
 220  * bytestring_spn - search a bytestring for a set of bytes
 221  * @s: a bytestring
 222  * @accept: a bytestring containing a set of bytes to accept
 223  *
 224  * Returns the length, in bytes, of the initial segment of @s which
 225  * consists entirely of characters in @accept.
 226  */
 227 size_t bytestring_spn(struct bytestring s, struct bytestring accept);
 228
 229 /**
 230  * bytestring_cspn - search a bytestring for a set of bytes (complemented)
 231  * @s: a bytestring
 232  * @reject: a bytestring containing a set of bytes to reject
 233  *
 234  * Returns the length, in bytes, of the initial segment of @s which
 235  * consists entirely of characters not in @reject.
 236  */
 237 size_t bytestring_cspn(struct bytestring s, struct bytestring reject);
 238
 239 /**
 240  * bytestring_splitchr_first - split a bytestring on a single character delimiter
 241  * @whole: a bytestring
 242  * @delim: delimiter character
 243  *
 244  * Returns the first @delim delimited substring of @whole.
 245  */
 246 struct bytestring bytestring_splitchr_first(struct bytestring whole,
 247                                             char delim);
 248
 249 /**
 250  * bytestring_splitchr_next - split a bytestring on a single character delimiter
 251  * @whole: a bytestring
 252  * @delim: delimiter character
 253  * @prev: last substring
 254  *
 255  * Returns the next @delim delimited substring of @whole after @prev.
 256  */
 257 struct bytestring bytestring_splitchr_next(struct bytestring whole,
 258                                            char delim, struct bytestring prev);
 259
 260 #define bytestring_foreach_splitchr(_s, _w, _delim) \
 261         for ((_s) = bytestring_splitchr_first((_w), (_delim)); \
 262              (_s).ptr;                                         \
 263              (_s) = bytestring_splitchr_next((_w), (_delim), (_s)))
 264
 265 /**
 266  * bytestring_splitchrs_first - split a bytestring on a set of delimiter
 267  *                              characters
 268  * @whole: a bytestring
 269  * @delim: delimiter characters
 270  *
 271  * Returns the first substring of @whole delimited by any character in
 272  * @delim.
 273  */
 274 struct bytestring bytestring_splitchrs_first(struct bytestring whole,
 275                                              struct bytestring delim);
 276
 277 /**
 278  * bytestring_splitchr_next - split a bytestring on a set of delimiter
 279  *                            characters
 280  * @whole: a bytestring
 281  * @delim: delimiter character
 282  * @prev: last substring
 283  *
 284  * Returns the next @delim delimited substring of @whole after @prev.
 285  */
 286 struct bytestring bytestring_splitchrs_next(struct bytestring whole,
 287                                             struct bytestring delim,
 288                                             struct bytestring prev);
 289
 290 #define bytestring_foreach_splitchrs(_s, _w, _delim) \
 291         for ((_s) = bytestring_splitchrs_first((_w), (_delim)); \
 292              (_s).ptr;                                         \
 293              (_s) = bytestring_splitchrs_next((_w), (_delim), (_s)))
 294
 295 /**
 296  * bytestring_splitstr_first - split a bytestring on a delimiter string
 297  * @whole: a bytestring
 298  * @delim: delimiter substring
 299  *
 300  * Returns the first substring of @whole delimited by the substring in
 301  * @delim.
 302  */
 303 struct bytestring bytestring_splitstr_first(struct bytestring whole,
 304                                              struct bytestring delim);
 305
 306 /**
 307  * bytestring_splitstr_next - split a bytestring on a delimiter string
 308  * @whole: a bytestring
 309  * @delim: delimiter string
 310  * @prev: last substring
 311  *
 312  * Returns the next @delim delimited substring of @whole after @prev.
 313  */
 314 struct bytestring bytestring_splitstr_next(struct bytestring whole,
 315                                            struct bytestring delim,
 316                                            struct bytestring prev);
 317
 318 #define bytestring_foreach_splitstr(_s, _w, _delim) \
 319         for ((_s) = bytestring_splitstr_first((_w), (_delim)); \
 320              (_s).ptr;                                         \
 321              (_s) = bytestring_splitstr_next((_w), (_delim), (_s)))
 322
 323 #endif /* CCAN_BYTESTRING_H_ */