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
  15 struct bytestring {
  16         const char *ptr;
  17         size_t len;
  18 };
  19
  20 /**
  21  * bytestring - construct a new bytestring
  22  * @p: pointer to the content of the bytestring
  23  * @l: length of the bytestring
  24  *
  25  * Builds a new bytestring starting at p, of length l.
  26  *
  27  * Example:
  28  *      char x[5] = "abcde";
  29  *      struct bytestring bs = bytestring(x, 5);
  30  *      assert(bs.len == 5);
  31  */
  32 static inline struct bytestring bytestring(const char *p, size_t l)
  33 {
  34         struct bytestring bs = {
  35                 .ptr = p,
  36                 .len = l,
  37         };
  38
  39         return bs;
  40 }
  41
  42 #define bytestring_NULL         bytestring(NULL, 0)
  43
  44 /**
  45  * BYTESTRING - construct a bytestring from a string literal
  46  * @s: string literal
  47  *
  48  * Builds a new bytestring containing the given literal string, not
  49  * including the terminating \0 (but including any internal \0s).
  50  *
  51  * Example:
  52  *      assert(BYTESTRING("abc\0def").len == 7);
  53  */
  54 #define BYTESTRING(s) (bytestring((s), ARRAY_SIZE(s) - 1))
  55
  56
  57 /**
  58  * bytestring_from_string - construct a bytestring from a NUL terminated string
  59  * @s: NUL-terminated string pointer
  60  *
  61  * Builds a new bytestring containing the given NUL-terminated string,
  62  * up to, but not including, the terminating \0.
  63  *
  64  * Example:
  65  *      assert(bytestring_from_string("abc\0def").len == 3);
  66  */
  67 static inline struct bytestring bytestring_from_string(const char *s)
  68 {
  69         if (!s)
  70                 return bytestring_NULL;
  71         return bytestring(s, strlen(s));
  72 }
  73
  74 /**
  75  * bytestring_eq - test if bytestrings have identical content
  76  * @a, @b: bytestrings
  77  *
  78  * Returns 1 if the given bytestrings have identical length and
  79  * content, 0 otherwise.
  80  */
  81 static inline bool bytestring_eq(struct bytestring a, struct bytestring b)
  82 {
  83         return (a.len == b.len)
  84                 && (memcmp(a.ptr, b.ptr, a.len) == 0);
  85 }
  86
  87 /**
  88  * bytestring_byte - get a byte from a bytestring
  89  * @s: bytestring
  90  * @n: index
  91  *
  92  * Return the @n-th byte from @s.  Aborts (via assert) if @n is out of
  93  * range for the length of @s.
  94  */
  95 static inline char bytestring_byte(struct bytestring s, size_t n)
  96 {
  97         assert(n < s.len);
  98         return s.ptr[n];
  99 }
 100
 101 /**
 102  * bytestring_slice - extract a substring from a bytestring
 103  * @s: bytestring
 104  * @start, @end: indexes
 105  *
 106  * Return a sub-bytestring of @s, starting at byte index @start, and
 107  * running to, but not including byte @end.  If @end is before start,
 108  * returns a zero-length bytestring.  If @start is out of range,
 109  * return a zero length bytestring at the end of @s.
 110  *
 111  * Note that this doesn't copy or allocate anything - the returned
 112  * bytestring occupies (some of) the same memory as the given
 113  * bytestring.
 114  */
 115 static inline struct bytestring bytestring_slice(struct bytestring s,
 116                                                  size_t start, size_t end)
 117 {
 118         if (start > s.len)
 119                 start = s.len;
 120         if (end > s.len)
 121                 end = s.len;
 122         if (end < start)
 123                 end = start;
 124
 125         return bytestring(s.ptr + start, end - start);
 126 }
 127
 128 /**
 129  * bytestring_starts - test if the start of one bytestring matches another
 130  * @s, @prefix: bytestrings
 131  *
 132  * Returns true if @prefix appears as a substring at the beginning of
 133  * @s, false otherwise.
 134  */
 135 static inline bool bytestring_starts(struct bytestring s,
 136                                      struct bytestring prefix)
 137 {
 138         return (s.len >= prefix.len) && (memcmp(s.ptr,
 139                                                 prefix.ptr, prefix.len) == 0);
 140 }
 141
 142 /**
 143  * bytestring_ends - test if the end of one bytestring matches another
 144  * @s, @suffix: bytestrings
 145  *
 146  * Returns true if @suffix appears as a substring at the end of @s,
 147  * false otherwise.
 148  */
 149 static inline bool bytestring_ends(struct bytestring s,
 150                                    struct bytestring suffix)
 151 {
 152         return (s.len >= suffix.len) && (memcmp(s.ptr + s.len - suffix.len,
 153                                                 suffix.ptr, suffix.len) == 0);
 154 }
 155
 156 /**
 157  * bytestring_index - locate character in bytestring
 158  * @haystack: a bytestring
 159  * @needle: a character or byte value
 160  *
 161  * Returns a pointer to the first occurrence of @needle within
 162  * @haystack, or NULL if @needle does not appear in @haystack.
 163  */
 164 static inline const char *bytestring_index(struct bytestring haystack,
 165                                            char needle)
 166 {
 167         return memchr(haystack.ptr, needle, haystack.len);
 168 }
 169
 170 /**
 171  * bytestring_rindex - locate character in bytestring
 172  * @haystack: a bytestring
 173  * @needle: a character or byte value
 174  *
 175  * Returns a pointer to the last occurrence of @needle within
 176  * @haystack, or NULL if @needle does not appear in @haystack.
 177  */
 178 static inline const char *bytestring_rindex(struct bytestring haystack,
 179                                            char needle)
 180 {
 181         return memrchr(haystack.ptr, needle, haystack.len);
 182 }
 183
 184 /*
 185  * bytestring_bytestring - search for a bytestring in another bytestring
 186  * @haystack, @needle: bytestrings
 187  *
 188  * Returns a bytestring corresponding to the first occurrence of
 189  * @needle in @haystack, or bytestring_NULL if @needle is not found
 190  * within @haystack.
 191  */
 192 static inline struct bytestring bytestring_bytestring(struct bytestring haystack,
 193                                                       struct bytestring needle)
 194 {
 195         const char *p = memmem(haystack.ptr, haystack.len,
 196                                needle.ptr, needle.len);
 197         if (p)
 198                 return bytestring(p, needle.len);
 199         else
 200                 return bytestring_NULL;
 201 }
 202
 203 /**
 204  * bytestring_spn - search a bytestring for a set of bytes
 205  * @s: a bytestring
 206  * @accept: a bytestring containing a set of bytes to accept
 207  *
 208  * Returns the length, in bytes, of the initial segment of @s which
 209  * consists entirely of characters in @accept.
 210  */
 211 size_t bytestring_spn(struct bytestring s, struct bytestring accept);
 212
 213 /**
 214  * bytestring_cspn - search a bytestring for a set of bytes (complemented)
 215  * @s: a bytestring
 216  * @reject: a bytestring containing a set of bytes to reject
 217  *
 218  * Returns the length, in bytes, of the initial segment of @s which
 219  * consists entirely of characters not in @reject.
 220  */
 221 size_t bytestring_cspn(struct bytestring s, struct bytestring reject);
 222
 223 /**
 224  * bytestring_splitchr_first - split a bytestring on a single character delimiter
 225  * @whole: a bytestring
 226  * @delim: delimiter character
 227  *
 228  * Returns the first @delim delimited substring of @whole.
 229  */
 230 struct bytestring bytestring_splitchr_first(struct bytestring whole,
 231                                             char delim);
 232
 233 /**
 234  * bytestring_splitchr_next - split a bytestring on a single character delimiter
 235  * @whole: a bytestring
 236  * @delim: delimiter character
 237  * @prev: last substring
 238  *
 239  * Returns the next @delim delimited substring of @whole after @prev.
 240  */
 241 struct bytestring bytestring_splitchr_next(struct bytestring whole,
 242                                            char delim, struct bytestring prev);
 243
 244 #define bytestring_foreach_splitchr(_s, _w, _delim) \
 245         for ((_s) = bytestring_splitchr_first((_w), (_delim)); \
 246              (_s).ptr;                                         \
 247              (_s) = bytestring_splitchr_next((_w), (_delim), (_s)))
 248
 249 #endif /* CCAN_BYTESTRING_H_ */