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