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