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/message.h"
30 #include "libpspp/pool.h"
32 #include "gl/c-ctype.h"
33 #include "gl/c-vasnprintf.h"
34 #include "gl/relocatable.h"
35 #include "gl/minmax.h"
36 #include "gl/xalloc.h"
37 #include "gl/xmemdup0.h"
40 /* Reverses the order of NBYTES bytes at address P, thus converting
41 between little- and big-endian byte orders. */
43 buf_reverse (char *p, size_t nbytes)
45 char *h = p, *t = &h[nbytes - 1];
57 /* Compares the SIZE bytes in A to those in B, disregarding case,
58 and returns a strcmp()-type result. */
60 buf_compare_case (const char *a_, const char *b_, size_t size)
62 const unsigned char *a = (unsigned char *) a_;
63 const unsigned char *b = (unsigned char *) b_;
67 unsigned char ac = toupper (*a++);
68 unsigned char bc = toupper (*b++);
71 return ac > bc ? 1 : -1;
77 /* Compares A of length A_LEN to B of length B_LEN. The shorter
78 string is considered to be padded with spaces to the length of
81 buf_compare_rpad (const char *a, size_t a_len, const char *b, size_t b_len)
86 min_len = a_len < b_len ? a_len : b_len;
87 result = memcmp (a, b, min_len);
96 for (idx = min_len; idx < b_len; idx++)
98 return ' ' > b[idx] ? 1 : -1;
102 for (idx = min_len; idx < a_len; idx++)
104 return a[idx] > ' ' ? 1 : -1;
110 /* Compares strin A to string B. The shorter string is
111 considered to be padded with spaces to the length of the
114 str_compare_rpad (const char *a, const char *b)
116 return buf_compare_rpad (a, strlen (a), b, strlen (b));
119 /* Copies string SRC to buffer DST, of size DST_SIZE bytes.
120 DST is truncated to DST_SIZE bytes or padded on the right with
121 copies of PAD as needed. */
123 buf_copy_str_rpad (char *dst, size_t dst_size, const char *src, char pad)
125 size_t src_len = strlen (src);
126 if (src_len >= dst_size)
127 memcpy (dst, src, dst_size);
130 memcpy (dst, src, src_len);
131 memset (&dst[src_len], pad, dst_size - src_len);
135 /* Copies string SRC to buffer DST, of size DST_SIZE bytes.
136 DST is truncated to DST_SIZE bytes or padded on the left with
137 copies of PAD as needed. */
139 buf_copy_str_lpad (char *dst, size_t dst_size, const char *src, char pad)
141 size_t src_len = strlen (src);
142 if (src_len >= dst_size)
143 memcpy (dst, src, dst_size);
146 size_t pad_cnt = dst_size - src_len;
147 memset (&dst[0], pad, pad_cnt);
148 memcpy (dst + pad_cnt, src, src_len);
152 /* Copies buffer SRC, of SRC_SIZE bytes, to DST, of DST_SIZE bytes.
153 DST is truncated to DST_SIZE bytes or padded on the left with
154 copies of PAD as needed. */
156 buf_copy_lpad (char *dst, size_t dst_size,
157 const char *src, size_t src_size,
160 if (src_size >= dst_size)
161 memmove (dst, src, dst_size);
164 memset (dst, pad, dst_size - src_size);
165 memmove (&dst[dst_size - src_size], src, src_size);
169 /* Copies buffer SRC, of SRC_SIZE bytes, to DST, of DST_SIZE bytes.
170 DST is truncated to DST_SIZE bytes or padded on the right with
171 copies of PAD as needed. */
173 buf_copy_rpad (char *dst, size_t dst_size,
174 const char *src, size_t src_size,
177 if (src_size >= dst_size)
178 memmove (dst, src, dst_size);
181 memmove (dst, src, src_size);
182 memset (&dst[src_size], pad, dst_size - src_size);
186 /* Copies string SRC to string DST, which is in a buffer DST_SIZE
188 Truncates DST to DST_SIZE - 1 bytes or right-pads with
189 spaces to DST_SIZE - 1 bytes if necessary. */
191 str_copy_rpad (char *dst, size_t dst_size, const char *src)
195 size_t src_len = strlen (src);
196 if (src_len < dst_size - 1)
198 memcpy (dst, src, src_len);
199 memset (&dst[src_len], ' ', dst_size - 1 - src_len);
202 memcpy (dst, src, dst_size - 1);
203 dst[dst_size - 1] = 0;
207 /* Copies SRC to DST, which is in a buffer DST_SIZE bytes long.
208 Truncates DST to DST_SIZE - 1 bytes, if necessary. */
210 str_copy_trunc (char *dst, size_t dst_size, const char *src)
212 size_t src_len = strlen (src);
213 assert (dst_size > 0);
214 if (src_len + 1 < dst_size)
215 memcpy (dst, src, src_len + 1);
218 memcpy (dst, src, dst_size - 1);
219 dst[dst_size - 1] = '\0';
223 /* Copies buffer SRC, of SRC_LEN bytes,
224 to DST, which is in a buffer DST_SIZE bytes long.
225 Truncates DST to DST_SIZE - 1 bytes, if necessary. */
227 str_copy_buf_trunc (char *dst, size_t dst_size,
228 const char *src, size_t src_size)
231 assert (dst_size > 0);
233 dst_len = src_size < dst_size ? src_size : dst_size - 1;
234 memcpy (dst, src, dst_len);
238 /* Converts each byte in S to uppercase.
240 This is suitable only for ASCII strings. Use utf8_to_upper() for UTF-8
243 str_uppercase (char *s)
245 for (; *s != '\0'; s++)
246 *s = c_toupper ((unsigned char) *s);
249 /* Converts each byte in S to lowercase.
251 This is suitable only for ASCII strings. Use utf8_to_lower() for UTF-8
254 str_lowercase (char *s)
256 for (; *s != '\0'; s++)
257 *s = c_tolower ((unsigned char) *s);
260 /* Converts NUMBER into a string in 26-adic notation in BUFFER,
261 which has room for SIZE bytes. Uses uppercase if UPPERCASE is
262 true, otherwise lowercase, Returns true if successful, false
263 if NUMBER, plus a trailing null, is too large to fit in the
266 26-adic notation is "spreadsheet column numbering": 1 = A, 2 =
267 B, 3 = C, ... 26 = Z, 27 = AA, 28 = AB, 29 = AC, ...
269 26-adic notation is the special case of a k-adic numeration
270 system (aka bijective base-k numeration) with k=26. In k-adic
271 numeration, the digits are {1, 2, 3, ..., k} (there is no
272 digit 0), and integer 0 is represented by the empty string.
273 For more information, see
274 http://en.wikipedia.org/wiki/Bijective_numeration. */
276 str_format_26adic (unsigned long int number, bool uppercase,
277 char buffer[], size_t size)
280 = uppercase ? "ABCDEFGHIJKLMNOPQRSTUVWXYZ" : "abcdefghijklmnopqrstuvwxyz";
287 buffer[length++] = alphabet[number % 26];
293 buffer[length] = '\0';
295 buf_reverse (buffer, length);
304 /* Copies IN to buffer OUT with size OUT_SIZE, appending a null terminator. If
305 IN is too long for OUT, or if IN contains a new-line, replaces the tail with
308 OUT_SIZE must be at least 16. */
310 str_ellipsize (struct substring in, char *out, size_t out_size)
312 assert (out_size >= 16);
314 size_t out_maxlen = out_size - 1;
315 if (in.length > out_maxlen - 3)
319 while (out_len < in.length
320 && in.string[out_len] != '\n'
321 && in.string[out_len] != '\0'
322 && (in.string[out_len] != '\r'
323 || out_len + 1 >= in.length
324 || in.string[out_len + 1] != '\n'))
326 int mblen = u8_mblen (CHAR_CAST (const uint8_t *, in.string + out_len),
327 in.length - out_len);
328 if (mblen < 0 || out_len + mblen > out_maxlen)
333 memcpy (out, in.string, out_len);
334 strcpy (&out[out_len], out_len < in.length ? "..." : "");
337 /* Sets the SIZE bytes starting at BLOCK to C,
338 and returns the byte following BLOCK. */
340 mempset (void *block, int c, size_t size)
342 memset (block, c, size);
343 return (char *) block + size;
348 /* Returns a substring whose contents are the CNT bytes
349 starting at the (0-based) position START in SS. */
351 ss_substr (struct substring ss, size_t start, size_t cnt)
353 if (start < ss.length)
354 return ss_buffer (ss.string + start, MIN (cnt, ss.length - start));
356 return ss_buffer (ss.string + ss.length, 0);
359 /* Returns a substring whose contents are the first CNT
362 ss_head (struct substring ss, size_t cnt)
364 return ss_buffer (ss.string, MIN (cnt, ss.length));
367 /* Returns a substring whose contents are the last CNT bytes
370 ss_tail (struct substring ss, size_t cnt)
373 return ss_buffer (ss.string + (ss.length - cnt), cnt);
378 /* Makes a malloc()'d, null-terminated copy of the contents of OLD
379 and stores it in NEW. */
381 ss_alloc_substring (struct substring *new, struct substring old)
383 new->string = xmemdup0 (old.string, old.length);
384 new->length = old.length;
387 /* Allocates room for a CNT-byte string in NEW. */
389 ss_alloc_uninit (struct substring *new, size_t cnt)
391 new->string = xmalloc (cnt);
396 ss_realloc (struct substring *ss, size_t size)
398 ss->string = xrealloc (ss->string, size);
401 /* Makes a pool_alloc_unaligned()'d, null-terminated copy of the contents of
402 OLD in POOL, and stores it in NEW. */
404 ss_alloc_substring_pool (struct substring *new, struct substring old,
407 new->string = pool_alloc_unaligned (pool, old.length + 1);
408 new->length = old.length;
409 memcpy (new->string, old.string, old.length);
410 new->string[old.length] = '\0';
413 /* Allocates room for a CNT-byte string in NEW in POOL. */
415 ss_alloc_uninit_pool (struct substring *new, size_t cnt, struct pool *pool)
417 new->string = pool_alloc_unaligned (pool, cnt);
421 /* Frees the string that SS points to. */
423 ss_dealloc (struct substring *ss)
428 /* Exchanges the contents of A and B. */
430 ss_swap (struct substring *a, struct substring *b)
432 struct substring tmp = *a;
437 /* Truncates SS to at most CNT bytes in length. */
439 ss_truncate (struct substring *ss, size_t cnt)
441 if (ss->length > cnt)
445 /* Removes trailing bytes in TRIM_SET from SS.
446 Returns number of bytes removed. */
448 ss_rtrim (struct substring *ss, struct substring trim_set)
451 while (cnt < ss->length
452 && ss_find_byte (trim_set,
453 ss->string[ss->length - cnt - 1]) != SIZE_MAX)
459 /* Removes leading bytes in TRIM_SET from SS.
460 Returns number of bytes removed. */
462 ss_ltrim (struct substring *ss, struct substring trim_set)
464 size_t cnt = ss_span (*ss, trim_set);
465 ss_advance (ss, cnt);
469 /* Trims leading and trailing bytes in TRIM_SET from SS. */
471 ss_trim (struct substring *ss, struct substring trim_set)
473 ss_ltrim (ss, trim_set);
474 ss_rtrim (ss, trim_set);
477 /* If the last byte in SS is C, removes it and returns true.
478 Otherwise, returns false without changing the string. */
480 ss_chomp_byte (struct substring *ss, char c)
482 if (ss_last (*ss) == c)
491 /* If SS ends with SUFFIX, removes it and returns true.
492 Otherwise, returns false without changing the string. */
494 ss_chomp (struct substring *ss, struct substring suffix)
496 if (ss_ends_with (*ss, suffix))
498 ss->length -= suffix.length;
505 /* Divides SS into tokens separated by any of the DELIMITERS.
506 Each call replaces TOKEN by the next token in SS, or by an
507 empty string if no tokens remain. Returns true if a token was
508 obtained, false otherwise.
510 Before the first call, initialize *SAVE_IDX to 0. Do not
511 modify *SAVE_IDX between calls.
513 SS divides into exactly one more tokens than it contains
514 delimiters. That is, a delimiter at the start or end of SS or
515 a pair of adjacent delimiters yields an empty token, and the
516 empty string contains a single token. */
518 ss_separate (struct substring ss, struct substring delimiters,
519 size_t *save_idx, struct substring *token)
521 if (*save_idx <= ss_length (ss))
523 struct substring tmp = ss_substr (ss, *save_idx, SIZE_MAX);
524 size_t length = ss_cspan (tmp, delimiters);
525 *token = ss_head (tmp, length);
526 *save_idx += length + 1;
531 *token = ss_empty ();
536 /* Divides SS into tokens separated by any of the DELIMITERS,
537 merging adjacent delimiters so that the empty string is never
538 produced as a token. Each call replaces TOKEN by the next
539 token in SS, or by an empty string if no tokens remain, and
540 then skips past the first delimiter following the token.
541 Returns true if a token was obtained, false otherwise.
543 Before the first call, initialize *SAVE_IDX to 0. Do not
544 modify *SAVE_IDX between calls. */
546 ss_tokenize (struct substring ss, struct substring delimiters,
547 size_t *save_idx, struct substring *token)
551 ss_advance (&ss, *save_idx);
552 *save_idx += ss_ltrim (&ss, delimiters);
553 ss_get_bytes (&ss, ss_cspan (ss, delimiters), token);
555 found_token = ss_length (*token) > 0;
556 *save_idx += ss_length (*token) + (found_token?1:0);
560 /* Removes the first CNT bytes from SS. */
562 ss_advance (struct substring *ss, size_t cnt)
564 if (cnt > ss->length)
570 /* If the first byte in SS is C, removes it and returns true.
571 Otherwise, returns false without changing the string. */
573 ss_match_byte (struct substring *ss, char c)
575 if (ss_first (*ss) == c)
585 /* If the first byte in SS is in MATCH, removes it and
586 returns the byte that was removed.
587 Otherwise, returns EOF without changing the string. */
589 ss_match_byte_in (struct substring *ss, struct substring match)
593 && memchr (match.string, ss->string[0], match.length) != NULL)
602 /* If SS begins with TARGET, removes it and returns true.
603 Otherwise, returns false without changing SS. */
605 ss_match_string (struct substring *ss, const struct substring target)
607 size_t length = ss_length (target);
608 if (ss_equals (ss_head (*ss, length), target))
610 ss_advance (ss, length);
617 /* Removes the first byte from SS and returns it.
618 If SS is empty, returns EOF without modifying SS. */
620 ss_get_byte (struct substring *ss)
622 int c = ss_first (*ss);
631 /* Stores the prefix of SS up to the first DELIMITER in OUT (if
632 any). Trims those same bytes from SS. DELIMITER is
633 removed from SS but not made part of OUT. Returns true if
634 DELIMITER was found (and removed), false otherwise. */
636 ss_get_until (struct substring *ss, char delimiter, struct substring *out)
638 ss_get_bytes (ss, ss_cspan (*ss, ss_buffer (&delimiter, 1)), out);
639 return ss_match_byte (ss, delimiter);
642 /* Stores the first CNT bytes in SS in OUT (or fewer, if SS
643 is shorter than CNT bytes). Trims the same bytes
644 from the beginning of SS. Returns CNT. */
646 ss_get_bytes (struct substring *ss, size_t cnt, struct substring *out)
648 *out = ss_head (*ss, cnt);
649 ss_advance (ss, cnt);
653 /* Parses and removes an optionally signed decimal integer from
654 the beginning of SS. Returns 0 if an error occurred,
655 otherwise the number of bytes removed from SS. Stores
656 the integer's value into *VALUE. */
658 ss_get_long (struct substring *ss, long *value)
663 length = ss_span (*ss, ss_cstr ("+-"));
664 length += ss_span (ss_substr (*ss, length, SIZE_MAX), ss_cstr (CC_DIGITS));
665 if (length > 0 && length < sizeof tmp)
669 memcpy (tmp, ss_data (*ss), length);
672 *value = strtol (tmp, &tail, 10);
673 if (tail - tmp == length)
675 ss_advance (ss, length);
683 /* Returns true if SS is empty (has length 0 bytes),
686 ss_is_empty (struct substring ss)
688 return ss.length == 0;
691 /* Returns the number of bytes in SS. */
693 ss_length (struct substring ss)
698 /* Returns a pointer to the bytes in SS. */
700 ss_data (struct substring ss)
705 /* Returns a pointer just past the last byte in SS. */
707 ss_end (struct substring ss)
709 return ss.string + ss.length;
712 /* Returns the byte in position IDX in SS, as a value in the
713 range of unsigned char. Returns EOF if IDX is out of the
714 range of indexes for SS. */
716 ss_at (struct substring ss, size_t idx)
718 return idx < ss.length ? (unsigned char) ss.string[idx] : EOF;
721 /* Returns the first byte in SS as a value in the range of
722 unsigned char. Returns EOF if SS is the empty string. */
724 ss_first (struct substring ss)
726 return ss_at (ss, 0);
729 /* Returns the last byte in SS as a value in the range of
730 unsigned char. Returns EOF if SS is the empty string. */
732 ss_last (struct substring ss)
734 return ss.length > 0 ? (unsigned char) ss.string[ss.length - 1] : EOF;
737 /* Returns true if SS starts with PREFIX, false otherwise. */
739 ss_starts_with (struct substring ss, struct substring prefix)
741 return (ss.length >= prefix.length
742 && !memcmp (ss.string, prefix.string, prefix.length));
745 /* Returns true if SS ends with SUFFIX, false otherwise. */
747 ss_ends_with (struct substring ss, struct substring suffix)
749 return (ss.length >= suffix.length
750 && !memcmp (&ss.string[ss.length - suffix.length], suffix.string,
754 /* Returns the number of contiguous bytes at the beginning
755 of SS that are in SKIP_SET. */
757 ss_span (struct substring ss, struct substring skip_set)
760 for (i = 0; i < ss.length; i++)
761 if (ss_find_byte (skip_set, ss.string[i]) == SIZE_MAX)
766 /* Returns the number of contiguous bytes at the beginning
767 of SS that are not in SKIP_SET. */
769 ss_cspan (struct substring ss, struct substring stop_set)
772 for (i = 0; i < ss.length; i++)
773 if (ss_find_byte (stop_set, ss.string[i]) != SIZE_MAX)
778 /* Returns the offset in SS of the first instance of C,
779 or SIZE_MAX if C does not occur in SS. */
781 ss_find_byte (struct substring ss, char c)
783 const char *p = memchr (ss.string, (int) c, ss.length);
784 return p != NULL ? p - ss.string : SIZE_MAX;
787 /* Returns the offset in HAYSTACK of the first instance of NEEDLE,
788 or SIZE_MAX if NEEDLE does not occur in HAYSTACK. */
790 ss_find_substring (struct substring haystack, struct substring needle)
792 const char *p = memmem (haystack.string, haystack.length,
793 needle.string, needle.length);
794 return p != NULL ? p - haystack.string : SIZE_MAX;
797 /* Compares A and B and returns a strcmp()-type comparison
800 ss_compare (struct substring a, struct substring b)
802 int retval = memcmp (a.string, b.string, MIN (a.length, b.length));
804 retval = a.length < b.length ? -1 : a.length > b.length;
808 /* Compares A and B case-insensitively and returns a
809 strcmp()-type comparison result. */
811 ss_compare_case (struct substring a, struct substring b)
813 int retval = memcasecmp (a.string, b.string, MIN (a.length, b.length));
815 retval = a.length < b.length ? -1 : a.length > b.length;
819 /* Compares A and B and returns true if their contents are
820 identical, false otherwise. */
822 ss_equals (struct substring a, struct substring b)
824 return a.length == b.length && !memcmp (a.string, b.string, a.length);
827 /* Compares A and B and returns true if their contents are
828 identical except possibly for case differences, false
831 ss_equals_case (struct substring a, struct substring b)
833 return a.length == b.length && !memcasecmp (a.string, b.string, a.length);
836 /* Returns the position in SS that the byte at P occupies.
837 P must point within SS or one past its end. */
839 ss_pointer_to_position (struct substring ss, const char *p)
841 size_t pos = p - ss.string;
842 assert (pos <= ss.length);
846 /* Allocates and returns a null-terminated string that contains
849 ss_xstrdup (struct substring ss)
851 char *s = xmalloc (ss.length + 1);
852 memcpy (s, ss.string, ss.length);
858 /* Returns the character represented by the UTF-8 sequence at the start of S.
859 The return value is either a Unicode code point in the range 0 to 0x10ffff,
860 or UINT32_MAX if S is empty. */
862 ss_first_mb (struct substring s)
864 return ss_at_mb (s, 0);
867 /* Returns the number of bytes in the UTF-8 character at the beginning of S.
869 The return value is 0 if S is empty, otherwise between 1 and 4. */
871 ss_first_mblen (struct substring s)
873 return ss_at_mblen (s, 0);
876 /* Advances S past the UTF-8 character at its beginning. Returns the Unicode
877 code point that was skipped (in the range 0 to 0x10ffff), or UINT32_MAX if S
878 was not modified because it was initially empty. */
880 ss_get_mb (struct substring *s)
887 n = u8_mbtouc (&uc, CHAR_CAST (const uint8_t *, s->string), s->length);
896 /* Returns the character represented by the UTF-8 sequence starting OFS bytes
897 into S. The return value is either a Unicode code point in the range 0 to
898 0x10ffff, or UINT32_MAX if OFS is past the last byte in S.
900 (Returns 0xfffd if OFS points into the middle, not the beginning, of a UTF-8
903 ss_at_mb (struct substring s, size_t ofs)
908 u8_mbtouc (&uc, CHAR_CAST (const uint8_t *, s.string + ofs),
916 /* Returns the number of bytes represented by the UTF-8 sequence starting OFS
917 bytes into S. The return value is 0 if OFS is past the last byte in S,
918 otherwise between 1 and 4. */
920 ss_at_mblen (struct substring s, size_t ofs)
925 return u8_mbtouc (&uc, CHAR_CAST (const uint8_t *, s.string + ofs),
932 /* Initializes ST as an empty string. */
934 ds_init_empty (struct string *st)
936 st->ss = ss_empty ();
940 /* Initializes ST with initial contents S. */
942 ds_init_string (struct string *st, const struct string *s)
944 ds_init_substring (st, ds_ss (s));
947 /* Initializes ST with initial contents SS. */
949 ds_init_substring (struct string *st, struct substring ss)
951 st->capacity = MAX (8, ss.length * 2);
952 st->ss.string = xmalloc (st->capacity + 1);
953 memcpy (st->ss.string, ss.string, ss.length);
954 st->ss.length = ss.length;
957 /* Initializes ST with initial contents S. */
959 ds_init_cstr (struct string *st, const char *s)
961 ds_init_substring (st, ss_cstr (s));
966 ds_destroy (struct string *st)
970 ss_dealloc (&st->ss);
971 st->ss.string = NULL;
977 /* Swaps the contents of strings A and B. */
979 ds_swap (struct string *a, struct string *b)
981 struct string tmp = *a;
986 /* Helper function for ds_register_pool. */
988 free_string (void *st_)
990 struct string *st = st_;
994 /* Arranges for ST to be destroyed automatically as part of
997 ds_register_pool (struct string *st, struct pool *pool)
999 pool_register (pool, free_string, st);
1002 /* Cancels the arrangement for ST to be destroyed automatically
1005 ds_unregister_pool (struct string *st, struct pool *pool)
1007 pool_unregister (pool, st);
1010 /* Copies SRC into DST.
1011 DST and SRC may be the same string. */
1013 ds_assign_string (struct string *dst, const struct string *src)
1015 ds_assign_substring (dst, ds_ss (src));
1018 /* Replaces DST by SS.
1019 SS may be a substring of DST. */
1021 ds_assign_substring (struct string *dst, struct substring ss)
1023 dst->ss.length = ss.length;
1024 ds_extend (dst, ss.length);
1025 memmove (dst->ss.string, ss.string, ss.length);
1028 /* Replaces DST by null-terminated string SRC. SRC may overlap
1031 ds_assign_cstr (struct string *dst, const char *src)
1033 ds_assign_substring (dst, ss_cstr (src));
1036 /* Truncates ST to zero length. */
1038 ds_clear (struct string *st)
1043 /* Returns a substring that contains ST. */
1045 ds_ss (const struct string *st)
1050 /* Returns a substring that contains CNT bytes from ST
1051 starting at position START.
1053 If START is greater than or equal to the length of ST, then
1054 the substring will be the empty string. If START + CNT
1055 exceeds the length of ST, then the substring will only be
1056 ds_length(ST) - START bytes long. */
1058 ds_substr (const struct string *st, size_t start, size_t cnt)
1060 return ss_substr (ds_ss (st), start, cnt);
1063 /* Returns a substring that contains the first CNT bytes in
1064 ST. If CNT exceeds the length of ST, then the substring will
1065 contain all of ST. */
1067 ds_head (const struct string *st, size_t cnt)
1069 return ss_head (ds_ss (st), cnt);
1072 /* Returns a substring that contains the last CNT bytes in
1073 ST. If CNT exceeds the length of ST, then the substring will
1074 contain all of ST. */
1076 ds_tail (const struct string *st, size_t cnt)
1078 return ss_tail (ds_ss (st), cnt);
1081 /* Ensures that ST can hold at least MIN_CAPACITY bytes plus a null
1084 ds_extend (struct string *st, size_t min_capacity)
1086 if (min_capacity > st->capacity)
1089 if (st->capacity < min_capacity)
1090 st->capacity = 2 * min_capacity;
1092 st->ss.string = xrealloc (st->ss.string, st->capacity + 1);
1096 /* Shrink ST to the minimum capacity need to contain its content. */
1098 ds_shrink (struct string *st)
1100 if (st->capacity != st->ss.length)
1102 st->capacity = st->ss.length;
1103 st->ss.string = xrealloc (st->ss.string, st->capacity + 1);
1107 /* Truncates ST to at most LENGTH bytes long. */
1109 ds_truncate (struct string *st, size_t length)
1111 ss_truncate (&st->ss, length);
1114 /* Removes trailing bytes in TRIM_SET from ST.
1115 Returns number of bytes removed. */
1117 ds_rtrim (struct string *st, struct substring trim_set)
1119 return ss_rtrim (&st->ss, trim_set);
1122 /* Removes leading bytes in TRIM_SET from ST.
1123 Returns number of bytes removed. */
1125 ds_ltrim (struct string *st, struct substring trim_set)
1127 size_t cnt = ds_span (st, trim_set);
1129 ds_assign_substring (st, ds_substr (st, cnt, SIZE_MAX));
1133 /* Trims leading and trailing bytes in TRIM_SET from ST.
1134 Returns number of bytes removed. */
1136 ds_trim (struct string *st, struct substring trim_set)
1138 size_t cnt = ds_rtrim (st, trim_set);
1139 return cnt + ds_ltrim (st, trim_set);
1142 /* If the last byte in ST is C, removes it and returns true.
1143 Otherwise, returns false without modifying ST. */
1145 ds_chomp_byte (struct string *st, char c)
1147 return ss_chomp_byte (&st->ss, c);
1150 /* If ST ends with SUFFIX, removes it and returns true.
1151 Otherwise, returns false without modifying ST. */
1153 ds_chomp (struct string *st, struct substring suffix)
1155 return ss_chomp (&st->ss, suffix);
1158 /* Divides ST into tokens separated by any of the DELIMITERS.
1159 Each call replaces TOKEN by the next token in ST, or by an
1160 empty string if no tokens remain. Returns true if a token was
1161 obtained, false otherwise.
1163 Before the first call, initialize *SAVE_IDX to 0. Do not
1164 modify *SAVE_IDX between calls.
1166 ST divides into exactly one more tokens than it contains
1167 delimiters. That is, a delimiter at the start or end of ST or
1168 a pair of adjacent delimiters yields an empty token, and the
1169 empty string contains a single token. */
1171 ds_separate (const struct string *st, struct substring delimiters,
1172 size_t *save_idx, struct substring *token)
1174 return ss_separate (ds_ss (st), delimiters, save_idx, token);
1177 /* Divides ST into tokens separated by any of the DELIMITERS,
1178 merging adjacent delimiters so that the empty string is never
1179 produced as a token. Each call replaces TOKEN by the next
1180 token in ST, or by an empty string if no tokens remain.
1181 Returns true if a token was obtained, false otherwise.
1183 Before the first call, initialize *SAVE_IDX to 0. Do not
1184 modify *SAVE_IDX between calls. */
1186 ds_tokenize (const struct string *st, struct substring delimiters,
1187 size_t *save_idx, struct substring *token)
1189 return ss_tokenize (ds_ss (st), delimiters, save_idx, token);
1192 /* Pad ST on the right with copies of PAD until ST is at least
1193 LENGTH bytes in size. If ST is initially LENGTH
1194 bytes or longer, this is a no-op. */
1196 ds_rpad (struct string *st, size_t length, char pad)
1198 if (length > st->ss.length)
1199 ds_put_byte_multiple (st, pad, length - st->ss.length);
1202 /* Sets the length of ST to exactly NEW_LENGTH,
1203 either by truncating bytes from the end,
1204 or by padding on the right with PAD. */
1206 ds_set_length (struct string *st, size_t new_length, char pad)
1208 if (st->ss.length < new_length)
1209 ds_rpad (st, new_length, pad);
1211 st->ss.length = new_length;
1214 /* Removes N bytes from ST starting at offset START. */
1216 ds_remove (struct string *st, size_t start, size_t n)
1218 if (n > 0 && start < st->ss.length)
1220 if (st->ss.length - start <= n)
1222 /* All bytes at or beyond START are deleted. */
1223 st->ss.length = start;
1227 /* Some bytes remain and must be shifted into
1229 memmove (st->ss.string + st->ss.length,
1230 st->ss.string + st->ss.length + n,
1231 st->ss.length - start - n);
1237 /* There are no bytes to delete or no bytes at or
1238 beyond START, hence deletion is a no-op. */
1242 /* Returns true if ST is empty, false otherwise. */
1244 ds_is_empty (const struct string *st)
1246 return ss_is_empty (st->ss);
1249 /* Returns the length of ST. */
1251 ds_length (const struct string *st)
1253 return ss_length (ds_ss (st));
1256 /* Returns the string data inside ST. */
1258 ds_data (const struct string *st)
1260 return ss_data (ds_ss (st));
1263 /* Returns a pointer to the null terminator ST.
1264 This might not be an actual null byte unless ds_c_str() has
1265 been called since the last modification to ST. */
1267 ds_end (const struct string *st)
1269 return ss_end (ds_ss (st));
1272 /* Returns the byte in position IDX in ST, as a value in the
1273 range of unsigned char. Returns EOF if IDX is out of the
1274 range of indexes for ST. */
1276 ds_at (const struct string *st, size_t idx)
1278 return ss_at (ds_ss (st), idx);
1281 /* Returns the first byte in ST as a value in the range of
1282 unsigned char. Returns EOF if ST is the empty string. */
1284 ds_first (const struct string *st)
1286 return ss_first (ds_ss (st));
1289 /* Returns the last byte in ST as a value in the range of
1290 unsigned char. Returns EOF if ST is the empty string. */
1292 ds_last (const struct string *st)
1294 return ss_last (ds_ss (st));
1297 /* Returns true if ST ends with SUFFIX, false otherwise. */
1299 ds_ends_with (const struct string *st, struct substring suffix)
1301 return ss_ends_with (st->ss, suffix);
1304 /* Returns the number of consecutive bytes at the beginning
1305 of ST that are in SKIP_SET. */
1307 ds_span (const struct string *st, struct substring skip_set)
1309 return ss_span (ds_ss (st), skip_set);
1312 /* Returns the number of consecutive bytes at the beginning
1313 of ST that are not in STOP_SET. */
1315 ds_cspan (const struct string *st, struct substring stop_set)
1317 return ss_cspan (ds_ss (st), stop_set);
1320 /* Returns the position of the first occurrence of byte C in
1321 ST at or after position OFS, or SIZE_MAX if there is no such
1324 ds_find_byte (const struct string *st, char c)
1326 return ss_find_byte (ds_ss (st), c);
1329 /* Compares A and B and returns a strcmp()-type comparison
1332 ds_compare (const struct string *a, const struct string *b)
1334 return ss_compare (ds_ss (a), ds_ss (b));
1337 /* Returns the position in ST that the byte at P occupies.
1338 P must point within ST or one past its end. */
1340 ds_pointer_to_position (const struct string *st, const char *p)
1342 return ss_pointer_to_position (ds_ss (st), p);
1345 /* Allocates and returns a null-terminated string that contains
1348 ds_xstrdup (const struct string *st)
1350 return ss_xstrdup (ds_ss (st));
1353 /* Returns the allocation size of ST. */
1355 ds_capacity (const struct string *st)
1357 return st->capacity;
1360 /* Returns the value of ST as a null-terminated string. */
1362 ds_cstr (const struct string *st_)
1364 struct string *st = CONST_CAST (struct string *, st_);
1365 if (st->ss.string == NULL)
1367 st->ss.string[st->ss.length] = '\0';
1368 return st->ss.string;
1371 /* Returns the value of ST as a null-terminated string and then
1372 reinitialized ST as an empty string. The caller must free the
1373 returned string with free(). */
1375 ds_steal_cstr (struct string *st)
1377 char *s = ds_cstr (st);
1382 /* Reads bytes from STREAM and appends them to ST, stopping
1383 after MAX_LENGTH bytes, after appending a newline, or
1384 after an I/O error or end of file was encountered, whichever
1385 comes first. Returns true if at least one byte was added
1386 to ST, false if no bytes were read before an I/O error or
1387 end of file (or if MAX_LENGTH was 0).
1389 This function treats LF and CR LF sequences as new-line,
1390 translating each of them to a single '\n' in ST. */
1392 ds_read_line (struct string *st, FILE *stream, size_t max_length)
1396 for (length = 0; length < max_length; length++)
1398 int c = getc (stream);
1405 ds_put_byte (st, c);
1412 /* CR followed by LF is special: translate to \n. */
1413 ds_put_byte (st, '\n');
1418 /* CR followed by anything else is just CR. */
1419 ds_put_byte (st, '\r');
1427 ds_put_byte (st, c);
1434 /* Removes a comment introduced by `#' from ST,
1435 ignoring occurrences inside quoted strings. */
1437 remove_comment (struct string *st)
1442 for (cp = ds_data (st); cp < ds_end (st); cp++)
1447 else if (*cp == '\\')
1450 else if (*cp == '\'' || *cp == '"')
1452 else if (*cp == '#')
1454 ds_truncate (st, cp - ds_cstr (st));
1459 /* Reads a line from STREAM into ST, then preprocesses as follows:
1461 - Splices lines terminated with `\'.
1463 - Deletes comments introduced by `#' outside of single or double
1466 - Deletes trailing white space.
1468 Returns true if a line was successfully read, false on
1469 failure. If LINE_NUMBER is non-null, then *LINE_NUMBER is
1470 incremented by the number of lines read. */
1472 ds_read_config_line (struct string *st, int *line_number, FILE *stream)
1477 if (!ds_read_line (st, stream, SIZE_MAX))
1480 ds_rtrim (st, ss_cstr (CC_SPACES));
1482 while (ds_chomp_byte (st, '\\'));
1484 remove_comment (st);
1488 /* Attempts to read SIZE * CNT bytes from STREAM and append them
1490 Returns true if all the requested data was read, false otherwise. */
1492 ds_read_stream (struct string *st, size_t size, size_t cnt, FILE *stream)
1496 size_t try_bytes = xtimes (cnt, size);
1497 if (size_in_bounds_p (xsum (ds_length (st), try_bytes)))
1499 char *buffer = ds_put_uninit (st, try_bytes);
1500 size_t got_bytes = fread (buffer, 1, try_bytes, stream);
1501 ds_truncate (st, ds_length (st) - (try_bytes - got_bytes));
1502 return got_bytes == try_bytes;
1514 /* Concatenates S onto ST. */
1516 ds_put_cstr (struct string *st, const char *s)
1519 ds_put_substring (st, ss_cstr (s));
1522 /* Concatenates SS to ST. */
1524 ds_put_substring (struct string *st, struct substring ss)
1527 memcpy (ds_put_uninit (st, ss_length (ss)), ss_data (ss), ss_length (ss));
1530 /* Returns ds_end(ST) and THEN increases the length by INCR. */
1532 ds_put_uninit (struct string *st, size_t incr)
1535 ds_extend (st, ds_length (st) + incr);
1537 st->ss.length += incr;
1541 /* Moves the bytes in ST following offset OFS + OLD_LEN in ST to offset OFS +
1542 NEW_LEN and returns the byte at offset OFS. The first min(OLD_LEN, NEW_LEN)
1543 bytes at the returned position are unchanged; if NEW_LEN > OLD_LEN then the
1544 following NEW_LEN - OLD_LEN bytes are initially indeterminate.
1546 The intention is that the caller should write NEW_LEN bytes at the returned
1547 position, to effectively replace the OLD_LEN bytes previously at that
1550 ds_splice_uninit (struct string *st,
1551 size_t ofs, size_t old_len, size_t new_len)
1553 if (new_len != old_len)
1555 if (new_len > old_len)
1556 ds_extend (st, ds_length (st) + (new_len - old_len));
1558 assert (ds_length (st) >= ofs + old_len);
1560 memmove (ds_data (st) + (ofs + new_len),
1561 ds_data (st) + (ofs + old_len),
1562 ds_length (st) - (ofs + old_len));
1563 st->ss.length += new_len - old_len;
1565 return ds_data (st) + ofs;
1568 /* Formats FORMAT as a printf string and appends the result to ST. */
1570 ds_put_format (struct string *st, const char *format, ...)
1574 va_start (args, format);
1575 ds_put_vformat (st, format, args);
1579 /* Formats FORMAT as a printf string as if in the C locale and appends the result to ST. */
1581 ds_put_c_format (struct string *st, const char *format, ...)
1585 va_start (args, format);
1586 ds_put_c_vformat (st, format, args);
1590 /* Formats FORMAT as a printf string and appends the result to ST. */
1592 ds_put_vformat (struct string *st, const char *format, va_list args_)
1597 va_copy (args, args_);
1598 avail = st->ss.string != NULL ? st->capacity - st->ss.length + 1 : 0;
1599 needed = vsnprintf (st->ss.string + st->ss.length, avail, format, args);
1602 if (needed >= avail)
1604 va_copy (args, args_);
1605 vsnprintf (ds_put_uninit (st, needed), needed + 1, format, args);
1610 /* Some old libc's returned -1 when the destination string
1612 while (needed == -1)
1614 ds_extend (st, (st->capacity + 1) * 2);
1615 avail = st->capacity - st->ss.length + 1;
1617 va_copy (args, args_);
1618 needed = vsnprintf (ds_end (st), avail, format, args);
1621 st->ss.length += needed;
1625 /* Formats FORMAT as a printf string, as if in the C locale,
1626 and appends the result to ST. */
1628 ds_put_c_vformat (struct string *st, const char *format, va_list args)
1631 size_t len = sizeof buf;
1632 char *output = c_vasnprintf (buf, &len, format, args);
1635 ds_put_cstr (st, output);
1641 /* Appends byte CH to ST. */
1643 ds_put_byte (struct string *st, int ch)
1645 ds_put_uninit (st, 1)[0] = ch;
1648 /* Appends CNT copies of byte CH to ST. */
1650 ds_put_byte_multiple (struct string *st, int ch, size_t cnt)
1652 memset (ds_put_uninit (st, cnt), ch, cnt);
1655 /* Appends Unicode code point UC to ST in UTF-8 encoding. */
1657 ds_put_unichar (struct string *st, ucs4_t uc)
1659 ds_extend (st, ds_length (st) + 6);
1660 st->ss.length += u8_uctomb (CHAR_CAST (uint8_t *, ds_end (st)), uc, 6);
1663 /* If relocation has been enabled, replace ST,
1664 with its relocated version */
1666 ds_relocate (struct string *st)
1668 const char *orig = ds_cstr (st);
1669 const char *rel = relocate (orig);
1674 ds_put_cstr (st, rel);
1675 /* The documentation for relocate says that casting away const
1676 and then freeing is appropriate ... */
1677 free (CONST_CAST (char *, rel));
1684 /* Operations on uint8_t "strings" */
1686 /* Copies buffer SRC, of SRC_SIZE bytes, to DST, of DST_SIZE bytes.
1687 DST is truncated to DST_SIZE bytes or padded on the right with
1688 copies of PAD as needed. */
1690 u8_buf_copy_rpad (uint8_t *dst, size_t dst_size,
1691 const uint8_t *src, size_t src_size,
1694 if (src_size >= dst_size)
1695 memmove (dst, src, dst_size);
1698 memmove (dst, src, src_size);
1699 memset (&dst[src_size], pad, dst_size - src_size);