1 /* PSPP - a program for statistical analysis.
2 Copyright (C) 1997-9, 2000, 2006, 2009, 2010, 2011, 2012 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/c-vasnprintf.h"
32 #include "gl/relocatable.h"
33 #include "gl/minmax.h"
34 #include "gl/xalloc.h"
35 #include "gl/xmemdup0.h"
38 /* Reverses the order of NBYTES bytes at address P, thus converting
39 between little- and big-endian byte orders. */
41 buf_reverse (char *p, size_t nbytes)
43 char *h = p, *t = &h[nbytes - 1];
55 /* Compares the SIZE bytes in A to those in B, disregarding case,
56 and returns a strcmp()-type result. */
58 buf_compare_case (const char *a_, const char *b_, size_t size)
60 const unsigned char *a = (unsigned char *) a_;
61 const unsigned char *b = (unsigned char *) b_;
65 unsigned char ac = toupper (*a++);
66 unsigned char bc = toupper (*b++);
69 return ac > bc ? 1 : -1;
75 /* Compares A of length A_LEN to B of length B_LEN. The shorter
76 string is considered to be padded with spaces to the length of
79 buf_compare_rpad (const char *a, size_t a_len, const char *b, size_t b_len)
84 min_len = a_len < b_len ? a_len : b_len;
85 result = memcmp (a, b, min_len);
94 for (idx = min_len; idx < b_len; idx++)
96 return ' ' > b[idx] ? 1 : -1;
100 for (idx = min_len; idx < a_len; idx++)
102 return a[idx] > ' ' ? 1 : -1;
108 /* Compares strin A to string B. The shorter string is
109 considered to be padded with spaces to the length of the
112 str_compare_rpad (const char *a, const char *b)
114 return buf_compare_rpad (a, strlen (a), b, strlen (b));
117 /* Copies string SRC to buffer DST, of size DST_SIZE bytes.
118 DST is truncated to DST_SIZE bytes or padded on the right with
119 copies of PAD as needed. */
121 buf_copy_str_rpad (char *dst, size_t dst_size, const char *src, char pad)
123 size_t src_len = strlen (src);
124 if (src_len >= dst_size)
125 memcpy (dst, src, dst_size);
128 memcpy (dst, src, src_len);
129 memset (&dst[src_len], pad, dst_size - src_len);
133 /* Copies string SRC to buffer DST, of size DST_SIZE bytes.
134 DST is truncated to DST_SIZE bytes or padded on the left with
135 copies of PAD as needed. */
137 buf_copy_str_lpad (char *dst, size_t dst_size, const char *src, char pad)
139 size_t src_len = strlen (src);
140 if (src_len >= dst_size)
141 memcpy (dst, src, dst_size);
144 size_t pad_cnt = dst_size - src_len;
145 memset (&dst[0], pad, pad_cnt);
146 memcpy (dst + pad_cnt, src, src_len);
150 /* Copies buffer SRC, of SRC_SIZE bytes, to DST, of DST_SIZE bytes.
151 DST is truncated to DST_SIZE bytes or padded on the left with
152 copies of PAD as needed. */
154 buf_copy_lpad (char *dst, size_t dst_size,
155 const char *src, size_t src_size,
158 if (src_size >= dst_size)
159 memmove (dst, src, dst_size);
162 memset (dst, pad, dst_size - src_size);
163 memmove (&dst[dst_size - src_size], src, src_size);
167 /* Copies buffer SRC, of SRC_SIZE bytes, to DST, of DST_SIZE bytes.
168 DST is truncated to DST_SIZE bytes or padded on the right with
169 copies of PAD as needed. */
171 buf_copy_rpad (char *dst, size_t dst_size,
172 const char *src, size_t src_size,
175 if (src_size >= dst_size)
176 memmove (dst, src, dst_size);
179 memmove (dst, src, src_size);
180 memset (&dst[src_size], pad, dst_size - src_size);
184 /* Copies string SRC to string DST, which is in a buffer DST_SIZE
186 Truncates DST to DST_SIZE - 1 bytes or right-pads with
187 spaces to DST_SIZE - 1 bytes if necessary. */
189 str_copy_rpad (char *dst, size_t dst_size, const char *src)
193 size_t src_len = strlen (src);
194 if (src_len < dst_size - 1)
196 memcpy (dst, src, src_len);
197 memset (&dst[src_len], ' ', dst_size - 1 - src_len);
200 memcpy (dst, src, dst_size - 1);
201 dst[dst_size - 1] = 0;
205 /* Copies SRC to DST, which is in a buffer DST_SIZE bytes long.
206 Truncates DST to DST_SIZE - 1 bytes, if necessary. */
208 str_copy_trunc (char *dst, size_t dst_size, const char *src)
210 size_t src_len = strlen (src);
211 assert (dst_size > 0);
212 if (src_len + 1 < dst_size)
213 memcpy (dst, src, src_len + 1);
216 memcpy (dst, src, dst_size - 1);
217 dst[dst_size - 1] = '\0';
221 /* Copies buffer SRC, of SRC_LEN bytes,
222 to DST, which is in a buffer DST_SIZE bytes long.
223 Truncates DST to DST_SIZE - 1 bytes, if necessary. */
225 str_copy_buf_trunc (char *dst, size_t dst_size,
226 const char *src, size_t src_size)
229 assert (dst_size > 0);
231 dst_len = src_size < dst_size ? src_size : dst_size - 1;
232 memcpy (dst, src, dst_len);
236 /* Converts each byte in S to uppercase. */
238 str_uppercase (char *s)
240 for (; *s != '\0'; s++)
241 *s = toupper ((unsigned char) *s);
244 /* Converts each byte in S to lowercase. */
246 str_lowercase (char *s)
248 for (; *s != '\0'; s++)
249 *s = tolower ((unsigned char) *s);
252 /* Converts NUMBER into a string in 26-adic notation in BUFFER,
253 which has room for SIZE bytes. Returns true if successful,
254 false if NUMBER, plus a trailing null, is too large to fit in
257 26-adic notation is "spreadsheet column numbering": 1 = A, 2 =
258 B, 3 = C, ... 26 = Z, 27 = AA, 28 = AB, 29 = AC, ...
260 26-adic notation is the special case of a k-adic numeration
261 system (aka bijective base-k numeration) with k=26. In k-adic
262 numeration, the digits are {1, 2, 3, ..., k} (there is no
263 digit 0), and integer 0 is represented by the empty string.
264 For more information, see
265 http://en.wikipedia.org/wiki/Bijective_numeration. */
267 str_format_26adic (unsigned long int number, char buffer[], size_t size)
275 buffer[length++] = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"[number % 26];
281 buffer[length] = '\0';
283 buf_reverse (buffer, length);
292 /* Sets the SIZE bytes starting at BLOCK to C,
293 and returns the byte following BLOCK. */
295 mempset (void *block, int c, size_t size)
297 memset (block, c, size);
298 return (char *) block + size;
303 /* Returns a substring whose contents are the CNT bytes
304 starting at the (0-based) position START in SS. */
306 ss_substr (struct substring ss, size_t start, size_t cnt)
308 if (start < ss.length)
309 return ss_buffer (ss.string + start, MIN (cnt, ss.length - start));
311 return ss_buffer (ss.string + ss.length, 0);
314 /* Returns a substring whose contents are the first CNT
317 ss_head (struct substring ss, size_t cnt)
319 return ss_buffer (ss.string, MIN (cnt, ss.length));
322 /* Returns a substring whose contents are the last CNT bytes
325 ss_tail (struct substring ss, size_t cnt)
328 return ss_buffer (ss.string + (ss.length - cnt), cnt);
333 /* Makes a malloc()'d, null-terminated copy of the contents of OLD
334 and stores it in NEW. */
336 ss_alloc_substring (struct substring *new, struct substring old)
338 new->string = xmemdup0 (old.string, old.length);
339 new->length = old.length;
342 /* Allocates room for a CNT-byte string in NEW. */
344 ss_alloc_uninit (struct substring *new, size_t cnt)
346 new->string = xmalloc (cnt);
351 ss_realloc (struct substring *ss, size_t size)
353 ss->string = xrealloc (ss->string, size);
356 /* Makes a pool_alloc_unaligned()'d, null-terminated copy of the contents of
357 OLD in POOL, and stores it in NEW. */
359 ss_alloc_substring_pool (struct substring *new, struct substring old,
362 new->string = pool_alloc_unaligned (pool, old.length + 1);
363 new->length = old.length;
364 memcpy (new->string, old.string, old.length);
365 new->string[old.length] = '\0';
368 /* Allocates room for a CNT-byte string in NEW in POOL. */
370 ss_alloc_uninit_pool (struct substring *new, size_t cnt, struct pool *pool)
372 new->string = pool_alloc_unaligned (pool, cnt);
376 /* Frees the string that SS points to. */
378 ss_dealloc (struct substring *ss)
383 /* Truncates SS to at most CNT bytes in length. */
385 ss_truncate (struct substring *ss, size_t cnt)
387 if (ss->length > cnt)
391 /* Removes trailing bytes in TRIM_SET from SS.
392 Returns number of bytes removed. */
394 ss_rtrim (struct substring *ss, struct substring trim_set)
397 while (cnt < ss->length
398 && ss_find_byte (trim_set,
399 ss->string[ss->length - cnt - 1]) != SIZE_MAX)
405 /* Removes leading bytes in TRIM_SET from SS.
406 Returns number of bytes removed. */
408 ss_ltrim (struct substring *ss, struct substring trim_set)
410 size_t cnt = ss_span (*ss, trim_set);
411 ss_advance (ss, cnt);
415 /* Trims leading and trailing bytes in TRIM_SET from SS. */
417 ss_trim (struct substring *ss, struct substring trim_set)
419 ss_ltrim (ss, trim_set);
420 ss_rtrim (ss, trim_set);
423 /* If the last byte in SS is C, removes it and returns true.
424 Otherwise, returns false without changing the string. */
426 ss_chomp_byte (struct substring *ss, char c)
428 if (ss_last (*ss) == c)
437 /* If SS ends with SUFFIX, removes it and returns true.
438 Otherwise, returns false without changing the string. */
440 ss_chomp (struct substring *ss, struct substring suffix)
442 if (ss_ends_with (*ss, suffix))
444 ss->length -= suffix.length;
451 /* Divides SS into tokens separated by any of the DELIMITERS.
452 Each call replaces TOKEN by the next token in SS, or by an
453 empty string if no tokens remain. Returns true if a token was
454 obtained, false otherwise.
456 Before the first call, initialize *SAVE_IDX to 0. Do not
457 modify *SAVE_IDX between calls.
459 SS divides into exactly one more tokens than it contains
460 delimiters. That is, a delimiter at the start or end of SS or
461 a pair of adjacent delimiters yields an empty token, and the
462 empty string contains a single token. */
464 ss_separate (struct substring ss, struct substring delimiters,
465 size_t *save_idx, struct substring *token)
467 if (*save_idx <= ss_length (ss))
469 struct substring tmp = ss_substr (ss, *save_idx, SIZE_MAX);
470 size_t length = ss_cspan (tmp, delimiters);
471 *token = ss_head (tmp, length);
472 *save_idx += length + 1;
477 *token = ss_empty ();
482 /* Divides SS into tokens separated by any of the DELIMITERS,
483 merging adjacent delimiters so that the empty string is never
484 produced as a token. Each call replaces TOKEN by the next
485 token in SS, or by an empty string if no tokens remain, and
486 then skips past the first delimiter following the token.
487 Returns true if a token was obtained, false otherwise.
489 Before the first call, initialize *SAVE_IDX to 0. Do not
490 modify *SAVE_IDX between calls. */
492 ss_tokenize (struct substring ss, struct substring delimiters,
493 size_t *save_idx, struct substring *token)
497 ss_advance (&ss, *save_idx);
498 *save_idx += ss_ltrim (&ss, delimiters);
499 ss_get_bytes (&ss, ss_cspan (ss, delimiters), token);
501 found_token = ss_length (*token) > 0;
502 *save_idx += ss_length (*token) + found_token;
506 /* Removes the first CNT bytes from SS. */
508 ss_advance (struct substring *ss, size_t cnt)
510 if (cnt > ss->length)
516 /* If the first byte in SS is C, removes it and returns true.
517 Otherwise, returns false without changing the string. */
519 ss_match_byte (struct substring *ss, char c)
521 if (ss_first (*ss) == c)
531 /* If the first byte in SS is in MATCH, removes it and
532 returns the byte that was removed.
533 Otherwise, returns EOF without changing the string. */
535 ss_match_byte_in (struct substring *ss, struct substring match)
539 && memchr (match.string, ss->string[0], match.length) != NULL)
548 /* If SS begins with TARGET, removes it and returns true.
549 Otherwise, returns false without changing SS. */
551 ss_match_string (struct substring *ss, const struct substring target)
553 size_t length = ss_length (target);
554 if (ss_equals (ss_head (*ss, length), target))
556 ss_advance (ss, length);
563 /* Removes the first byte from SS and returns it.
564 If SS is empty, returns EOF without modifying SS. */
566 ss_get_byte (struct substring *ss)
568 int c = ss_first (*ss);
577 /* Stores the prefix of SS up to the first DELIMITER in OUT (if
578 any). Trims those same bytes from SS. DELIMITER is
579 removed from SS but not made part of OUT. Returns true if
580 DELIMITER was found (and removed), false otherwise. */
582 ss_get_until (struct substring *ss, char delimiter, struct substring *out)
584 ss_get_bytes (ss, ss_cspan (*ss, ss_buffer (&delimiter, 1)), out);
585 return ss_match_byte (ss, delimiter);
588 /* Stores the first CNT bytes in SS in OUT (or fewer, if SS
589 is shorter than CNT bytes). Trims the same bytes
590 from the beginning of SS. Returns CNT. */
592 ss_get_bytes (struct substring *ss, size_t cnt, struct substring *out)
594 *out = ss_head (*ss, cnt);
595 ss_advance (ss, cnt);
599 /* Parses and removes an optionally signed decimal integer from
600 the beginning of SS. Returns 0 if an error occurred,
601 otherwise the number of bytes removed from SS. Stores
602 the integer's value into *VALUE. */
604 ss_get_long (struct substring *ss, long *value)
609 length = ss_span (*ss, ss_cstr ("+-"));
610 length += ss_span (ss_substr (*ss, length, SIZE_MAX), ss_cstr (CC_DIGITS));
611 if (length > 0 && length < sizeof tmp)
615 memcpy (tmp, ss_data (*ss), length);
618 *value = strtol (tmp, &tail, 10);
619 if (tail - tmp == length)
621 ss_advance (ss, length);
629 /* Returns true if SS is empty (has length 0 bytes),
632 ss_is_empty (struct substring ss)
634 return ss.length == 0;
637 /* Returns the number of bytes in SS. */
639 ss_length (struct substring ss)
644 /* Returns a pointer to the bytes in SS. */
646 ss_data (struct substring ss)
651 /* Returns a pointer just past the last byte in SS. */
653 ss_end (struct substring ss)
655 return ss.string + ss.length;
658 /* Returns the byte in position IDX in SS, as a value in the
659 range of unsigned char. Returns EOF if IDX is out of the
660 range of indexes for SS. */
662 ss_at (struct substring ss, size_t idx)
664 return idx < ss.length ? (unsigned char) ss.string[idx] : EOF;
667 /* Returns the first byte in SS as a value in the range of
668 unsigned char. Returns EOF if SS is the empty string. */
670 ss_first (struct substring ss)
672 return ss_at (ss, 0);
675 /* Returns the last byte in SS as a value in the range of
676 unsigned char. Returns EOF if SS is the empty string. */
678 ss_last (struct substring ss)
680 return ss.length > 0 ? (unsigned char) ss.string[ss.length - 1] : EOF;
683 /* Returns true if SS ends with SUFFIX, false otherwise. */
685 ss_ends_with (struct substring ss, struct substring suffix)
687 return (ss.length >= suffix.length
688 && !memcmp (&ss.string[ss.length - suffix.length], suffix.string,
692 /* Returns the number of contiguous bytes at the beginning
693 of SS that are in SKIP_SET. */
695 ss_span (struct substring ss, struct substring skip_set)
698 for (i = 0; i < ss.length; i++)
699 if (ss_find_byte (skip_set, ss.string[i]) == SIZE_MAX)
704 /* Returns the number of contiguous bytes at the beginning
705 of SS that are not in SKIP_SET. */
707 ss_cspan (struct substring ss, struct substring stop_set)
710 for (i = 0; i < ss.length; i++)
711 if (ss_find_byte (stop_set, ss.string[i]) != SIZE_MAX)
716 /* Returns the offset in SS of the first instance of C,
717 or SIZE_MAX if C does not occur in SS. */
719 ss_find_byte (struct substring ss, char c)
721 const char *p = memchr (ss.string, c, ss.length);
722 return p != NULL ? p - ss.string : SIZE_MAX;
725 /* Compares A and B and returns a strcmp()-type comparison
728 ss_compare (struct substring a, struct substring b)
730 int retval = memcmp (a.string, b.string, MIN (a.length, b.length));
732 retval = a.length < b.length ? -1 : a.length > b.length;
736 /* Compares A and B case-insensitively and returns a
737 strcmp()-type comparison result. */
739 ss_compare_case (struct substring a, struct substring b)
741 int retval = memcasecmp (a.string, b.string, MIN (a.length, b.length));
743 retval = a.length < b.length ? -1 : a.length > b.length;
747 /* Compares A and B and returns true if their contents are
748 identical, false otherwise. */
750 ss_equals (struct substring a, struct substring b)
752 return a.length == b.length && !memcmp (a.string, b.string, a.length);
755 /* Compares A and B and returns true if their contents are
756 identical except possibly for case differences, false
759 ss_equals_case (struct substring a, struct substring b)
761 return a.length == b.length && !memcasecmp (a.string, b.string, a.length);
764 /* Returns the position in SS that the byte at P occupies.
765 P must point within SS or one past its end. */
767 ss_pointer_to_position (struct substring ss, const char *p)
769 size_t pos = p - ss.string;
770 assert (pos <= ss.length);
774 /* Allocates and returns a null-terminated string that contains
777 ss_xstrdup (struct substring ss)
779 char *s = xmalloc (ss.length + 1);
780 memcpy (s, ss.string, ss.length);
786 /* Returns the character represented by the UTF-8 sequence at the start of S.
787 The return value is either a Unicode code point in the range 0 to 0x10ffff,
788 or UINT32_MAX if S is empty. */
790 ss_first_mb (struct substring s)
792 return ss_at_mb (s, 0);
795 /* Returns the number of bytes in the UTF-8 character at the beginning of S.
797 The return value is 0 if S is empty, otherwise between 1 and 4. */
799 ss_first_mblen (struct substring s)
801 return ss_at_mblen (s, 0);
804 /* Advances S past the UTF-8 character at its beginning. Returns the Unicode
805 code point that was skipped (in the range 0 to 0x10ffff), or UINT32_MAX if S
806 was not modified because it was initially empty. */
808 ss_get_mb (struct substring *s)
815 n = u8_mbtouc (&uc, CHAR_CAST (const uint8_t *, s->string), s->length);
824 /* Returns the character represented by the UTF-8 sequence starting OFS bytes
825 into S. The return value is either a Unicode code point in the range 0 to
826 0x10ffff, or UINT32_MAX if OFS is past the last byte in S.
828 (Returns 0xfffd if OFS points into the middle, not the beginning, of a UTF-8
831 ss_at_mb (struct substring s, size_t ofs)
836 u8_mbtouc (&uc, CHAR_CAST (const uint8_t *, s.string + ofs),
844 /* Returns the number of bytes represented by the UTF-8 sequence starting OFS
845 bytes into S. The return value is 0 if OFS is past the last byte in S,
846 otherwise between 1 and 4. */
848 ss_at_mblen (struct substring s, size_t ofs)
853 return u8_mbtouc (&uc, CHAR_CAST (const uint8_t *, s.string + ofs),
860 /* Initializes ST as an empty string. */
862 ds_init_empty (struct string *st)
864 st->ss = ss_empty ();
868 /* Initializes ST with initial contents S. */
870 ds_init_string (struct string *st, const struct string *s)
872 ds_init_substring (st, ds_ss (s));
875 /* Initializes ST with initial contents SS. */
877 ds_init_substring (struct string *st, struct substring ss)
879 st->capacity = MAX (8, ss.length * 2);
880 st->ss.string = xmalloc (st->capacity + 1);
881 memcpy (st->ss.string, ss.string, ss.length);
882 st->ss.length = ss.length;
885 /* Initializes ST with initial contents S. */
887 ds_init_cstr (struct string *st, const char *s)
889 ds_init_substring (st, ss_cstr (s));
894 ds_destroy (struct string *st)
898 ss_dealloc (&st->ss);
899 st->ss.string = NULL;
905 /* Swaps the contents of strings A and B. */
907 ds_swap (struct string *a, struct string *b)
909 struct string tmp = *a;
914 /* Helper function for ds_register_pool. */
916 free_string (void *st_)
918 struct string *st = st_;
922 /* Arranges for ST to be destroyed automatically as part of
925 ds_register_pool (struct string *st, struct pool *pool)
927 pool_register (pool, free_string, st);
930 /* Cancels the arrangement for ST to be destroyed automatically
933 ds_unregister_pool (struct string *st, struct pool *pool)
935 pool_unregister (pool, st);
938 /* Copies SRC into DST.
939 DST and SRC may be the same string. */
941 ds_assign_string (struct string *dst, const struct string *src)
943 ds_assign_substring (dst, ds_ss (src));
946 /* Replaces DST by SS.
947 SS may be a substring of DST. */
949 ds_assign_substring (struct string *dst, struct substring ss)
951 dst->ss.length = ss.length;
952 ds_extend (dst, ss.length);
953 memmove (dst->ss.string, ss.string, ss.length);
956 /* Replaces DST by null-terminated string SRC. SRC may overlap
959 ds_assign_cstr (struct string *dst, const char *src)
961 ds_assign_substring (dst, ss_cstr (src));
964 /* Truncates ST to zero length. */
966 ds_clear (struct string *st)
971 /* Returns a substring that contains ST. */
973 ds_ss (const struct string *st)
978 /* Returns a substring that contains CNT bytes from ST
979 starting at position START.
981 If START is greater than or equal to the length of ST, then
982 the substring will be the empty string. If START + CNT
983 exceeds the length of ST, then the substring will only be
984 ds_length(ST) - START bytes long. */
986 ds_substr (const struct string *st, size_t start, size_t cnt)
988 return ss_substr (ds_ss (st), start, cnt);
991 /* Returns a substring that contains the first CNT bytes in
992 ST. If CNT exceeds the length of ST, then the substring will
993 contain all of ST. */
995 ds_head (const struct string *st, size_t cnt)
997 return ss_head (ds_ss (st), cnt);
1000 /* Returns a substring that contains the last CNT bytes in
1001 ST. If CNT exceeds the length of ST, then the substring will
1002 contain all of ST. */
1004 ds_tail (const struct string *st, size_t cnt)
1006 return ss_tail (ds_ss (st), cnt);
1009 /* Ensures that ST can hold at least MIN_CAPACITY bytes plus a null
1012 ds_extend (struct string *st, size_t min_capacity)
1014 if (min_capacity > st->capacity)
1017 if (st->capacity < min_capacity)
1018 st->capacity = 2 * min_capacity;
1020 st->ss.string = xrealloc (st->ss.string, st->capacity + 1);
1024 /* Shrink ST to the minimum capacity need to contain its content. */
1026 ds_shrink (struct string *st)
1028 if (st->capacity != st->ss.length)
1030 st->capacity = st->ss.length;
1031 st->ss.string = xrealloc (st->ss.string, st->capacity + 1);
1035 /* Truncates ST to at most LENGTH bytes long. */
1037 ds_truncate (struct string *st, size_t length)
1039 ss_truncate (&st->ss, length);
1042 /* Removes trailing bytes in TRIM_SET from ST.
1043 Returns number of bytes removed. */
1045 ds_rtrim (struct string *st, struct substring trim_set)
1047 return ss_rtrim (&st->ss, trim_set);
1050 /* Removes leading bytes in TRIM_SET from ST.
1051 Returns number of bytes removed. */
1053 ds_ltrim (struct string *st, struct substring trim_set)
1055 size_t cnt = ds_span (st, trim_set);
1057 ds_assign_substring (st, ds_substr (st, cnt, SIZE_MAX));
1061 /* Trims leading and trailing bytes in TRIM_SET from ST.
1062 Returns number of bytes removed. */
1064 ds_trim (struct string *st, struct substring trim_set)
1066 size_t cnt = ds_rtrim (st, trim_set);
1067 return cnt + ds_ltrim (st, trim_set);
1070 /* If the last byte in ST is C, removes it and returns true.
1071 Otherwise, returns false without modifying ST. */
1073 ds_chomp_byte (struct string *st, char c)
1075 return ss_chomp_byte (&st->ss, c);
1078 /* If ST ends with SUFFIX, removes it and returns true.
1079 Otherwise, returns false without modifying ST. */
1081 ds_chomp (struct string *st, struct substring suffix)
1083 return ss_chomp (&st->ss, suffix);
1086 /* Divides ST into tokens separated by any of the DELIMITERS.
1087 Each call replaces TOKEN by the next token in ST, or by an
1088 empty string if no tokens remain. Returns true if a token was
1089 obtained, false otherwise.
1091 Before the first call, initialize *SAVE_IDX to 0. Do not
1092 modify *SAVE_IDX between calls.
1094 ST divides into exactly one more tokens than it contains
1095 delimiters. That is, a delimiter at the start or end of ST or
1096 a pair of adjacent delimiters yields an empty token, and the
1097 empty string contains a single token. */
1099 ds_separate (const struct string *st, struct substring delimiters,
1100 size_t *save_idx, struct substring *token)
1102 return ss_separate (ds_ss (st), delimiters, save_idx, token);
1105 /* Divides ST into tokens separated by any of the DELIMITERS,
1106 merging adjacent delimiters so that the empty string is never
1107 produced as a token. Each call replaces TOKEN by the next
1108 token in ST, or by an empty string if no tokens remain.
1109 Returns true if a token was obtained, false otherwise.
1111 Before the first call, initialize *SAVE_IDX to 0. Do not
1112 modify *SAVE_IDX between calls. */
1114 ds_tokenize (const struct string *st, struct substring delimiters,
1115 size_t *save_idx, struct substring *token)
1117 return ss_tokenize (ds_ss (st), delimiters, save_idx, token);
1120 /* Pad ST on the right with copies of PAD until ST is at least
1121 LENGTH bytes in size. If ST is initially LENGTH
1122 bytes or longer, this is a no-op. */
1124 ds_rpad (struct string *st, size_t length, char pad)
1126 if (length > st->ss.length)
1127 ds_put_byte_multiple (st, pad, length - st->ss.length);
1130 /* Sets the length of ST to exactly NEW_LENGTH,
1131 either by truncating bytes from the end,
1132 or by padding on the right with PAD. */
1134 ds_set_length (struct string *st, size_t new_length, char pad)
1136 if (st->ss.length < new_length)
1137 ds_rpad (st, new_length, pad);
1139 st->ss.length = new_length;
1142 /* Removes N bytes from ST starting at offset START. */
1144 ds_remove (struct string *st, size_t start, size_t n)
1146 if (n > 0 && start < st->ss.length)
1148 if (st->ss.length - start <= n)
1150 /* All bytes at or beyond START are deleted. */
1151 st->ss.length = start;
1155 /* Some bytes remain and must be shifted into
1157 memmove (st->ss.string + st->ss.length,
1158 st->ss.string + st->ss.length + n,
1159 st->ss.length - start - n);
1165 /* There are no bytes to delete or no bytes at or
1166 beyond START, hence deletion is a no-op. */
1170 /* Returns true if ST is empty, false otherwise. */
1172 ds_is_empty (const struct string *st)
1174 return ss_is_empty (st->ss);
1177 /* Returns the length of ST. */
1179 ds_length (const struct string *st)
1181 return ss_length (ds_ss (st));
1184 /* Returns the string data inside ST. */
1186 ds_data (const struct string *st)
1188 return ss_data (ds_ss (st));
1191 /* Returns a pointer to the null terminator ST.
1192 This might not be an actual null byte unless ds_c_str() has
1193 been called since the last modification to ST. */
1195 ds_end (const struct string *st)
1197 return ss_end (ds_ss (st));
1200 /* Returns the byte in position IDX in ST, as a value in the
1201 range of unsigned char. Returns EOF if IDX is out of the
1202 range of indexes for ST. */
1204 ds_at (const struct string *st, size_t idx)
1206 return ss_at (ds_ss (st), idx);
1209 /* Returns the first byte in ST as a value in the range of
1210 unsigned char. Returns EOF if ST is the empty string. */
1212 ds_first (const struct string *st)
1214 return ss_first (ds_ss (st));
1217 /* Returns the last byte in ST as a value in the range of
1218 unsigned char. Returns EOF if ST is the empty string. */
1220 ds_last (const struct string *st)
1222 return ss_last (ds_ss (st));
1225 /* Returns true if ST ends with SUFFIX, false otherwise. */
1227 ds_ends_with (const struct string *st, struct substring suffix)
1229 return ss_ends_with (st->ss, suffix);
1232 /* Returns the number of consecutive bytes at the beginning
1233 of ST that are in SKIP_SET. */
1235 ds_span (const struct string *st, struct substring skip_set)
1237 return ss_span (ds_ss (st), skip_set);
1240 /* Returns the number of consecutive bytes at the beginning
1241 of ST that are not in STOP_SET. */
1243 ds_cspan (const struct string *st, struct substring stop_set)
1245 return ss_cspan (ds_ss (st), stop_set);
1248 /* Returns the position of the first occurrence of byte C in
1249 ST at or after position OFS, or SIZE_MAX if there is no such
1252 ds_find_byte (const struct string *st, char c)
1254 return ss_find_byte (ds_ss (st), c);
1257 /* Compares A and B and returns a strcmp()-type comparison
1260 ds_compare (const struct string *a, const struct string *b)
1262 return ss_compare (ds_ss (a), ds_ss (b));
1265 /* Returns the position in ST that the byte at P occupies.
1266 P must point within ST or one past its end. */
1268 ds_pointer_to_position (const struct string *st, const char *p)
1270 return ss_pointer_to_position (ds_ss (st), p);
1273 /* Allocates and returns a null-terminated string that contains
1276 ds_xstrdup (const struct string *st)
1278 return ss_xstrdup (ds_ss (st));
1281 /* Returns the allocation size of ST. */
1283 ds_capacity (const struct string *st)
1285 return st->capacity;
1288 /* Returns the value of ST as a null-terminated string. */
1290 ds_cstr (const struct string *st_)
1292 struct string *st = CONST_CAST (struct string *, st_);
1293 if (st->ss.string == NULL)
1295 st->ss.string[st->ss.length] = '\0';
1296 return st->ss.string;
1299 /* Returns the value of ST as a null-terminated string and then
1300 reinitialized ST as an empty string. The caller must free the
1301 returned string with free(). */
1303 ds_steal_cstr (struct string *st)
1305 char *s = ds_cstr (st);
1310 /* Reads bytes from STREAM and appends them to ST, stopping
1311 after MAX_LENGTH bytes, after appending a newline, or
1312 after an I/O error or end of file was encountered, whichever
1313 comes first. Returns true if at least one byte was added
1314 to ST, false if no bytes were read before an I/O error or
1315 end of file (or if MAX_LENGTH was 0).
1317 This function treats LF and CR LF sequences as new-line,
1318 translating each of them to a single '\n' in ST. */
1320 ds_read_line (struct string *st, FILE *stream, size_t max_length)
1324 for (length = 0; length < max_length; length++)
1326 int c = getc (stream);
1333 ds_put_byte (st, c);
1340 /* CR followed by LF is special: translate to \n. */
1341 ds_put_byte (st, '\n');
1346 /* CR followed by anything else is just CR. */
1347 ds_put_byte (st, '\r');
1355 ds_put_byte (st, c);
1362 /* Removes a comment introduced by `#' from ST,
1363 ignoring occurrences inside quoted strings. */
1365 remove_comment (struct string *st)
1370 for (cp = ds_data (st); cp < ds_end (st); cp++)
1375 else if (*cp == '\\')
1378 else if (*cp == '\'' || *cp == '"')
1380 else if (*cp == '#')
1382 ds_truncate (st, cp - ds_cstr (st));
1387 /* Reads a line from STREAM into ST, then preprocesses as follows:
1389 - Splices lines terminated with `\'.
1391 - Deletes comments introduced by `#' outside of single or double
1394 - Deletes trailing white space.
1396 Returns true if a line was successfully read, false on
1397 failure. If LINE_NUMBER is non-null, then *LINE_NUMBER is
1398 incremented by the number of lines read. */
1400 ds_read_config_line (struct string *st, int *line_number, FILE *stream)
1405 if (!ds_read_line (st, stream, SIZE_MAX))
1408 ds_rtrim (st, ss_cstr (CC_SPACES));
1410 while (ds_chomp_byte (st, '\\'));
1412 remove_comment (st);
1416 /* Attempts to read SIZE * CNT bytes from STREAM and append them
1418 Returns true if all the requested data was read, false otherwise. */
1420 ds_read_stream (struct string *st, size_t size, size_t cnt, FILE *stream)
1424 size_t try_bytes = xtimes (cnt, size);
1425 if (size_in_bounds_p (xsum (ds_length (st), try_bytes)))
1427 char *buffer = ds_put_uninit (st, try_bytes);
1428 size_t got_bytes = fread (buffer, 1, try_bytes, stream);
1429 ds_truncate (st, ds_length (st) - (try_bytes - got_bytes));
1430 return got_bytes == try_bytes;
1442 /* Concatenates S onto ST. */
1444 ds_put_cstr (struct string *st, const char *s)
1447 ds_put_substring (st, ss_cstr (s));
1450 /* Concatenates SS to ST. */
1452 ds_put_substring (struct string *st, struct substring ss)
1454 memcpy (ds_put_uninit (st, ss_length (ss)), ss_data (ss), ss_length (ss));
1457 /* Returns ds_end(ST) and THEN increases the length by INCR. */
1459 ds_put_uninit (struct string *st, size_t incr)
1462 ds_extend (st, ds_length (st) + incr);
1464 st->ss.length += incr;
1468 /* Moves the bytes in ST following offset OFS + OLD_LEN in ST to offset OFS +
1469 NEW_LEN and returns the byte at offset OFS. The first min(OLD_LEN, NEW_LEN)
1470 bytes at the returned position are unchanged; if NEW_LEN > OLD_LEN then the
1471 following NEW_LEN - OLD_LEN bytes are initially indeterminate.
1473 The intention is that the caller should write NEW_LEN bytes at the returned
1474 position, to effectively replace the OLD_LEN bytes previously at that
1477 ds_splice_uninit (struct string *st,
1478 size_t ofs, size_t old_len, size_t new_len)
1480 if (new_len != old_len)
1482 if (new_len > old_len)
1483 ds_extend (st, ds_length (st) + (new_len - old_len));
1484 memmove (ds_data (st) + (ofs + new_len),
1485 ds_data (st) + (ofs + old_len),
1486 ds_length (st) - (ofs + old_len));
1487 st->ss.length += new_len - old_len;
1489 return ds_data (st) + ofs;
1492 /* Formats FORMAT as a printf string and appends the result to ST. */
1494 ds_put_format (struct string *st, const char *format, ...)
1498 va_start (args, format);
1499 ds_put_vformat (st, format, args);
1503 /* Formats FORMAT as a printf string as if in the C locale and appends the result to ST. */
1505 ds_put_c_format (struct string *st, const char *format, ...)
1509 va_start (args, format);
1510 ds_put_c_vformat (st, format, args);
1515 /* Formats FORMAT as a printf string, using fmt_func (a snprintf like function)
1516 and appends the result to ST. */
1518 ds_put_vformat_int (struct string *st, const char *format, va_list args_,
1519 int (*fmt_func) (char *, size_t, const char *, va_list))
1524 va_copy (args, args_);
1525 avail = st->ss.string != NULL ? st->capacity - st->ss.length + 1 : 0;
1526 needed = fmt_func (st->ss.string + st->ss.length, avail, format, args);
1529 if (needed >= avail)
1531 va_copy (args, args_);
1532 fmt_func (ds_put_uninit (st, needed), needed + 1, format, args);
1537 /* Some old libc's returned -1 when the destination string
1539 while (needed == -1)
1541 ds_extend (st, (st->capacity + 1) * 2);
1542 avail = st->capacity - st->ss.length + 1;
1544 va_copy (args, args_);
1545 needed = fmt_func (ds_end (st), avail, format, args);
1548 st->ss.length += needed;
1554 vasnwrapper (char *str, size_t size, const char *format, va_list ap)
1556 c_vasnprintf (str, &size, format, ap);
1560 /* Formats FORMAT as a printf string and appends the result to ST. */
1562 ds_put_vformat (struct string *st, const char *format, va_list args_)
1564 ds_put_vformat_int (st, format, args_, vsnprintf);
1567 /* Formats FORMAT as a printf string, as if in the C locale,
1568 and appends the result to ST. */
1570 ds_put_c_vformat (struct string *st, const char *format, va_list args_)
1572 ds_put_vformat_int (st, format, args_, vasnwrapper);
1575 /* Appends byte CH to ST. */
1577 ds_put_byte (struct string *st, int ch)
1579 ds_put_uninit (st, 1)[0] = ch;
1582 /* Appends CNT copies of byte CH to ST. */
1584 ds_put_byte_multiple (struct string *st, int ch, size_t cnt)
1586 memset (ds_put_uninit (st, cnt), ch, cnt);
1590 /* If relocation has been enabled, replace ST,
1591 with its relocated version */
1593 ds_relocate (struct string *st)
1595 const char *orig = ds_cstr (st);
1596 const char *rel = relocate (orig);
1601 ds_put_cstr (st, rel);
1602 /* The documentation for relocate says that casting away const
1603 and then freeing is appropriate ... */
1604 free (CONST_CAST (char *, rel));
1611 /* Operations on uint8_t "strings" */
1613 /* Copies buffer SRC, of SRC_SIZE bytes, to DST, of DST_SIZE bytes.
1614 DST is truncated to DST_SIZE bytes or padded on the right with
1615 copies of PAD as needed. */
1617 u8_buf_copy_rpad (uint8_t *dst, size_t dst_size,
1618 const uint8_t *src, size_t src_size,
1621 if (src_size >= dst_size)
1622 memmove (dst, src, dst_size);
1625 memmove (dst, src, src_size);
1626 memset (&dst[src_size], pad, dst_size - src_size);