1 /* PSPP - a program for statistical analysis.
2 Copyright (C) 1997-9, 2000, 2006, 2009, 2010, 2011, 2012, 2014,
3 2020 Free Software Foundation, Inc.
5 This program is free software: you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published by
7 the Free Software Foundation, either version 3 of the License, or
8 (at your option) any later version.
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>. */
28 #include "libpspp/cast.h"
29 #include "libpspp/i18n.h"
30 #include "libpspp/message.h"
31 #include "libpspp/pool.h"
33 #include "gl/c-ctype.h"
34 #include "gl/c-vasnprintf.h"
35 #include "gl/relocatable.h"
36 #include "gl/minmax.h"
37 #include "gl/xalloc.h"
38 #include "gl/xmemdup0.h"
41 /* Reverses the order of NBYTES bytes at address P, thus converting
42 between little- and big-endian byte orders. */
44 buf_reverse (char *p, size_t nbytes)
46 char *h = p, *t = &h[nbytes - 1];
58 /* Compares the SIZE bytes in A to those in B, disregarding case,
59 and returns a strcmp()-type result. */
61 buf_compare_case (const char *a_, const char *b_, size_t size)
63 const unsigned char *a = (unsigned char *) a_;
64 const unsigned char *b = (unsigned char *) b_;
68 unsigned char ac = toupper (*a++);
69 unsigned char bc = toupper (*b++);
72 return ac > bc ? 1 : -1;
78 /* Compares A of length A_LEN to B of length B_LEN. The shorter
79 string is considered to be padded with spaces to the length of
82 buf_compare_rpad (const char *a, size_t a_len, const char *b, size_t b_len)
87 min_len = a_len < b_len ? a_len : b_len;
88 result = memcmp (a, b, min_len);
97 for (idx = min_len; idx < b_len; idx++)
99 return ' ' > b[idx] ? 1 : -1;
103 for (idx = min_len; idx < a_len; idx++)
105 return a[idx] > ' ' ? 1 : -1;
111 /* Compares strin A to string B. The shorter string is
112 considered to be padded with spaces to the length of the
115 str_compare_rpad (const char *a, const char *b)
117 return buf_compare_rpad (a, strlen (a), b, strlen (b));
120 /* Copies string SRC to buffer DST, of size DST_SIZE bytes.
121 DST is truncated to DST_SIZE bytes or padded on the right with
122 copies of PAD as needed. */
124 buf_copy_str_rpad (char *dst, size_t dst_size, const char *src, char pad)
126 size_t src_len = strlen (src);
127 if (src_len >= dst_size)
128 memcpy (dst, src, dst_size);
131 memcpy (dst, src, src_len);
132 memset (&dst[src_len], pad, dst_size - src_len);
136 /* Copies string SRC to buffer DST, of size DST_SIZE bytes.
137 DST is truncated to DST_SIZE bytes or padded on the left with
138 copies of PAD as needed. */
140 buf_copy_str_lpad (char *dst, size_t dst_size, const char *src, char pad)
142 size_t src_len = strlen (src);
143 if (src_len >= dst_size)
144 memcpy (dst, src, dst_size);
147 size_t n_pad = dst_size - src_len;
148 memset (&dst[0], pad, n_pad);
149 memcpy (dst + n_pad, src, src_len);
153 /* Copies buffer SRC, of SRC_SIZE bytes, to DST, of DST_SIZE bytes.
154 DST is truncated to DST_SIZE bytes or padded on the left with
155 copies of PAD as needed. */
157 buf_copy_lpad (char *dst, size_t dst_size,
158 const char *src, size_t src_size,
161 if (src_size >= dst_size)
162 memmove (dst, src, dst_size);
165 memset (dst, pad, dst_size - src_size);
166 memmove (&dst[dst_size - src_size], src, src_size);
170 /* Copies buffer SRC, of SRC_SIZE bytes, to DST, of DST_SIZE bytes.
171 DST is truncated to DST_SIZE bytes or padded on the right with
172 copies of PAD as needed. */
174 buf_copy_rpad (char *dst, size_t dst_size,
175 const char *src, size_t src_size,
178 if (src_size >= dst_size)
179 memmove (dst, src, dst_size);
182 memmove (dst, src, src_size);
183 memset (&dst[src_size], pad, dst_size - src_size);
187 /* Copies string SRC to string DST, which is in a buffer DST_SIZE
189 Truncates DST to DST_SIZE - 1 bytes or right-pads with
190 spaces to DST_SIZE - 1 bytes if necessary. */
192 str_copy_rpad (char *dst, size_t dst_size, const char *src)
196 size_t src_len = strlen (src);
197 if (src_len < dst_size - 1)
199 memcpy (dst, src, src_len);
200 memset (&dst[src_len], ' ', dst_size - 1 - src_len);
203 memcpy (dst, src, dst_size - 1);
204 dst[dst_size - 1] = 0;
208 /* Copies SRC to DST, which is in a buffer DST_SIZE bytes long.
209 Truncates DST to DST_SIZE - 1 bytes, if necessary. */
211 str_copy_trunc (char *dst, size_t dst_size, const char *src)
213 size_t src_len = strlen (src);
214 assert (dst_size > 0);
215 if (src_len + 1 < dst_size)
216 memcpy (dst, src, src_len + 1);
219 memcpy (dst, src, dst_size - 1);
220 dst[dst_size - 1] = '\0';
224 /* Copies buffer SRC, of SRC_LEN bytes,
225 to DST, which is in a buffer DST_SIZE bytes long.
226 Truncates DST to DST_SIZE - 1 bytes, if necessary. */
228 str_copy_buf_trunc (char *dst, size_t dst_size,
229 const char *src, size_t src_size)
232 assert (dst_size > 0);
234 dst_len = src_size < dst_size ? src_size : dst_size - 1;
235 memcpy (dst, src, dst_len);
239 /* Converts each byte in S to uppercase.
241 This is suitable only for ASCII strings. Use utf8_to_upper() for UTF-8
244 str_uppercase (char *s)
246 for (; *s != '\0'; s++)
247 *s = c_toupper ((unsigned char) *s);
250 /* Converts each byte in S to lowercase.
252 This is suitable only for ASCII strings. Use utf8_to_lower() for UTF-8
255 str_lowercase (char *s)
257 for (; *s != '\0'; s++)
258 *s = c_tolower ((unsigned char) *s);
261 /* Converts NUMBER into a string in 26-adic notation in BUFFER,
262 which has room for SIZE bytes. Uses uppercase if UPPERCASE is
263 true, otherwise lowercase, Returns true if successful, false
264 if NUMBER, plus a trailing null, is too large to fit in the
267 26-adic notation is "spreadsheet column numbering": 1 = A, 2 =
268 B, 3 = C, ... 26 = Z, 27 = AA, 28 = AB, 29 = AC, ...
270 26-adic notation is the special case of a k-adic numeration
271 system (aka bijective base-k numeration) with k=26. In k-adic
272 numeration, the digits are {1, 2, 3, ..., k} (there is no
273 digit 0), and integer 0 is represented by the empty string.
274 For more information, see
275 http://en.wikipedia.org/wiki/Bijective_numeration. */
277 str_format_26adic (unsigned long int number, bool uppercase,
278 char buffer[], size_t size)
281 = uppercase ? "ABCDEFGHIJKLMNOPQRSTUVWXYZ" : "abcdefghijklmnopqrstuvwxyz";
288 buffer[length++] = alphabet[number % 26];
294 buffer[length] = '\0';
296 buf_reverse (buffer, length);
305 /* Copies IN to buffer OUT with size OUT_SIZE, appending a null terminator. If
306 IN is too long for OUT, or if IN contains a new-line, replaces the tail with
309 OUT_SIZE must be at least 16. */
311 str_ellipsize (struct substring in, char *out, size_t out_size)
313 assert (out_size >= 16);
315 size_t out_maxlen = out_size - 1;
316 if (in.length > out_maxlen - 3)
320 while (out_len < in.length
321 && in.string[out_len] != '\n'
322 && in.string[out_len] != '\0'
323 && (in.string[out_len] != '\r'
324 || out_len + 1 >= in.length
325 || in.string[out_len + 1] != '\n'))
327 int mblen = u8_mblen (CHAR_CAST (const uint8_t *, in.string + out_len),
328 in.length - out_len);
329 if (mblen < 0 || out_len + mblen > out_maxlen)
334 memcpy (out, in.string, out_len);
335 strcpy (&out[out_len], out_len < in.length ? "..." : "");
338 /* Sets the SIZE bytes starting at BLOCK to C,
339 and returns the byte following BLOCK. */
341 mempset (void *block, int c, size_t size)
343 memset (block, c, size);
344 return (char *) block + size;
349 /* Returns a substring whose contents are the N bytes
350 starting at the (0-based) position START in SS. */
352 ss_substr (struct substring ss, size_t start, size_t n)
354 if (start < ss.length)
355 return ss_buffer (ss.string + start, MIN (n, ss.length - start));
357 return ss_buffer (ss.string + ss.length, 0);
360 /* Returns a substring whose contents are the first N
363 ss_head (struct substring ss, size_t n)
365 return ss_buffer (ss.string, MIN (n, ss.length));
368 /* Returns a substring whose contents are the last N bytes
371 ss_tail (struct substring ss, size_t n)
374 return ss_buffer (ss.string + (ss.length - n), n);
379 /* Returns a malloc()'d, null-terminated copy of the contents of OLD. The
380 caller owns the returned string and must eventually free it. */
382 ss_clone (struct substring old)
384 return (struct substring) {
385 .string = xmemdup0 (old.string, old.length),
386 .length = old.length,
390 /* Allocates room for a N-byte string in NEW. */
392 ss_alloc_uninit (struct substring *new, size_t n)
394 new->string = xmalloc (n);
399 ss_realloc (struct substring *ss, size_t size)
401 ss->string = xrealloc (ss->string, size);
404 /* Returns a pool_alloc_unaligned()'d, null-terminated copy of the contents of
405 OLD in POOL. The pool owns the returned string. */
407 ss_clone_pool (struct substring old, struct pool *pool)
409 return (struct substring) {
410 .string = pool_memdup0 (pool, old.string, old.length),
415 /* Allocates room for a N-byte string in NEW in POOL. */
417 ss_alloc_uninit_pool (struct substring *new, size_t n, struct pool *pool)
419 new->string = pool_alloc_unaligned (pool, n);
423 /* Frees the string that SS points to. */
425 ss_dealloc (struct substring *ss)
430 /* Exchanges the contents of A and B. */
432 ss_swap (struct substring *a, struct substring *b)
434 struct substring tmp = *a;
439 /* Truncates SS to at most N bytes in length. */
441 ss_truncate (struct substring *ss, size_t n)
447 /* Removes trailing bytes in TRIM_SET from SS.
448 Returns number of bytes removed. */
450 ss_rtrim (struct substring *ss, struct substring trim_set)
453 while (n < ss->length
454 && ss_find_byte (trim_set,
455 ss->string[ss->length - n - 1]) != SIZE_MAX)
461 /* Removes leading bytes in TRIM_SET from SS.
462 Returns number of bytes removed. */
464 ss_ltrim (struct substring *ss, struct substring trim_set)
466 size_t n = ss_span (*ss, trim_set);
471 /* Trims leading and trailing bytes in TRIM_SET from SS. */
473 ss_trim (struct substring *ss, struct substring trim_set)
475 ss_ltrim (ss, trim_set);
476 ss_rtrim (ss, trim_set);
479 /* If the last byte in SS is C, removes it and returns true.
480 Otherwise, returns false without changing the string. */
482 ss_chomp_byte (struct substring *ss, char c)
484 if (ss_last (*ss) == c)
493 /* If SS ends with SUFFIX, removes it and returns true.
494 Otherwise, returns false without changing the string. */
496 ss_chomp (struct substring *ss, struct substring suffix)
498 if (ss_ends_with (*ss, suffix))
500 ss->length -= suffix.length;
507 /* Divides SS into tokens separated by any of the DELIMITERS.
508 Each call replaces TOKEN by the next token in SS, or by an
509 empty string if no tokens remain. Returns true if a token was
510 obtained, false otherwise.
512 Before the first call, initialize *SAVE_IDX to 0. Do not
513 modify *SAVE_IDX between calls.
515 SS divides into exactly one more tokens than it contains
516 delimiters. That is, a delimiter at the start or end of SS or
517 a pair of adjacent delimiters yields an empty token, and the
518 empty string contains a single token. */
520 ss_separate (struct substring ss, struct substring delimiters,
521 size_t *save_idx, struct substring *token)
523 if (*save_idx <= ss_length (ss))
525 struct substring tmp = ss_substr (ss, *save_idx, SIZE_MAX);
526 size_t length = ss_cspan (tmp, delimiters);
527 *token = ss_head (tmp, length);
528 *save_idx += length + 1;
533 *token = ss_empty ();
538 /* Divides SS into tokens separated by any of the DELIMITERS,
539 merging adjacent delimiters so that the empty string is never
540 produced as a token. Each call replaces TOKEN by the next
541 token in SS, or by an empty string if no tokens remain, and
542 then skips past the first delimiter following the token.
543 Returns true if a token was obtained, false otherwise.
545 Before the first call, initialize *SAVE_IDX to 0. Do not
546 modify *SAVE_IDX between calls. */
548 ss_tokenize (struct substring ss, struct substring delimiters,
549 size_t *save_idx, struct substring *token)
553 ss_advance (&ss, *save_idx);
554 *save_idx += ss_ltrim (&ss, delimiters);
555 ss_get_bytes (&ss, ss_cspan (ss, delimiters), token);
557 found_token = ss_length (*token) > 0;
558 *save_idx += ss_length (*token) + (found_token?1:0);
562 /* Removes the first N bytes from SS. */
564 ss_advance (struct substring *ss, size_t n)
572 /* If the first byte in SS is C, removes it and returns true.
573 Otherwise, returns false without changing the string. */
575 ss_match_byte (struct substring *ss, char c)
577 if (ss_first (*ss) == c)
587 /* If the first byte in SS is in MATCH, removes it and
588 returns the byte that was removed.
589 Otherwise, returns EOF without changing the string. */
591 ss_match_byte_in (struct substring *ss, struct substring match)
595 && memchr (match.string, ss->string[0], match.length) != NULL)
604 /* If SS begins with TARGET, removes it and returns true.
605 Otherwise, returns false without changing SS. */
607 ss_match_string (struct substring *ss, const struct substring target)
609 size_t length = ss_length (target);
610 if (ss_equals (ss_head (*ss, length), target))
612 ss_advance (ss, length);
619 /* If SS begins with TARGET, except possibly for case differences, removes it
620 and returns true. Otherwise, returns false without changing SS. */
622 ss_match_string_case (struct substring *ss, const struct substring target)
624 size_t length = ss_length (target);
625 if (ss_equals_case (ss_head (*ss, length), target))
627 ss_advance (ss, length);
634 /* Removes the first byte from SS and returns it.
635 If SS is empty, returns EOF without modifying SS. */
637 ss_get_byte (struct substring *ss)
639 int c = ss_first (*ss);
648 /* Stores the prefix of SS up to the first DELIMITER in OUT (if
649 any). Trims those same bytes from SS. DELIMITER is
650 removed from SS but not made part of OUT. Returns true if
651 DELIMITER was found (and removed), false otherwise. */
653 ss_get_until (struct substring *ss, char delimiter, struct substring *out)
655 ss_get_bytes (ss, ss_cspan (*ss, ss_buffer (&delimiter, 1)), out);
656 return ss_match_byte (ss, delimiter);
659 /* Stores the first N bytes in SS in OUT (or fewer, if SS
660 is shorter than N bytes). Trims the same bytes
661 from the beginning of SS. Returns N. */
663 ss_get_bytes (struct substring *ss, size_t n, struct substring *out)
665 *out = ss_head (*ss, n);
670 /* Parses and removes an optionally signed decimal integer from
671 the beginning of SS. Returns 0 if an error occurred,
672 otherwise the number of bytes removed from SS. Stores
673 the integer's value into *VALUE. */
675 ss_get_long (struct substring *ss, long *value)
680 length = ss_span (*ss, ss_cstr ("+-"));
681 length += ss_span (ss_substr (*ss, length, SIZE_MAX), ss_cstr (CC_DIGITS));
682 if (length > 0 && length < sizeof tmp)
686 memcpy (tmp, ss_data (*ss), length);
689 *value = strtol (tmp, &tail, 10);
690 if (tail - tmp == length)
692 ss_advance (ss, length);
700 /* Returns true if SS is empty (has length 0 bytes),
703 ss_is_empty (struct substring ss)
705 return ss.length == 0;
708 /* Returns the number of bytes in SS. */
710 ss_length (struct substring ss)
715 /* Returns a pointer to the bytes in SS. */
717 ss_data (struct substring ss)
722 /* Returns a pointer just past the last byte in SS. */
724 ss_end (struct substring ss)
726 return ss.string + ss.length;
729 /* Returns the byte in position IDX in SS, as a value in the
730 range of unsigned char. Returns EOF if IDX is out of the
731 range of indexes for SS. */
733 ss_at (struct substring ss, size_t idx)
735 return idx < ss.length ? (unsigned char) ss.string[idx] : EOF;
738 /* Returns the first byte in SS as a value in the range of
739 unsigned char. Returns EOF if SS is the empty string. */
741 ss_first (struct substring ss)
743 return ss_at (ss, 0);
746 /* Returns the last byte in SS as a value in the range of
747 unsigned char. Returns EOF if SS is the empty string. */
749 ss_last (struct substring ss)
751 return ss.length > 0 ? (unsigned char) ss.string[ss.length - 1] : EOF;
754 /* Returns true if SS starts with PREFIX, false otherwise. */
756 ss_starts_with (struct substring ss, struct substring prefix)
758 return (ss.length >= prefix.length
759 && !memcmp (ss.string, prefix.string, prefix.length));
762 /* Returns true if SS starts with PREFIX in any case, false otherwise. */
764 ss_starts_with_case (struct substring ss, struct substring prefix)
766 return (ss.length >= prefix.length
767 && !memcasecmp (ss.string, prefix.string, prefix.length));
770 /* Returns true if SS ends with SUFFIX, false otherwise. */
772 ss_ends_with (struct substring ss, struct substring suffix)
774 return (ss.length >= suffix.length
775 && !memcmp (&ss.string[ss.length - suffix.length], suffix.string,
779 /* Returns true if SS ends with SUFFIX in any case, false otherwise. */
781 ss_ends_with_case (struct substring ss, struct substring suffix)
783 return (ss.length >= suffix.length
784 && !memcasecmp (&ss.string[ss.length - suffix.length], suffix.string,
788 /* Returns the number of contiguous bytes at the beginning
789 of SS that are in SKIP_SET. */
791 ss_span (struct substring ss, struct substring skip_set)
794 for (i = 0; i < ss.length; i++)
795 if (ss_find_byte (skip_set, ss.string[i]) == SIZE_MAX)
800 /* Returns the number of contiguous bytes at the beginning
801 of SS that are not in SKIP_SET. */
803 ss_cspan (struct substring ss, struct substring stop_set)
806 for (i = 0; i < ss.length; i++)
807 if (ss_find_byte (stop_set, ss.string[i]) != SIZE_MAX)
812 /* Returns the offset in SS of the first instance of C,
813 or SIZE_MAX if C does not occur in SS. */
815 ss_find_byte (struct substring ss, char c)
817 const char *p = memchr (ss.string, (int) c, ss.length);
818 return p != NULL ? p - ss.string : SIZE_MAX;
821 /* Returns the offset in HAYSTACK of the first instance of NEEDLE,
822 or SIZE_MAX if NEEDLE does not occur in HAYSTACK. */
824 ss_find_substring (struct substring haystack, struct substring needle)
826 const char *p = memmem (haystack.string, haystack.length,
827 needle.string, needle.length);
828 return p != NULL ? p - haystack.string : SIZE_MAX;
831 /* Compares A and B and returns a strcmp()-type comparison
834 ss_compare (struct substring a, struct substring b)
836 int retval = memcmp (a.string, b.string, MIN (a.length, b.length));
838 retval = a.length < b.length ? -1 : a.length > b.length;
842 /* Compares A to B and returns a strcmp()-type comparison result. The shorter
843 string is considered to be padded with spaces to the length of the
846 ss_compare_rpad (struct substring a, struct substring b)
848 return buf_compare_rpad (a.string, a.length, b.string, b.length);
851 /* Compares A and B case-insensitively and returns a
852 strcmp()-type comparison result. */
854 ss_compare_case (struct substring a, struct substring b)
856 int retval = memcasecmp (a.string, b.string, MIN (a.length, b.length));
858 retval = a.length < b.length ? -1 : a.length > b.length;
862 /* Compares A and B and returns true if their contents are
863 identical, false otherwise. */
865 ss_equals (struct substring a, struct substring b)
867 return a.length == b.length && !memcmp (a.string, b.string, a.length);
870 /* Compares A and B and returns true if their contents are
871 identical except possibly for case differences, false
874 ss_equals_case (struct substring a, struct substring b)
876 return a.length == b.length && !memcasecmp (a.string, b.string, a.length);
879 /* Returns the position in SS that the byte at P occupies.
880 P must point within SS or one past its end. */
882 ss_pointer_to_position (struct substring ss, const char *p)
884 size_t pos = p - ss.string;
885 assert (pos <= ss.length);
889 /* Allocates and returns a null-terminated string that contains
892 ss_xstrdup (struct substring ss)
894 char *s = xmalloc (ss.length + 1);
895 memcpy (s, ss.string, ss.length);
901 /* Returns the character represented by the UTF-8 sequence at the start of S.
902 The return value is either a Unicode code point in the range 0 to 0x10ffff,
903 or UINT32_MAX if S is empty. */
905 ss_first_mb (struct substring s)
907 return ss_at_mb (s, 0);
910 /* Returns the number of bytes in the UTF-8 character at the beginning of S.
912 The return value is 0 if S is empty, otherwise between 1 and 4. */
914 ss_first_mblen (struct substring s)
916 return ss_at_mblen (s, 0);
919 /* Advances S past the UTF-8 character at its beginning. Returns the Unicode
920 code point that was skipped (in the range 0 to 0x10ffff), or UINT32_MAX if S
921 was not modified because it was initially empty. */
923 ss_get_mb (struct substring *s)
930 n = u8_mbtouc (&uc, CHAR_CAST (const uint8_t *, s->string), s->length);
939 /* Returns the character represented by the UTF-8 sequence starting OFS bytes
940 into S. The return value is either a Unicode code point in the range 0 to
941 0x10ffff, or UINT32_MAX if OFS is past the last byte in S.
943 (Returns 0xfffd if OFS points into the middle, not the beginning, of a UTF-8
946 ss_at_mb (struct substring s, size_t ofs)
951 u8_mbtouc (&uc, CHAR_CAST (const uint8_t *, s.string + ofs),
959 /* Returns the number of bytes represented by the UTF-8 sequence starting OFS
960 bytes into S. The return value is 0 if OFS is past the last byte in S,
961 otherwise between 1 and 4. */
963 ss_at_mblen (struct substring s, size_t ofs)
968 return u8_mbtouc (&uc, CHAR_CAST (const uint8_t *, s.string + ofs),
976 ss_utf8_count_columns (struct substring s)
978 return utf8_count_columns (s.string, s.length);
981 /* Returns a substring of S starting at 0-based display column START and
982 running for N display columns. */
984 ss_utf8_columns (struct substring s, size_t start, size_t n)
986 ss_advance (&s, utf8_columns_to_bytes (s.string, s.length, start));
987 s.length = utf8_columns_to_bytes (s.string, s.length, n);
991 /* Initializes ST as an empty string. */
993 ds_init_empty (struct string *st)
995 st->ss = ss_empty ();
999 /* Initializes ST with initial contents S. */
1001 ds_init_string (struct string *st, const struct string *s)
1003 ds_init_substring (st, ds_ss (s));
1006 /* Initializes ST with initial contents SS. */
1008 ds_init_substring (struct string *st, struct substring ss)
1010 st->capacity = MAX (8, ss.length * 2);
1011 st->ss.string = xmalloc (st->capacity + 1);
1012 memcpy (st->ss.string, ss.string, ss.length);
1013 st->ss.length = ss.length;
1016 /* Initializes ST with initial contents S. */
1018 ds_init_cstr (struct string *st, const char *s)
1020 ds_init_substring (st, ss_cstr (s));
1025 ds_destroy (struct string *st)
1029 ss_dealloc (&st->ss);
1030 st->ss.string = NULL;
1036 /* Swaps the contents of strings A and B. */
1038 ds_swap (struct string *a, struct string *b)
1040 struct string tmp = *a;
1045 /* Helper function for ds_register_pool. */
1047 free_string (void *st_)
1049 struct string *st = st_;
1053 /* Arranges for ST to be destroyed automatically as part of
1056 ds_register_pool (struct string *st, struct pool *pool)
1058 pool_register (pool, free_string, st);
1061 /* Cancels the arrangement for ST to be destroyed automatically
1064 ds_unregister_pool (struct string *st, struct pool *pool)
1066 pool_unregister (pool, st);
1069 /* Copies SRC into DST.
1070 DST and SRC may be the same string. */
1072 ds_assign_string (struct string *dst, const struct string *src)
1074 ds_assign_substring (dst, ds_ss (src));
1077 /* Replaces DST by SS.
1078 SS may be a substring of DST. */
1080 ds_assign_substring (struct string *dst, struct substring ss)
1082 dst->ss.length = ss.length;
1083 ds_extend (dst, ss.length);
1084 memmove (dst->ss.string, ss.string, ss.length);
1087 /* Replaces DST by null-terminated string SRC. SRC may overlap
1090 ds_assign_cstr (struct string *dst, const char *src)
1092 ds_assign_substring (dst, ss_cstr (src));
1095 /* Truncates ST to zero length. */
1097 ds_clear (struct string *st)
1102 /* Returns a substring that contains ST. */
1104 ds_ss (const struct string *st)
1109 /* Returns a substring that contains N bytes from ST
1110 starting at position START.
1112 If START is greater than or equal to the length of ST, then
1113 the substring will be the empty string. If START + N
1114 exceeds the length of ST, then the substring will only be
1115 ds_length(ST) - START bytes long. */
1117 ds_substr (const struct string *st, size_t start, size_t n)
1119 return ss_substr (ds_ss (st), start, n);
1122 /* Returns a substring that contains the first N bytes in
1123 ST. If N exceeds the length of ST, then the substring will
1124 contain all of ST. */
1126 ds_head (const struct string *st, size_t n)
1128 return ss_head (ds_ss (st), n);
1131 /* Returns a substring that contains the last N bytes in
1132 ST. If N exceeds the length of ST, then the substring will
1133 contain all of ST. */
1135 ds_tail (const struct string *st, size_t n)
1137 return ss_tail (ds_ss (st), n);
1140 /* Ensures that ST can hold at least MIN_CAPACITY bytes plus a null
1143 ds_extend (struct string *st, size_t min_capacity)
1145 if (min_capacity > st->capacity)
1148 if (st->capacity < min_capacity)
1149 st->capacity = 2 * min_capacity;
1151 st->ss.string = xrealloc (st->ss.string, st->capacity + 1);
1155 /* Shrink ST to the minimum capacity need to contain its content. */
1157 ds_shrink (struct string *st)
1159 if (st->capacity != st->ss.length)
1161 st->capacity = st->ss.length;
1162 st->ss.string = xrealloc (st->ss.string, st->capacity + 1);
1166 /* Truncates ST to at most LENGTH bytes long. */
1168 ds_truncate (struct string *st, size_t length)
1170 ss_truncate (&st->ss, length);
1173 /* Removes trailing bytes in TRIM_SET from ST.
1174 Returns number of bytes removed. */
1176 ds_rtrim (struct string *st, struct substring trim_set)
1178 return ss_rtrim (&st->ss, trim_set);
1181 /* Removes leading bytes in TRIM_SET from ST.
1182 Returns number of bytes removed. */
1184 ds_ltrim (struct string *st, struct substring trim_set)
1186 size_t n = ds_span (st, trim_set);
1188 ds_assign_substring (st, ds_substr (st, n, SIZE_MAX));
1192 /* Trims leading and trailing bytes in TRIM_SET from ST.
1193 Returns number of bytes removed. */
1195 ds_trim (struct string *st, struct substring trim_set)
1197 size_t n = ds_rtrim (st, trim_set);
1198 return n + ds_ltrim (st, trim_set);
1201 /* If the last byte in ST is C, removes it and returns true.
1202 Otherwise, returns false without modifying ST. */
1204 ds_chomp_byte (struct string *st, char c)
1206 return ss_chomp_byte (&st->ss, c);
1209 /* If ST ends with SUFFIX, removes it and returns true.
1210 Otherwise, returns false without modifying ST. */
1212 ds_chomp (struct string *st, struct substring suffix)
1214 return ss_chomp (&st->ss, suffix);
1217 /* Divides ST into tokens separated by any of the DELIMITERS.
1218 Each call replaces TOKEN by the next token in ST, or by an
1219 empty string if no tokens remain. Returns true if a token was
1220 obtained, false otherwise.
1222 Before the first call, initialize *SAVE_IDX to 0. Do not
1223 modify *SAVE_IDX between calls.
1225 ST divides into exactly one more tokens than it contains
1226 delimiters. That is, a delimiter at the start or end of ST or
1227 a pair of adjacent delimiters yields an empty token, and the
1228 empty string contains a single token. */
1230 ds_separate (const struct string *st, struct substring delimiters,
1231 size_t *save_idx, struct substring *token)
1233 return ss_separate (ds_ss (st), delimiters, save_idx, token);
1236 /* Divides ST into tokens separated by any of the DELIMITERS,
1237 merging adjacent delimiters so that the empty string is never
1238 produced as a token. Each call replaces TOKEN by the next
1239 token in ST, or by an empty string if no tokens remain.
1240 Returns true if a token was obtained, false otherwise.
1242 Before the first call, initialize *SAVE_IDX to 0. Do not
1243 modify *SAVE_IDX between calls. */
1245 ds_tokenize (const struct string *st, struct substring delimiters,
1246 size_t *save_idx, struct substring *token)
1248 return ss_tokenize (ds_ss (st), delimiters, save_idx, token);
1251 /* Pad ST on the right with copies of PAD until ST is at least
1252 LENGTH bytes in size. If ST is initially LENGTH
1253 bytes or longer, this is a no-op. */
1255 ds_rpad (struct string *st, size_t length, char pad)
1257 if (length > st->ss.length)
1258 ds_put_byte_multiple (st, pad, length - st->ss.length);
1261 /* Sets the length of ST to exactly NEW_LENGTH,
1262 either by truncating bytes from the end,
1263 or by padding on the right with PAD. */
1265 ds_set_length (struct string *st, size_t new_length, char pad)
1267 if (st->ss.length < new_length)
1268 ds_rpad (st, new_length, pad);
1270 st->ss.length = new_length;
1273 /* Removes N bytes from ST starting at offset START. */
1275 ds_remove (struct string *st, size_t start, size_t n)
1277 if (n > 0 && start < st->ss.length)
1279 if (st->ss.length - start <= n)
1281 /* All bytes at or beyond START are deleted. */
1282 st->ss.length = start;
1286 /* Some bytes remain and must be shifted into
1288 memmove (st->ss.string + st->ss.length,
1289 st->ss.string + st->ss.length + n,
1290 st->ss.length - start - n);
1296 /* There are no bytes to delete or no bytes at or
1297 beyond START, hence deletion is a no-op. */
1301 /* Returns true if ST is empty, false otherwise. */
1303 ds_is_empty (const struct string *st)
1305 return ss_is_empty (st->ss);
1308 /* Returns the length of ST. */
1310 ds_length (const struct string *st)
1312 return ss_length (ds_ss (st));
1315 /* Returns the string data inside ST. */
1317 ds_data (const struct string *st)
1319 return ss_data (ds_ss (st));
1322 /* Returns a pointer to the null terminator ST.
1323 This might not be an actual null byte unless ds_c_str() has
1324 been called since the last modification to ST. */
1326 ds_end (const struct string *st)
1328 return ss_end (ds_ss (st));
1331 /* Returns the byte in position IDX in ST, as a value in the
1332 range of unsigned char. Returns EOF if IDX is out of the
1333 range of indexes for ST. */
1335 ds_at (const struct string *st, size_t idx)
1337 return ss_at (ds_ss (st), idx);
1340 /* Returns the first byte in ST as a value in the range of
1341 unsigned char. Returns EOF if ST is the empty string. */
1343 ds_first (const struct string *st)
1345 return ss_first (ds_ss (st));
1348 /* Returns the last byte in ST as a value in the range of
1349 unsigned char. Returns EOF if ST is the empty string. */
1351 ds_last (const struct string *st)
1353 return ss_last (ds_ss (st));
1356 /* Returns true if ST ends with SUFFIX, false otherwise. */
1358 ds_ends_with (const struct string *st, struct substring suffix)
1360 return ss_ends_with (st->ss, suffix);
1363 /* Returns the number of consecutive bytes at the beginning
1364 of ST that are in SKIP_SET. */
1366 ds_span (const struct string *st, struct substring skip_set)
1368 return ss_span (ds_ss (st), skip_set);
1371 /* Returns the number of consecutive bytes at the beginning
1372 of ST that are not in STOP_SET. */
1374 ds_cspan (const struct string *st, struct substring stop_set)
1376 return ss_cspan (ds_ss (st), stop_set);
1379 /* Returns the position of the first occurrence of byte C in
1380 ST at or after position OFS, or SIZE_MAX if there is no such
1383 ds_find_byte (const struct string *st, char c)
1385 return ss_find_byte (ds_ss (st), c);
1388 /* Compares A and B and returns a strcmp()-type comparison
1391 ds_compare (const struct string *a, const struct string *b)
1393 return ss_compare (ds_ss (a), ds_ss (b));
1396 /* Returns the position in ST that the byte at P occupies.
1397 P must point within ST or one past its end. */
1399 ds_pointer_to_position (const struct string *st, const char *p)
1401 return ss_pointer_to_position (ds_ss (st), p);
1404 /* Allocates and returns a null-terminated string that contains
1407 ds_xstrdup (const struct string *st)
1409 return ss_xstrdup (ds_ss (st));
1412 /* Returns the allocation size of ST. */
1414 ds_capacity (const struct string *st)
1416 return st->capacity;
1419 /* Returns the value of ST as a null-terminated string. */
1421 ds_cstr (const struct string *st_)
1423 struct string *st = CONST_CAST (struct string *, st_);
1424 if (st->ss.string == NULL)
1426 st->ss.string[st->ss.length] = '\0';
1427 return st->ss.string;
1430 /* Returns the value of ST as a null-terminated string and then
1431 reinitialized ST as an empty string. The caller must free the
1432 returned string with free(). */
1434 ds_steal_cstr (struct string *st)
1436 char *s = ds_cstr (st);
1441 /* Reads bytes from STREAM and appends them to ST, stopping
1442 after MAX_LENGTH bytes, after appending a newline, or
1443 after an I/O error or end of file was encountered, whichever
1444 comes first. Returns true if at least one byte was added
1445 to ST, false if no bytes were read before an I/O error or
1446 end of file (or if MAX_LENGTH was 0).
1448 This function treats LF and CR LF sequences as new-line,
1449 translating each of them to a single '\n' in ST. */
1451 ds_read_line (struct string *st, FILE *stream, size_t max_length)
1455 for (length = 0; length < max_length; length++)
1457 int c = getc (stream);
1464 ds_put_byte (st, c);
1471 /* CR followed by LF is special: translate to \n. */
1472 ds_put_byte (st, '\n');
1477 /* CR followed by anything else is just CR. */
1478 ds_put_byte (st, '\r');
1486 ds_put_byte (st, c);
1493 /* Removes a comment introduced by `#' from ST,
1494 ignoring occurrences inside quoted strings. */
1496 remove_comment (struct string *st)
1501 for (cp = ds_data (st); cp < ds_end (st); cp++)
1506 else if (*cp == '\\')
1509 else if (*cp == '\'' || *cp == '"')
1511 else if (*cp == '#')
1513 ds_truncate (st, cp - ds_cstr (st));
1518 /* Reads a line from STREAM into ST, then preprocesses as follows:
1520 - Splices lines terminated with `\'.
1522 - Deletes comments introduced by `#' outside of single or double
1525 - Deletes trailing white space.
1527 Returns true if a line was successfully read, false on
1528 failure. If LINE_NUMBER is non-null, then *LINE_NUMBER is
1529 incremented by the number of lines read. */
1531 ds_read_config_line (struct string *st, int *line_number, FILE *stream)
1536 if (!ds_read_line (st, stream, SIZE_MAX))
1539 ds_rtrim (st, ss_cstr (CC_SPACES));
1541 while (ds_chomp_byte (st, '\\'));
1543 remove_comment (st);
1547 /* Attempts to read SIZE * N bytes from STREAM and append them
1549 Returns true if all the requested data was read, false otherwise. */
1551 ds_read_stream (struct string *st, size_t size, size_t n, FILE *stream)
1555 size_t try_bytes = xtimes (n, size);
1556 if (size_in_bounds_p (xsum (ds_length (st), try_bytes)))
1558 char *buffer = ds_put_uninit (st, try_bytes);
1559 size_t got_bytes = fread (buffer, 1, try_bytes, stream);
1560 ds_truncate (st, ds_length (st) - (try_bytes - got_bytes));
1561 return got_bytes == try_bytes;
1573 /* Concatenates S onto ST. */
1575 ds_put_cstr (struct string *st, const char *s)
1578 ds_put_substring (st, ss_cstr (s));
1581 /* Concatenates SS to ST. */
1583 ds_put_substring (struct string *st, struct substring ss)
1586 memcpy (ds_put_uninit (st, ss_length (ss)), ss_data (ss), ss_length (ss));
1589 /* Returns ds_end(ST) and THEN increases the length by INCR. */
1591 ds_put_uninit (struct string *st, size_t incr)
1594 ds_extend (st, ds_length (st) + incr);
1596 st->ss.length += incr;
1600 /* Moves the bytes in ST following offset OFS + OLD_LEN in ST to offset OFS +
1601 NEW_LEN and returns the byte at offset OFS. The first min(OLD_LEN, NEW_LEN)
1602 bytes at the returned position are unchanged; if NEW_LEN > OLD_LEN then the
1603 following NEW_LEN - OLD_LEN bytes are initially indeterminate.
1605 The intention is that the caller should write NEW_LEN bytes at the returned
1606 position, to effectively replace the OLD_LEN bytes previously at that
1609 ds_splice_uninit (struct string *st,
1610 size_t ofs, size_t old_len, size_t new_len)
1612 if (new_len != old_len)
1614 if (new_len > old_len)
1615 ds_extend (st, ds_length (st) + (new_len - old_len));
1617 assert (ds_length (st) >= ofs + old_len);
1619 memmove (ds_data (st) + (ofs + new_len),
1620 ds_data (st) + (ofs + old_len),
1621 ds_length (st) - (ofs + old_len));
1622 st->ss.length += new_len - old_len;
1624 return ds_data (st) + ofs;
1627 /* Formats FORMAT as a printf string and appends the result to ST. */
1629 ds_put_format (struct string *st, const char *format, ...)
1633 va_start (args, format);
1634 ds_put_vformat (st, format, args);
1638 /* Formats FORMAT as a printf string as if in the C locale and appends the result to ST. */
1640 ds_put_c_format (struct string *st, const char *format, ...)
1644 va_start (args, format);
1645 ds_put_c_vformat (st, format, args);
1649 /* Formats FORMAT as a printf string and appends the result to ST. */
1651 ds_put_vformat (struct string *st, const char *format, va_list args_)
1656 va_copy (args, args_);
1657 avail = st->ss.string != NULL ? st->capacity - st->ss.length + 1 : 0;
1658 needed = vsnprintf (st->ss.string + st->ss.length, avail, format, args);
1661 if (needed >= avail)
1663 va_copy (args, args_);
1664 vsnprintf (ds_put_uninit (st, needed), needed + 1, format, args);
1669 /* Some old libc's returned -1 when the destination string
1671 while (needed == -1)
1673 ds_extend (st, (st->capacity + 1) * 2);
1674 avail = st->capacity - st->ss.length + 1;
1676 va_copy (args, args_);
1677 needed = vsnprintf (ds_end (st), avail, format, args);
1680 st->ss.length += needed;
1684 /* Formats FORMAT as a printf string, as if in the C locale,
1685 and appends the result to ST. */
1687 ds_put_c_vformat (struct string *st, const char *format, va_list args)
1690 size_t len = sizeof buf;
1691 char *output = c_vasnprintf (buf, &len, format, args);
1694 ds_put_cstr (st, output);
1700 /* Appends byte CH to ST. */
1702 ds_put_byte (struct string *st, int ch)
1704 ds_put_uninit (st, 1)[0] = ch;
1707 /* Appends N copies of byte CH to ST. */
1709 ds_put_byte_multiple (struct string *st, int ch, size_t n)
1711 memset (ds_put_uninit (st, n), ch, n);
1714 /* Appends Unicode code point UC to ST in UTF-8 encoding. */
1716 ds_put_unichar (struct string *st, ucs4_t uc)
1718 ds_extend (st, ds_length (st) + 6);
1719 st->ss.length += u8_uctomb (CHAR_CAST (uint8_t *, ds_end (st)), uc, 6);
1722 /* Appends N copies of S to ST. */
1724 ds_put_substring_multiple (struct string *dst, struct substring src, size_t n)
1726 char *p = ds_put_uninit (dst, n * src.length);
1727 for (size_t i = 0; i < n; i++)
1729 memcpy (p, src.string, src.length);
1734 /* If relocation has been enabled, replace ST,
1735 with its relocated version */
1737 ds_relocate (struct string *st)
1739 const char *orig = ds_cstr (st);
1740 const char *rel = relocate (orig);
1745 ds_put_cstr (st, rel);
1746 /* The documentation for relocate says that casting away const
1747 and then freeing is appropriate ... */
1748 free (CONST_CAST (char *, rel));
1755 /* Operations on uint8_t "strings" */
1757 /* Copies buffer SRC, of SRC_SIZE bytes, to DST, of DST_SIZE bytes.
1758 DST is truncated to DST_SIZE bytes or padded on the right with
1759 copies of PAD as needed. */
1761 u8_buf_copy_rpad (uint8_t *dst, size_t dst_size,
1762 const uint8_t *src, size_t src_size,
1765 if (src_size >= dst_size)
1766 memmove (dst, src, dst_size);
1769 memmove (dst, src, src_size);
1770 memset (&dst[src_size], pad, dst_size - src_size);