1 /* PSPP - a program for statistical analysis.
2 Copyright (C) 1997-9, 2000, 2006, 2009, 2010, 2011 Free Software Foundation, Inc.
4 This program is free software: you can redistribute it and/or modify
5 it under the terms of the GNU General Public License as published by
6 the Free Software Foundation, either version 3 of the License, or
7 (at your option) any later version.
9 This program is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 GNU General Public License for more details.
14 You should have received a copy of the GNU General Public License
15 along with this program. If not, see <http://www.gnu.org/licenses/>. */
27 #include "libpspp/cast.h"
28 #include "libpspp/message.h"
29 #include "libpspp/pool.h"
31 #include "gl/relocatable.h"
32 #include "gl/minmax.h"
33 #include "gl/xalloc.h"
34 #include "gl/xmemdup0.h"
37 /* Reverses the order of NBYTES bytes at address P, thus converting
38 between little- and big-endian byte orders. */
40 buf_reverse (char *p, size_t nbytes)
42 char *h = p, *t = &h[nbytes - 1];
54 /* Compares the SIZE bytes in A to those in B, disregarding case,
55 and returns a strcmp()-type result. */
57 buf_compare_case (const char *a_, const char *b_, size_t size)
59 const unsigned char *a = (unsigned char *) a_;
60 const unsigned char *b = (unsigned char *) b_;
64 unsigned char ac = toupper (*a++);
65 unsigned char bc = toupper (*b++);
68 return ac > bc ? 1 : -1;
74 /* Compares A of length A_LEN to B of length B_LEN. The shorter
75 string is considered to be padded with spaces to the length of
78 buf_compare_rpad (const char *a, size_t a_len, const char *b, size_t b_len)
83 min_len = a_len < b_len ? a_len : b_len;
84 result = memcmp (a, b, min_len);
93 for (idx = min_len; idx < b_len; idx++)
95 return ' ' > b[idx] ? 1 : -1;
99 for (idx = min_len; idx < a_len; idx++)
101 return a[idx] > ' ' ? 1 : -1;
107 /* Compares strin A to string B. The shorter string is
108 considered to be padded with spaces to the length of the
111 str_compare_rpad (const char *a, const char *b)
113 return buf_compare_rpad (a, strlen (a), b, strlen (b));
116 /* Copies string SRC to buffer DST, of size DST_SIZE bytes.
117 DST is truncated to DST_SIZE bytes or padded on the right with
118 copies of PAD as needed. */
120 buf_copy_str_rpad (char *dst, size_t dst_size, const char *src, char pad)
122 size_t src_len = strlen (src);
123 if (src_len >= dst_size)
124 memcpy (dst, src, dst_size);
127 memcpy (dst, src, src_len);
128 memset (&dst[src_len], pad, dst_size - src_len);
132 /* Copies string SRC to buffer DST, of size DST_SIZE bytes.
133 DST is truncated to DST_SIZE bytes or padded on the left with
134 copies of PAD as needed. */
136 buf_copy_str_lpad (char *dst, size_t dst_size, const char *src, char pad)
138 size_t src_len = strlen (src);
139 if (src_len >= dst_size)
140 memcpy (dst, src, dst_size);
143 size_t pad_cnt = dst_size - src_len;
144 memset (&dst[0], pad, pad_cnt);
145 memcpy (dst + pad_cnt, src, src_len);
149 /* Copies buffer SRC, of SRC_SIZE bytes, to DST, of DST_SIZE bytes.
150 DST is truncated to DST_SIZE bytes or padded on the left with
151 copies of PAD as needed. */
153 buf_copy_lpad (char *dst, size_t dst_size,
154 const char *src, size_t src_size,
157 if (src_size >= dst_size)
158 memmove (dst, src, dst_size);
161 memset (dst, pad, dst_size - src_size);
162 memmove (&dst[dst_size - src_size], src, src_size);
166 /* Copies buffer SRC, of SRC_SIZE bytes, to DST, of DST_SIZE bytes.
167 DST is truncated to DST_SIZE bytes or padded on the right with
168 copies of PAD as needed. */
170 buf_copy_rpad (char *dst, size_t dst_size,
171 const char *src, size_t src_size,
174 if (src_size >= dst_size)
175 memmove (dst, src, dst_size);
178 memmove (dst, src, src_size);
179 memset (&dst[src_size], pad, dst_size - src_size);
183 /* Copies string SRC to string DST, which is in a buffer DST_SIZE
185 Truncates DST to DST_SIZE - 1 bytes or right-pads with
186 spaces to DST_SIZE - 1 bytes if necessary. */
188 str_copy_rpad (char *dst, size_t dst_size, const char *src)
192 size_t src_len = strlen (src);
193 if (src_len < dst_size - 1)
195 memcpy (dst, src, src_len);
196 memset (&dst[src_len], ' ', dst_size - 1 - src_len);
199 memcpy (dst, src, dst_size - 1);
200 dst[dst_size - 1] = 0;
204 /* Copies SRC to DST, which is in a buffer DST_SIZE bytes long.
205 Truncates DST to DST_SIZE - 1 bytes, if necessary. */
207 str_copy_trunc (char *dst, size_t dst_size, const char *src)
209 size_t src_len = strlen (src);
210 assert (dst_size > 0);
211 if (src_len + 1 < dst_size)
212 memcpy (dst, src, src_len + 1);
215 memcpy (dst, src, dst_size - 1);
216 dst[dst_size - 1] = '\0';
220 /* Copies buffer SRC, of SRC_LEN bytes,
221 to DST, which is in a buffer DST_SIZE bytes long.
222 Truncates DST to DST_SIZE - 1 bytes, if necessary. */
224 str_copy_buf_trunc (char *dst, size_t dst_size,
225 const char *src, size_t src_size)
228 assert (dst_size > 0);
230 dst_len = src_size < dst_size ? src_size : dst_size - 1;
231 memcpy (dst, src, dst_len);
235 /* Converts each byte in S to uppercase. */
237 str_uppercase (char *s)
239 for (; *s != '\0'; s++)
240 *s = toupper ((unsigned char) *s);
243 /* Converts each byte in S to lowercase. */
245 str_lowercase (char *s)
247 for (; *s != '\0'; s++)
248 *s = tolower ((unsigned char) *s);
251 /* Converts NUMBER into a string in 26-adic notation in BUFFER,
252 which has room for SIZE bytes. Returns true if successful,
253 false if NUMBER, plus a trailing null, is too large to fit in
256 26-adic notation is "spreadsheet column numbering": 1 = A, 2 =
257 B, 3 = C, ... 26 = Z, 27 = AA, 28 = AB, 29 = AC, ...
259 26-adic notation is the special case of a k-adic numeration
260 system (aka bijective base-k numeration) with k=26. In k-adic
261 numeration, the digits are {1, 2, 3, ..., k} (there is no
262 digit 0), and integer 0 is represented by the empty string.
263 For more information, see
264 http://en.wikipedia.org/wiki/Bijective_numeration. */
266 str_format_26adic (unsigned long int number, char buffer[], size_t size)
274 buffer[length++] = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"[number % 26];
280 buffer[length] = '\0';
282 buf_reverse (buffer, length);
286 /* Sets the SIZE bytes starting at BLOCK to C,
287 and returns the byte following BLOCK. */
289 mempset (void *block, int c, size_t size)
291 memset (block, c, size);
292 return (char *) block + size;
297 /* Returns a substring whose contents are the CNT bytes
298 starting at the (0-based) position START in SS. */
300 ss_substr (struct substring ss, size_t start, size_t cnt)
302 if (start < ss.length)
303 return ss_buffer (ss.string + start, MIN (cnt, ss.length - start));
305 return ss_buffer (ss.string + ss.length, 0);
308 /* Returns a substring whose contents are the first CNT
311 ss_head (struct substring ss, size_t cnt)
313 return ss_buffer (ss.string, MIN (cnt, ss.length));
316 /* Returns a substring whose contents are the last CNT bytes
319 ss_tail (struct substring ss, size_t cnt)
322 return ss_buffer (ss.string + (ss.length - cnt), cnt);
327 /* Makes a malloc()'d, null-terminated copy of the contents of OLD
328 and stores it in NEW. */
330 ss_alloc_substring (struct substring *new, struct substring old)
332 new->string = xmemdup0 (old.string, old.length);
333 new->length = old.length;
336 /* Allocates room for a CNT-byte string in NEW. */
338 ss_alloc_uninit (struct substring *new, size_t cnt)
340 new->string = xmalloc (cnt);
345 ss_realloc (struct substring *ss, size_t size)
347 ss->string = xrealloc (ss->string, size);
350 /* Makes a pool_alloc_unaligned()'d, null-terminated copy of the contents of
351 OLD in POOL, and stores it in NEW. */
353 ss_alloc_substring_pool (struct substring *new, struct substring old,
356 new->string = pool_alloc_unaligned (pool, old.length + 1);
357 new->length = old.length;
358 memcpy (new->string, old.string, old.length);
359 new->string[old.length] = '\0';
362 /* Allocates room for a CNT-byte string in NEW in POOL. */
364 ss_alloc_uninit_pool (struct substring *new, size_t cnt, struct pool *pool)
366 new->string = pool_alloc_unaligned (pool, cnt);
370 /* Frees the string that SS points to. */
372 ss_dealloc (struct substring *ss)
377 /* Truncates SS to at most CNT bytes in length. */
379 ss_truncate (struct substring *ss, size_t cnt)
381 if (ss->length > cnt)
385 /* Removes trailing bytes in TRIM_SET from SS.
386 Returns number of bytes removed. */
388 ss_rtrim (struct substring *ss, struct substring trim_set)
391 while (cnt < ss->length
392 && ss_find_byte (trim_set,
393 ss->string[ss->length - cnt - 1]) != SIZE_MAX)
399 /* Removes leading bytes in TRIM_SET from SS.
400 Returns number of bytes removed. */
402 ss_ltrim (struct substring *ss, struct substring trim_set)
404 size_t cnt = ss_span (*ss, trim_set);
405 ss_advance (ss, cnt);
409 /* Trims leading and trailing bytes in TRIM_SET from SS. */
411 ss_trim (struct substring *ss, struct substring trim_set)
413 ss_ltrim (ss, trim_set);
414 ss_rtrim (ss, trim_set);
417 /* If the last byte in SS is C, removes it and returns true.
418 Otherwise, returns false without changing the string. */
420 ss_chomp_byte (struct substring *ss, char c)
422 if (ss_last (*ss) == c)
431 /* If SS ends with SUFFIX, removes it and returns true.
432 Otherwise, returns false without changing the string. */
434 ss_chomp (struct substring *ss, struct substring suffix)
436 if (ss_ends_with (*ss, suffix))
438 ss->length -= suffix.length;
445 /* Divides SS into tokens separated by any of the DELIMITERS.
446 Each call replaces TOKEN by the next token in SS, or by an
447 empty string if no tokens remain. Returns true if a token was
448 obtained, false otherwise.
450 Before the first call, initialize *SAVE_IDX to 0. Do not
451 modify *SAVE_IDX between calls.
453 SS divides into exactly one more tokens than it contains
454 delimiters. That is, a delimiter at the start or end of SS or
455 a pair of adjacent delimiters yields an empty token, and the
456 empty string contains a single token. */
458 ss_separate (struct substring ss, struct substring delimiters,
459 size_t *save_idx, struct substring *token)
461 if (*save_idx <= ss_length (ss))
463 struct substring tmp = ss_substr (ss, *save_idx, SIZE_MAX);
464 size_t length = ss_cspan (tmp, delimiters);
465 *token = ss_head (tmp, length);
466 *save_idx += length + 1;
471 *token = ss_empty ();
476 /* Divides SS into tokens separated by any of the DELIMITERS,
477 merging adjacent delimiters so that the empty string is never
478 produced as a token. Each call replaces TOKEN by the next
479 token in SS, or by an empty string if no tokens remain, and
480 then skips past the first delimiter following the token.
481 Returns true if a token was obtained, false otherwise.
483 Before the first call, initialize *SAVE_IDX to 0. Do not
484 modify *SAVE_IDX between calls. */
486 ss_tokenize (struct substring ss, struct substring delimiters,
487 size_t *save_idx, struct substring *token)
489 ss_advance (&ss, *save_idx);
490 *save_idx += ss_ltrim (&ss, delimiters);
491 ss_get_bytes (&ss, ss_cspan (ss, delimiters), token);
492 *save_idx += ss_length (*token) + 1;
493 return ss_length (*token) > 0;
496 /* Removes the first CNT bytes from SS. */
498 ss_advance (struct substring *ss, size_t cnt)
500 if (cnt > ss->length)
506 /* If the first byte in SS is C, removes it and returns true.
507 Otherwise, returns false without changing the string. */
509 ss_match_byte (struct substring *ss, char c)
511 if (ss_first (*ss) == c)
521 /* If the first byte in SS is in MATCH, removes it and
522 returns the byte that was removed.
523 Otherwise, returns EOF without changing the string. */
525 ss_match_byte_in (struct substring *ss, struct substring match)
529 && memchr (match.string, ss->string[0], match.length) != NULL)
538 /* If SS begins with TARGET, removes it and returns true.
539 Otherwise, returns false without changing SS. */
541 ss_match_string (struct substring *ss, const struct substring target)
543 size_t length = ss_length (target);
544 if (ss_equals (ss_head (*ss, length), target))
546 ss_advance (ss, length);
553 /* Removes the first byte from SS and returns it.
554 If SS is empty, returns EOF without modifying SS. */
556 ss_get_byte (struct substring *ss)
558 int c = ss_first (*ss);
567 /* Stores the prefix of SS up to the first DELIMITER in OUT (if
568 any). Trims those same bytes from SS. DELIMITER is
569 removed from SS but not made part of OUT. Returns true if
570 DELIMITER was found (and removed), false otherwise. */
572 ss_get_until (struct substring *ss, char delimiter, struct substring *out)
574 ss_get_bytes (ss, ss_cspan (*ss, ss_buffer (&delimiter, 1)), out);
575 return ss_match_byte (ss, delimiter);
578 /* Stores the first CNT bytes in SS in OUT (or fewer, if SS
579 is shorter than CNT bytes). Trims the same bytes
580 from the beginning of SS. Returns CNT. */
582 ss_get_bytes (struct substring *ss, size_t cnt, struct substring *out)
584 *out = ss_head (*ss, cnt);
585 ss_advance (ss, cnt);
589 /* Parses and removes an optionally signed decimal integer from
590 the beginning of SS. Returns 0 if an error occurred,
591 otherwise the number of bytes removed from SS. Stores
592 the integer's value into *VALUE. */
594 ss_get_long (struct substring *ss, long *value)
599 length = ss_span (*ss, ss_cstr ("+-"));
600 length += ss_span (ss_substr (*ss, length, SIZE_MAX), ss_cstr (CC_DIGITS));
601 if (length > 0 && length < sizeof tmp)
605 memcpy (tmp, ss_data (*ss), length);
608 *value = strtol (tmp, &tail, 10);
609 if (tail - tmp == length)
611 ss_advance (ss, length);
619 /* Returns true if SS is empty (has length 0 bytes),
622 ss_is_empty (struct substring ss)
624 return ss.length == 0;
627 /* Returns the number of bytes in SS. */
629 ss_length (struct substring ss)
634 /* Returns a pointer to the bytes in SS. */
636 ss_data (struct substring ss)
641 /* Returns a pointer just past the last byte in SS. */
643 ss_end (struct substring ss)
645 return ss.string + ss.length;
648 /* Returns the byte in position IDX in SS, as a value in the
649 range of unsigned char. Returns EOF if IDX is out of the
650 range of indexes for SS. */
652 ss_at (struct substring ss, size_t idx)
654 return idx < ss.length ? (unsigned char) ss.string[idx] : EOF;
657 /* Returns the first byte in SS as a value in the range of
658 unsigned char. Returns EOF if SS is the empty string. */
660 ss_first (struct substring ss)
662 return ss_at (ss, 0);
665 /* Returns the last byte in SS as a value in the range of
666 unsigned char. Returns EOF if SS is the empty string. */
668 ss_last (struct substring ss)
670 return ss.length > 0 ? (unsigned char) ss.string[ss.length - 1] : EOF;
673 /* Returns true if SS ends with SUFFIX, false otherwise. */
675 ss_ends_with (struct substring ss, struct substring suffix)
677 return (ss.length >= suffix.length
678 && !memcmp (&ss.string[ss.length - suffix.length], suffix.string,
682 /* Returns the number of contiguous bytes at the beginning
683 of SS that are in SKIP_SET. */
685 ss_span (struct substring ss, struct substring skip_set)
688 for (i = 0; i < ss.length; i++)
689 if (ss_find_byte (skip_set, ss.string[i]) == SIZE_MAX)
694 /* Returns the number of contiguous bytes at the beginning
695 of SS that are not in SKIP_SET. */
697 ss_cspan (struct substring ss, struct substring stop_set)
700 for (i = 0; i < ss.length; i++)
701 if (ss_find_byte (stop_set, ss.string[i]) != SIZE_MAX)
706 /* Returns the offset in SS of the first instance of C,
707 or SIZE_MAX if C does not occur in SS. */
709 ss_find_byte (struct substring ss, char c)
711 const char *p = memchr (ss.string, c, ss.length);
712 return p != NULL ? p - ss.string : SIZE_MAX;
715 /* Compares A and B and returns a strcmp()-type comparison
718 ss_compare (struct substring a, struct substring b)
720 int retval = memcmp (a.string, b.string, MIN (a.length, b.length));
722 retval = a.length < b.length ? -1 : a.length > b.length;
726 /* Compares A and B case-insensitively and returns a
727 strcmp()-type comparison result. */
729 ss_compare_case (struct substring a, struct substring b)
731 int retval = memcasecmp (a.string, b.string, MIN (a.length, b.length));
733 retval = a.length < b.length ? -1 : a.length > b.length;
737 /* Compares A and B and returns true if their contents are
738 identical, false otherwise. */
740 ss_equals (struct substring a, struct substring b)
742 return a.length == b.length && !memcmp (a.string, b.string, a.length);
745 /* Compares A and B and returns true if their contents are
746 identical except possibly for case differences, false
749 ss_equals_case (struct substring a, struct substring b)
751 return a.length == b.length && !memcasecmp (a.string, b.string, a.length);
754 /* Returns the position in SS that the byte at P occupies.
755 P must point within SS or one past its end. */
757 ss_pointer_to_position (struct substring ss, const char *p)
759 size_t pos = p - ss.string;
760 assert (pos <= ss.length);
764 /* Allocates and returns a null-terminated string that contains
767 ss_xstrdup (struct substring ss)
769 char *s = xmalloc (ss.length + 1);
770 memcpy (s, ss.string, ss.length);
776 /* Returns the character represented by the UTF-8 sequence at the start of S.
777 The return value is either a Unicode code point in the range 0 to 0x10ffff,
778 or UINT32_MAX if S is empty. */
780 ss_first_mb (struct substring s)
782 return ss_at_mb (s, 0);
785 /* Returns the number of bytes in the UTF-8 character at the beginning of S.
787 The return value is 0 if S is empty, otherwise between 1 and 4. */
789 ss_first_mblen (struct substring s)
791 return ss_at_mblen (s, 0);
794 /* Advances S past the UTF-8 character at its beginning. Returns the Unicode
795 code point that was skipped (in the range 0 to 0x10ffff), or UINT32_MAX if S
796 was not modified because it was initially empty. */
798 ss_get_mb (struct substring *s)
805 n = u8_mbtouc (&uc, CHAR_CAST (const uint8_t *, s->string), s->length);
814 /* Returns the character represented by the UTF-8 sequence starting OFS bytes
815 into S. The return value is either a Unicode code point in the range 0 to
816 0x10ffff, or UINT32_MAX if OFS is past the last byte in S.
818 (Returns 0xfffd if OFS points into the middle, not the beginning, of a UTF-8
821 ss_at_mb (struct substring s, size_t ofs)
826 u8_mbtouc (&uc, CHAR_CAST (const uint8_t *, s.string + ofs),
834 /* Returns the number of bytes represented by the UTF-8 sequence starting OFS
835 bytes into S. The return value is 0 if OFS is past the last byte in S,
836 otherwise between 1 and 4. */
838 ss_at_mblen (struct substring s, size_t ofs)
843 return u8_mbtouc (&uc, CHAR_CAST (const uint8_t *, s.string + ofs),
850 /* Initializes ST as an empty string. */
852 ds_init_empty (struct string *st)
854 st->ss = ss_empty ();
858 /* Initializes ST with initial contents S. */
860 ds_init_string (struct string *st, const struct string *s)
862 ds_init_substring (st, ds_ss (s));
865 /* Initializes ST with initial contents SS. */
867 ds_init_substring (struct string *st, struct substring ss)
869 st->capacity = MAX (8, ss.length * 2);
870 st->ss.string = xmalloc (st->capacity + 1);
871 memcpy (st->ss.string, ss.string, ss.length);
872 st->ss.length = ss.length;
875 /* Initializes ST with initial contents S. */
877 ds_init_cstr (struct string *st, const char *s)
879 ds_init_substring (st, ss_cstr (s));
884 ds_destroy (struct string *st)
888 ss_dealloc (&st->ss);
889 st->ss.string = NULL;
895 /* Swaps the contents of strings A and B. */
897 ds_swap (struct string *a, struct string *b)
899 struct string tmp = *a;
904 /* Helper function for ds_register_pool. */
906 free_string (void *st_)
908 struct string *st = st_;
912 /* Arranges for ST to be destroyed automatically as part of
915 ds_register_pool (struct string *st, struct pool *pool)
917 pool_register (pool, free_string, st);
920 /* Cancels the arrangement for ST to be destroyed automatically
923 ds_unregister_pool (struct string *st, struct pool *pool)
925 pool_unregister (pool, st);
928 /* Copies SRC into DST.
929 DST and SRC may be the same string. */
931 ds_assign_string (struct string *dst, const struct string *src)
933 ds_assign_substring (dst, ds_ss (src));
936 /* Replaces DST by SS.
937 SS may be a substring of DST. */
939 ds_assign_substring (struct string *dst, struct substring ss)
941 dst->ss.length = ss.length;
942 ds_extend (dst, ss.length);
943 memmove (dst->ss.string, ss.string, ss.length);
946 /* Replaces DST by null-terminated string SRC. SRC may overlap
949 ds_assign_cstr (struct string *dst, const char *src)
951 ds_assign_substring (dst, ss_cstr (src));
954 /* Truncates ST to zero length. */
956 ds_clear (struct string *st)
961 /* Returns a substring that contains ST. */
963 ds_ss (const struct string *st)
968 /* Returns a substring that contains CNT bytes from ST
969 starting at position START.
971 If START is greater than or equal to the length of ST, then
972 the substring will be the empty string. If START + CNT
973 exceeds the length of ST, then the substring will only be
974 ds_length(ST) - START bytes long. */
976 ds_substr (const struct string *st, size_t start, size_t cnt)
978 return ss_substr (ds_ss (st), start, cnt);
981 /* Returns a substring that contains the first CNT bytes in
982 ST. If CNT exceeds the length of ST, then the substring will
983 contain all of ST. */
985 ds_head (const struct string *st, size_t cnt)
987 return ss_head (ds_ss (st), cnt);
990 /* Returns a substring that contains the last CNT bytes in
991 ST. If CNT exceeds the length of ST, then the substring will
992 contain all of ST. */
994 ds_tail (const struct string *st, size_t cnt)
996 return ss_tail (ds_ss (st), cnt);
999 /* Ensures that ST can hold at least MIN_CAPACITY bytes plus a null
1002 ds_extend (struct string *st, size_t min_capacity)
1004 if (min_capacity > st->capacity)
1007 if (st->capacity < min_capacity)
1008 st->capacity = 2 * min_capacity;
1010 st->ss.string = xrealloc (st->ss.string, st->capacity + 1);
1014 /* Shrink ST to the minimum capacity need to contain its content. */
1016 ds_shrink (struct string *st)
1018 if (st->capacity != st->ss.length)
1020 st->capacity = st->ss.length;
1021 st->ss.string = xrealloc (st->ss.string, st->capacity + 1);
1025 /* Truncates ST to at most LENGTH bytes long. */
1027 ds_truncate (struct string *st, size_t length)
1029 ss_truncate (&st->ss, length);
1032 /* Removes trailing bytes in TRIM_SET from ST.
1033 Returns number of bytes removed. */
1035 ds_rtrim (struct string *st, struct substring trim_set)
1037 return ss_rtrim (&st->ss, trim_set);
1040 /* Removes leading bytes in TRIM_SET from ST.
1041 Returns number of bytes removed. */
1043 ds_ltrim (struct string *st, struct substring trim_set)
1045 size_t cnt = ds_span (st, trim_set);
1047 ds_assign_substring (st, ds_substr (st, cnt, SIZE_MAX));
1051 /* Trims leading and trailing bytes in TRIM_SET from ST.
1052 Returns number of bytes removed. */
1054 ds_trim (struct string *st, struct substring trim_set)
1056 size_t cnt = ds_rtrim (st, trim_set);
1057 return cnt + ds_ltrim (st, trim_set);
1060 /* If the last byte in ST is C, removes it and returns true.
1061 Otherwise, returns false without modifying ST. */
1063 ds_chomp_byte (struct string *st, char c)
1065 return ss_chomp_byte (&st->ss, c);
1068 /* If ST ends with SUFFIX, removes it and returns true.
1069 Otherwise, returns false without modifying ST. */
1071 ds_chomp (struct string *st, struct substring suffix)
1073 return ss_chomp (&st->ss, suffix);
1076 /* Divides ST into tokens separated by any of the DELIMITERS.
1077 Each call replaces TOKEN by the next token in ST, or by an
1078 empty string if no tokens remain. Returns true if a token was
1079 obtained, false otherwise.
1081 Before the first call, initialize *SAVE_IDX to 0. Do not
1082 modify *SAVE_IDX between calls.
1084 ST divides into exactly one more tokens than it contains
1085 delimiters. That is, a delimiter at the start or end of ST or
1086 a pair of adjacent delimiters yields an empty token, and the
1087 empty string contains a single token. */
1089 ds_separate (const struct string *st, struct substring delimiters,
1090 size_t *save_idx, struct substring *token)
1092 return ss_separate (ds_ss (st), delimiters, save_idx, token);
1095 /* Divides ST into tokens separated by any of the DELIMITERS,
1096 merging adjacent delimiters so that the empty string is never
1097 produced as a token. Each call replaces TOKEN by the next
1098 token in ST, or by an empty string if no tokens remain.
1099 Returns true if a token was obtained, false otherwise.
1101 Before the first call, initialize *SAVE_IDX to 0. Do not
1102 modify *SAVE_IDX between calls. */
1104 ds_tokenize (const struct string *st, struct substring delimiters,
1105 size_t *save_idx, struct substring *token)
1107 return ss_tokenize (ds_ss (st), delimiters, save_idx, token);
1110 /* Pad ST on the right with copies of PAD until ST is at least
1111 LENGTH bytes in size. If ST is initially LENGTH
1112 bytes or longer, this is a no-op. */
1114 ds_rpad (struct string *st, size_t length, char pad)
1116 if (length > st->ss.length)
1117 ds_put_byte_multiple (st, pad, length - st->ss.length);
1120 /* Sets the length of ST to exactly NEW_LENGTH,
1121 either by truncating bytes from the end,
1122 or by padding on the right with PAD. */
1124 ds_set_length (struct string *st, size_t new_length, char pad)
1126 if (st->ss.length < new_length)
1127 ds_rpad (st, new_length, pad);
1129 st->ss.length = new_length;
1132 /* Removes N bytes from ST starting at offset START. */
1134 ds_remove (struct string *st, size_t start, size_t n)
1136 if (n > 0 && start < st->ss.length)
1138 if (st->ss.length - start <= n)
1140 /* All bytes at or beyond START are deleted. */
1141 st->ss.length = start;
1145 /* Some bytes remain and must be shifted into
1147 memmove (st->ss.string + st->ss.length,
1148 st->ss.string + st->ss.length + n,
1149 st->ss.length - start - n);
1155 /* There are no bytes to delete or no bytes at or
1156 beyond START, hence deletion is a no-op. */
1160 /* Returns true if ST is empty, false otherwise. */
1162 ds_is_empty (const struct string *st)
1164 return ss_is_empty (st->ss);
1167 /* Returns the length of ST. */
1169 ds_length (const struct string *st)
1171 return ss_length (ds_ss (st));
1174 /* Returns the string data inside ST. */
1176 ds_data (const struct string *st)
1178 return ss_data (ds_ss (st));
1181 /* Returns a pointer to the null terminator ST.
1182 This might not be an actual null byte unless ds_c_str() has
1183 been called since the last modification to ST. */
1185 ds_end (const struct string *st)
1187 return ss_end (ds_ss (st));
1190 /* Returns the byte in position IDX in ST, as a value in the
1191 range of unsigned char. Returns EOF if IDX is out of the
1192 range of indexes for ST. */
1194 ds_at (const struct string *st, size_t idx)
1196 return ss_at (ds_ss (st), idx);
1199 /* Returns the first byte in ST as a value in the range of
1200 unsigned char. Returns EOF if ST is the empty string. */
1202 ds_first (const struct string *st)
1204 return ss_first (ds_ss (st));
1207 /* Returns the last byte in ST as a value in the range of
1208 unsigned char. Returns EOF if ST is the empty string. */
1210 ds_last (const struct string *st)
1212 return ss_last (ds_ss (st));
1215 /* Returns true if ST ends with SUFFIX, false otherwise. */
1217 ds_ends_with (const struct string *st, struct substring suffix)
1219 return ss_ends_with (st->ss, suffix);
1222 /* Returns the number of consecutive bytes at the beginning
1223 of ST that are in SKIP_SET. */
1225 ds_span (const struct string *st, struct substring skip_set)
1227 return ss_span (ds_ss (st), skip_set);
1230 /* Returns the number of consecutive bytes at the beginning
1231 of ST that are not in STOP_SET. */
1233 ds_cspan (const struct string *st, struct substring stop_set)
1235 return ss_cspan (ds_ss (st), stop_set);
1238 /* Returns the position of the first occurrence of byte C in
1239 ST at or after position OFS, or SIZE_MAX if there is no such
1242 ds_find_byte (const struct string *st, char c)
1244 return ss_find_byte (ds_ss (st), c);
1247 /* Compares A and B and returns a strcmp()-type comparison
1250 ds_compare (const struct string *a, const struct string *b)
1252 return ss_compare (ds_ss (a), ds_ss (b));
1255 /* Returns the position in ST that the byte at P occupies.
1256 P must point within ST or one past its end. */
1258 ds_pointer_to_position (const struct string *st, const char *p)
1260 return ss_pointer_to_position (ds_ss (st), p);
1263 /* Allocates and returns a null-terminated string that contains
1266 ds_xstrdup (const struct string *st)
1268 return ss_xstrdup (ds_ss (st));
1271 /* Returns the allocation size of ST. */
1273 ds_capacity (const struct string *st)
1275 return st->capacity;
1278 /* Returns the value of ST as a null-terminated string. */
1280 ds_cstr (const struct string *st_)
1282 struct string *st = CONST_CAST (struct string *, st_);
1283 if (st->ss.string == NULL)
1285 st->ss.string[st->ss.length] = '\0';
1286 return st->ss.string;
1289 /* Returns the value of ST as a null-terminated string and then
1290 reinitialized ST as an empty string. The caller must free the
1291 returned string with free(). */
1293 ds_steal_cstr (struct string *st)
1295 char *s = ds_cstr (st);
1300 /* Reads bytes from STREAM and appends them to ST, stopping
1301 after MAX_LENGTH bytes, after appending a newline, or
1302 after an I/O error or end of file was encountered, whichever
1303 comes first. Returns true if at least one byte was added
1304 to ST, false if no bytes were read before an I/O error or
1305 end of file (or if MAX_LENGTH was 0).
1307 This function treats LF and CR LF sequences as new-line,
1308 translating each of them to a single '\n' in ST. */
1310 ds_read_line (struct string *st, FILE *stream, size_t max_length)
1314 for (length = 0; length < max_length; length++)
1316 int c = getc (stream);
1323 ds_put_byte (st, c);
1330 /* CR followed by LF is special: translate to \n. */
1331 ds_put_byte (st, '\n');
1336 /* CR followed by anything else is just CR. */
1337 ds_put_byte (st, '\r');
1345 ds_put_byte (st, c);
1352 /* Removes a comment introduced by `#' from ST,
1353 ignoring occurrences inside quoted strings. */
1355 remove_comment (struct string *st)
1360 for (cp = ds_data (st); cp < ds_end (st); cp++)
1365 else if (*cp == '\\')
1368 else if (*cp == '\'' || *cp == '"')
1370 else if (*cp == '#')
1372 ds_truncate (st, cp - ds_cstr (st));
1377 /* Reads a line from STREAM into ST, then preprocesses as follows:
1379 - Splices lines terminated with `\'.
1381 - Deletes comments introduced by `#' outside of single or double
1384 - Deletes trailing white space.
1386 Returns true if a line was successfully read, false on
1387 failure. If LINE_NUMBER is non-null, then *LINE_NUMBER is
1388 incremented by the number of lines read. */
1390 ds_read_config_line (struct string *st, int *line_number, FILE *stream)
1395 if (!ds_read_line (st, stream, SIZE_MAX))
1398 ds_rtrim (st, ss_cstr (CC_SPACES));
1400 while (ds_chomp_byte (st, '\\'));
1402 remove_comment (st);
1406 /* Attempts to read SIZE * CNT bytes from STREAM and append them
1408 Returns true if all the requested data was read, false otherwise. */
1410 ds_read_stream (struct string *st, size_t size, size_t cnt, FILE *stream)
1414 size_t try_bytes = xtimes (cnt, size);
1415 if (size_in_bounds_p (xsum (ds_length (st), try_bytes)))
1417 char *buffer = ds_put_uninit (st, try_bytes);
1418 size_t got_bytes = fread (buffer, 1, try_bytes, stream);
1419 ds_truncate (st, ds_length (st) - (try_bytes - got_bytes));
1420 return got_bytes == try_bytes;
1432 /* Concatenates S onto ST. */
1434 ds_put_cstr (struct string *st, const char *s)
1437 ds_put_substring (st, ss_cstr (s));
1440 /* Concatenates SS to ST. */
1442 ds_put_substring (struct string *st, struct substring ss)
1444 memcpy (ds_put_uninit (st, ss_length (ss)), ss_data (ss), ss_length (ss));
1447 /* Returns ds_end(ST) and THEN increases the length by INCR. */
1449 ds_put_uninit (struct string *st, size_t incr)
1452 ds_extend (st, ds_length (st) + incr);
1454 st->ss.length += incr;
1458 /* Moves the bytes in ST following offset OFS + OLD_LEN in ST to offset OFS +
1459 NEW_LEN and returns the byte at offset OFS. The first min(OLD_LEN, NEW_LEN)
1460 bytes at the returned position are unchanged; if NEW_LEN > OLD_LEN then the
1461 following NEW_LEN - OLD_LEN bytes are initially indeterminate.
1463 The intention is that the caller should write NEW_LEN bytes at the returned
1464 position, to effectively replace the OLD_LEN bytes previously at that
1467 ds_splice_uninit (struct string *st,
1468 size_t ofs, size_t old_len, size_t new_len)
1470 if (new_len != old_len)
1472 if (new_len > old_len)
1473 ds_extend (st, ds_length (st) + (new_len - old_len));
1474 memmove (ds_data (st) + (ofs + new_len),
1475 ds_data (st) + (ofs + old_len),
1476 ds_length (st) - (ofs + old_len));
1477 st->ss.length += new_len - old_len;
1479 return ds_data (st) + ofs;
1482 /* Formats FORMAT as a printf string and appends the result to ST. */
1484 ds_put_format (struct string *st, const char *format, ...)
1488 va_start (args, format);
1489 ds_put_vformat (st, format, args);
1493 /* Formats FORMAT as a printf string and appends the result to ST. */
1495 ds_put_vformat (struct string *st, const char *format, va_list args_)
1500 va_copy (args, args_);
1501 avail = st->ss.string != NULL ? st->capacity - st->ss.length + 1 : 0;
1502 needed = vsnprintf (st->ss.string + st->ss.length, avail, format, args);
1505 if (needed >= avail)
1507 va_copy (args, args_);
1508 vsprintf (ds_put_uninit (st, needed), format, args);
1513 /* Some old libc's returned -1 when the destination string
1515 while (needed == -1)
1517 ds_extend (st, (st->capacity + 1) * 2);
1518 avail = st->capacity - st->ss.length + 1;
1520 va_copy (args, args_);
1521 needed = vsnprintf (ds_end (st), avail, format, args);
1524 st->ss.length += needed;
1528 /* Appends byte CH to ST. */
1530 ds_put_byte (struct string *st, int ch)
1532 ds_put_uninit (st, 1)[0] = ch;
1535 /* Appends CNT copies of byte CH to ST. */
1537 ds_put_byte_multiple (struct string *st, int ch, size_t cnt)
1539 memset (ds_put_uninit (st, cnt), ch, cnt);
1543 /* If relocation has been enabled, replace ST,
1544 with its relocated version */
1546 ds_relocate (struct string *st)
1548 const char *orig = ds_cstr (st);
1549 const char *rel = relocate (orig);
1554 ds_put_cstr (st, rel);
1555 /* The documentation for relocate says that casting away const
1556 and then freeing is appropriate ... */
1557 free (CONST_CAST (char *, rel));
1564 /* Operations on uint8_t "strings" */
1566 /* Copies buffer SRC, of SRC_SIZE bytes, to DST, of DST_SIZE bytes.
1567 DST is truncated to DST_SIZE bytes or padded on the right with
1568 copies of PAD as needed. */
1570 u8_buf_copy_rpad (uint8_t *dst, size_t dst_size,
1571 const uint8_t *src, size_t src_size,
1574 if (src_size >= dst_size)
1575 memmove (dst, src, dst_size);
1578 memmove (dst, src, src_size);
1579 memset (&dst[src_size], pad, dst_size - src_size);