1 /* PSPP - a program for statistical analysis.
2 Copyright (C) 1997-9, 2000, 2006, 2009, 2010, 2011, 2012, 2014 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-ctype.h"
32 #include "gl/c-vasnprintf.h"
33 #include "gl/relocatable.h"
34 #include "gl/minmax.h"
35 #include "gl/xalloc.h"
36 #include "gl/xmemdup0.h"
39 /* Reverses the order of NBYTES bytes at address P, thus converting
40 between little- and big-endian byte orders. */
42 buf_reverse (char *p, size_t nbytes)
44 char *h = p, *t = &h[nbytes - 1];
56 /* Compares the SIZE bytes in A to those in B, disregarding case,
57 and returns a strcmp()-type result. */
59 buf_compare_case (const char *a_, const char *b_, size_t size)
61 const unsigned char *a = (unsigned char *) a_;
62 const unsigned char *b = (unsigned char *) b_;
66 unsigned char ac = toupper (*a++);
67 unsigned char bc = toupper (*b++);
70 return ac > bc ? 1 : -1;
76 /* Compares A of length A_LEN to B of length B_LEN. The shorter
77 string is considered to be padded with spaces to the length of
80 buf_compare_rpad (const char *a, size_t a_len, const char *b, size_t b_len)
85 min_len = a_len < b_len ? a_len : b_len;
86 result = memcmp (a, b, min_len);
95 for (idx = min_len; idx < b_len; idx++)
97 return ' ' > b[idx] ? 1 : -1;
101 for (idx = min_len; idx < a_len; idx++)
103 return a[idx] > ' ' ? 1 : -1;
109 /* Compares strin A to string B. The shorter string is
110 considered to be padded with spaces to the length of the
113 str_compare_rpad (const char *a, const char *b)
115 return buf_compare_rpad (a, strlen (a), b, strlen (b));
118 /* Copies string SRC to buffer DST, of size DST_SIZE bytes.
119 DST is truncated to DST_SIZE bytes or padded on the right with
120 copies of PAD as needed. */
122 buf_copy_str_rpad (char *dst, size_t dst_size, const char *src, char pad)
124 size_t src_len = strlen (src);
125 if (src_len >= dst_size)
126 memcpy (dst, src, dst_size);
129 memcpy (dst, src, src_len);
130 memset (&dst[src_len], pad, dst_size - src_len);
134 /* Copies string SRC to buffer DST, of size DST_SIZE bytes.
135 DST is truncated to DST_SIZE bytes or padded on the left with
136 copies of PAD as needed. */
138 buf_copy_str_lpad (char *dst, size_t dst_size, const char *src, char pad)
140 size_t src_len = strlen (src);
141 if (src_len >= dst_size)
142 memcpy (dst, src, dst_size);
145 size_t pad_cnt = dst_size - src_len;
146 memset (&dst[0], pad, pad_cnt);
147 memcpy (dst + pad_cnt, src, src_len);
151 /* Copies buffer SRC, of SRC_SIZE bytes, to DST, of DST_SIZE bytes.
152 DST is truncated to DST_SIZE bytes or padded on the left with
153 copies of PAD as needed. */
155 buf_copy_lpad (char *dst, size_t dst_size,
156 const char *src, size_t src_size,
159 if (src_size >= dst_size)
160 memmove (dst, src, dst_size);
163 memset (dst, pad, dst_size - src_size);
164 memmove (&dst[dst_size - src_size], src, src_size);
168 /* Copies buffer SRC, of SRC_SIZE bytes, to DST, of DST_SIZE bytes.
169 DST is truncated to DST_SIZE bytes or padded on the right with
170 copies of PAD as needed. */
172 buf_copy_rpad (char *dst, size_t dst_size,
173 const char *src, size_t src_size,
176 if (src_size >= dst_size)
177 memmove (dst, src, dst_size);
180 memmove (dst, src, src_size);
181 memset (&dst[src_size], pad, dst_size - src_size);
185 /* Copies string SRC to string DST, which is in a buffer DST_SIZE
187 Truncates DST to DST_SIZE - 1 bytes or right-pads with
188 spaces to DST_SIZE - 1 bytes if necessary. */
190 str_copy_rpad (char *dst, size_t dst_size, const char *src)
194 size_t src_len = strlen (src);
195 if (src_len < dst_size - 1)
197 memcpy (dst, src, src_len);
198 memset (&dst[src_len], ' ', dst_size - 1 - src_len);
201 memcpy (dst, src, dst_size - 1);
202 dst[dst_size - 1] = 0;
206 /* Copies SRC to DST, which is in a buffer DST_SIZE bytes long.
207 Truncates DST to DST_SIZE - 1 bytes, if necessary. */
209 str_copy_trunc (char *dst, size_t dst_size, const char *src)
211 size_t src_len = strlen (src);
212 assert (dst_size > 0);
213 if (src_len + 1 < dst_size)
214 memcpy (dst, src, src_len + 1);
217 memcpy (dst, src, dst_size - 1);
218 dst[dst_size - 1] = '\0';
222 /* Copies buffer SRC, of SRC_LEN bytes,
223 to DST, which is in a buffer DST_SIZE bytes long.
224 Truncates DST to DST_SIZE - 1 bytes, if necessary. */
226 str_copy_buf_trunc (char *dst, size_t dst_size,
227 const char *src, size_t src_size)
230 assert (dst_size > 0);
232 dst_len = src_size < dst_size ? src_size : dst_size - 1;
233 memcpy (dst, src, dst_len);
237 /* Converts each byte in S to uppercase.
239 This is suitable only for ASCII strings. Use utf8_to_upper() for UTF-8
242 str_uppercase (char *s)
244 for (; *s != '\0'; s++)
245 *s = c_toupper ((unsigned char) *s);
248 /* Converts each byte in S to lowercase.
250 This is suitable only for ASCII strings. Use utf8_to_lower() for UTF-8
253 str_lowercase (char *s)
255 for (; *s != '\0'; s++)
256 *s = c_tolower ((unsigned char) *s);
259 /* Converts NUMBER into a string in 26-adic notation in BUFFER,
260 which has room for SIZE bytes. Uses uppercase if UPPERCASE is
261 true, otherwise lowercase, Returns true if successful, false
262 if NUMBER, plus a trailing null, is too large to fit in the
265 26-adic notation is "spreadsheet column numbering": 1 = A, 2 =
266 B, 3 = C, ... 26 = Z, 27 = AA, 28 = AB, 29 = AC, ...
268 26-adic notation is the special case of a k-adic numeration
269 system (aka bijective base-k numeration) with k=26. In k-adic
270 numeration, the digits are {1, 2, 3, ..., k} (there is no
271 digit 0), and integer 0 is represented by the empty string.
272 For more information, see
273 http://en.wikipedia.org/wiki/Bijective_numeration. */
275 str_format_26adic (unsigned long int number, bool uppercase,
276 char buffer[], size_t size)
279 = uppercase ? "ABCDEFGHIJKLMNOPQRSTUVWXYZ" : "abcdefghijklmnopqrstuvwxyz";
286 buffer[length++] = alphabet[number % 26];
292 buffer[length] = '\0';
294 buf_reverse (buffer, length);
303 /* Sets the SIZE bytes starting at BLOCK to C,
304 and returns the byte following BLOCK. */
306 mempset (void *block, int c, size_t size)
308 memset (block, c, size);
309 return (char *) block + size;
314 /* Returns a substring whose contents are the CNT bytes
315 starting at the (0-based) position START in SS. */
317 ss_substr (struct substring ss, size_t start, size_t cnt)
319 if (start < ss.length)
320 return ss_buffer (ss.string + start, MIN (cnt, ss.length - start));
322 return ss_buffer (ss.string + ss.length, 0);
325 /* Returns a substring whose contents are the first CNT
328 ss_head (struct substring ss, size_t cnt)
330 return ss_buffer (ss.string, MIN (cnt, ss.length));
333 /* Returns a substring whose contents are the last CNT bytes
336 ss_tail (struct substring ss, size_t cnt)
339 return ss_buffer (ss.string + (ss.length - cnt), cnt);
344 /* Makes a malloc()'d, null-terminated copy of the contents of OLD
345 and stores it in NEW. */
347 ss_alloc_substring (struct substring *new, struct substring old)
349 new->string = xmemdup0 (old.string, old.length);
350 new->length = old.length;
353 /* Allocates room for a CNT-byte string in NEW. */
355 ss_alloc_uninit (struct substring *new, size_t cnt)
357 new->string = xmalloc (cnt);
362 ss_realloc (struct substring *ss, size_t size)
364 ss->string = xrealloc (ss->string, size);
367 /* Makes a pool_alloc_unaligned()'d, null-terminated copy of the contents of
368 OLD in POOL, and stores it in NEW. */
370 ss_alloc_substring_pool (struct substring *new, struct substring old,
373 new->string = pool_alloc_unaligned (pool, old.length + 1);
374 new->length = old.length;
375 memcpy (new->string, old.string, old.length);
376 new->string[old.length] = '\0';
379 /* Allocates room for a CNT-byte string in NEW in POOL. */
381 ss_alloc_uninit_pool (struct substring *new, size_t cnt, struct pool *pool)
383 new->string = pool_alloc_unaligned (pool, cnt);
387 /* Frees the string that SS points to. */
389 ss_dealloc (struct substring *ss)
394 /* Truncates SS to at most CNT bytes in length. */
396 ss_truncate (struct substring *ss, size_t cnt)
398 if (ss->length > cnt)
402 /* Removes trailing bytes in TRIM_SET from SS.
403 Returns number of bytes removed. */
405 ss_rtrim (struct substring *ss, struct substring trim_set)
408 while (cnt < ss->length
409 && ss_find_byte (trim_set,
410 ss->string[ss->length - cnt - 1]) != SIZE_MAX)
416 /* Removes leading bytes in TRIM_SET from SS.
417 Returns number of bytes removed. */
419 ss_ltrim (struct substring *ss, struct substring trim_set)
421 size_t cnt = ss_span (*ss, trim_set);
422 ss_advance (ss, cnt);
426 /* Trims leading and trailing bytes in TRIM_SET from SS. */
428 ss_trim (struct substring *ss, struct substring trim_set)
430 ss_ltrim (ss, trim_set);
431 ss_rtrim (ss, trim_set);
434 /* If the last byte in SS is C, removes it and returns true.
435 Otherwise, returns false without changing the string. */
437 ss_chomp_byte (struct substring *ss, char c)
439 if (ss_last (*ss) == c)
448 /* If SS ends with SUFFIX, removes it and returns true.
449 Otherwise, returns false without changing the string. */
451 ss_chomp (struct substring *ss, struct substring suffix)
453 if (ss_ends_with (*ss, suffix))
455 ss->length -= suffix.length;
462 /* Divides SS into tokens separated by any of the DELIMITERS.
463 Each call replaces TOKEN by the next token in SS, or by an
464 empty string if no tokens remain. Returns true if a token was
465 obtained, false otherwise.
467 Before the first call, initialize *SAVE_IDX to 0. Do not
468 modify *SAVE_IDX between calls.
470 SS divides into exactly one more tokens than it contains
471 delimiters. That is, a delimiter at the start or end of SS or
472 a pair of adjacent delimiters yields an empty token, and the
473 empty string contains a single token. */
475 ss_separate (struct substring ss, struct substring delimiters,
476 size_t *save_idx, struct substring *token)
478 if (*save_idx <= ss_length (ss))
480 struct substring tmp = ss_substr (ss, *save_idx, SIZE_MAX);
481 size_t length = ss_cspan (tmp, delimiters);
482 *token = ss_head (tmp, length);
483 *save_idx += length + 1;
488 *token = ss_empty ();
493 /* Divides SS into tokens separated by any of the DELIMITERS,
494 merging adjacent delimiters so that the empty string is never
495 produced as a token. Each call replaces TOKEN by the next
496 token in SS, or by an empty string if no tokens remain, and
497 then skips past the first delimiter following the token.
498 Returns true if a token was obtained, false otherwise.
500 Before the first call, initialize *SAVE_IDX to 0. Do not
501 modify *SAVE_IDX between calls. */
503 ss_tokenize (struct substring ss, struct substring delimiters,
504 size_t *save_idx, struct substring *token)
508 ss_advance (&ss, *save_idx);
509 *save_idx += ss_ltrim (&ss, delimiters);
510 ss_get_bytes (&ss, ss_cspan (ss, delimiters), token);
512 found_token = ss_length (*token) > 0;
513 *save_idx += ss_length (*token) + found_token;
517 /* Removes the first CNT bytes from SS. */
519 ss_advance (struct substring *ss, size_t cnt)
521 if (cnt > ss->length)
527 /* If the first byte in SS is C, removes it and returns true.
528 Otherwise, returns false without changing the string. */
530 ss_match_byte (struct substring *ss, char c)
532 if (ss_first (*ss) == c)
542 /* If the first byte in SS is in MATCH, removes it and
543 returns the byte that was removed.
544 Otherwise, returns EOF without changing the string. */
546 ss_match_byte_in (struct substring *ss, struct substring match)
550 && memchr (match.string, ss->string[0], match.length) != NULL)
559 /* If SS begins with TARGET, removes it and returns true.
560 Otherwise, returns false without changing SS. */
562 ss_match_string (struct substring *ss, const struct substring target)
564 size_t length = ss_length (target);
565 if (ss_equals (ss_head (*ss, length), target))
567 ss_advance (ss, length);
574 /* Removes the first byte from SS and returns it.
575 If SS is empty, returns EOF without modifying SS. */
577 ss_get_byte (struct substring *ss)
579 int c = ss_first (*ss);
588 /* Stores the prefix of SS up to the first DELIMITER in OUT (if
589 any). Trims those same bytes from SS. DELIMITER is
590 removed from SS but not made part of OUT. Returns true if
591 DELIMITER was found (and removed), false otherwise. */
593 ss_get_until (struct substring *ss, char delimiter, struct substring *out)
595 ss_get_bytes (ss, ss_cspan (*ss, ss_buffer (&delimiter, 1)), out);
596 return ss_match_byte (ss, delimiter);
599 /* Stores the first CNT bytes in SS in OUT (or fewer, if SS
600 is shorter than CNT bytes). Trims the same bytes
601 from the beginning of SS. Returns CNT. */
603 ss_get_bytes (struct substring *ss, size_t cnt, struct substring *out)
605 *out = ss_head (*ss, cnt);
606 ss_advance (ss, cnt);
610 /* Parses and removes an optionally signed decimal integer from
611 the beginning of SS. Returns 0 if an error occurred,
612 otherwise the number of bytes removed from SS. Stores
613 the integer's value into *VALUE. */
615 ss_get_long (struct substring *ss, long *value)
620 length = ss_span (*ss, ss_cstr ("+-"));
621 length += ss_span (ss_substr (*ss, length, SIZE_MAX), ss_cstr (CC_DIGITS));
622 if (length > 0 && length < sizeof tmp)
626 memcpy (tmp, ss_data (*ss), length);
629 *value = strtol (tmp, &tail, 10);
630 if (tail - tmp == length)
632 ss_advance (ss, length);
640 /* Returns true if SS is empty (has length 0 bytes),
643 ss_is_empty (struct substring ss)
645 return ss.length == 0;
648 /* Returns the number of bytes in SS. */
650 ss_length (struct substring ss)
655 /* Returns a pointer to the bytes in SS. */
657 ss_data (struct substring ss)
662 /* Returns a pointer just past the last byte in SS. */
664 ss_end (struct substring ss)
666 return ss.string + ss.length;
669 /* Returns the byte in position IDX in SS, as a value in the
670 range of unsigned char. Returns EOF if IDX is out of the
671 range of indexes for SS. */
673 ss_at (struct substring ss, size_t idx)
675 return idx < ss.length ? (unsigned char) ss.string[idx] : EOF;
678 /* Returns the first byte in SS as a value in the range of
679 unsigned char. Returns EOF if SS is the empty string. */
681 ss_first (struct substring ss)
683 return ss_at (ss, 0);
686 /* Returns the last byte in SS as a value in the range of
687 unsigned char. Returns EOF if SS is the empty string. */
689 ss_last (struct substring ss)
691 return ss.length > 0 ? (unsigned char) ss.string[ss.length - 1] : EOF;
694 /* Returns true if SS starts with PREFIX, false otherwise. */
696 ss_starts_with (struct substring ss, struct substring prefix)
698 return (ss.length >= prefix.length
699 && !memcmp (ss.string, prefix.string, prefix.length));
702 /* Returns true if SS ends with SUFFIX, false otherwise. */
704 ss_ends_with (struct substring ss, struct substring suffix)
706 return (ss.length >= suffix.length
707 && !memcmp (&ss.string[ss.length - suffix.length], suffix.string,
711 /* Returns the number of contiguous bytes at the beginning
712 of SS that are in SKIP_SET. */
714 ss_span (struct substring ss, struct substring skip_set)
717 for (i = 0; i < ss.length; i++)
718 if (ss_find_byte (skip_set, ss.string[i]) == SIZE_MAX)
723 /* Returns the number of contiguous bytes at the beginning
724 of SS that are not in SKIP_SET. */
726 ss_cspan (struct substring ss, struct substring stop_set)
729 for (i = 0; i < ss.length; i++)
730 if (ss_find_byte (stop_set, ss.string[i]) != SIZE_MAX)
735 /* Returns the offset in SS of the first instance of C,
736 or SIZE_MAX if C does not occur in SS. */
738 ss_find_byte (struct substring ss, char c)
740 const char *p = memchr (ss.string, c, ss.length);
741 return p != NULL ? p - ss.string : SIZE_MAX;
744 /* Returns the offset in HAYSTACK of the first instance of NEEDLE,
745 or SIZE_MAX if NEEDLE does not occur in HAYSTACK. */
747 ss_find_substring (struct substring haystack, struct substring needle)
749 const char *p = memmem (haystack.string, haystack.length,
750 needle.string, needle.length);
751 return p != NULL ? p - haystack.string : SIZE_MAX;
754 /* Compares A and B and returns a strcmp()-type comparison
757 ss_compare (struct substring a, struct substring b)
759 int retval = memcmp (a.string, b.string, MIN (a.length, b.length));
761 retval = a.length < b.length ? -1 : a.length > b.length;
765 /* Compares A and B case-insensitively and returns a
766 strcmp()-type comparison result. */
768 ss_compare_case (struct substring a, struct substring b)
770 int retval = memcasecmp (a.string, b.string, MIN (a.length, b.length));
772 retval = a.length < b.length ? -1 : a.length > b.length;
776 /* Compares A and B and returns true if their contents are
777 identical, false otherwise. */
779 ss_equals (struct substring a, struct substring b)
781 return a.length == b.length && !memcmp (a.string, b.string, a.length);
784 /* Compares A and B and returns true if their contents are
785 identical except possibly for case differences, false
788 ss_equals_case (struct substring a, struct substring b)
790 return a.length == b.length && !memcasecmp (a.string, b.string, a.length);
793 /* Returns the position in SS that the byte at P occupies.
794 P must point within SS or one past its end. */
796 ss_pointer_to_position (struct substring ss, const char *p)
798 size_t pos = p - ss.string;
799 assert (pos <= ss.length);
803 /* Allocates and returns a null-terminated string that contains
806 ss_xstrdup (struct substring ss)
808 char *s = xmalloc (ss.length + 1);
809 memcpy (s, ss.string, ss.length);
815 /* Returns the character represented by the UTF-8 sequence at the start of S.
816 The return value is either a Unicode code point in the range 0 to 0x10ffff,
817 or UINT32_MAX if S is empty. */
819 ss_first_mb (struct substring s)
821 return ss_at_mb (s, 0);
824 /* Returns the number of bytes in the UTF-8 character at the beginning of S.
826 The return value is 0 if S is empty, otherwise between 1 and 4. */
828 ss_first_mblen (struct substring s)
830 return ss_at_mblen (s, 0);
833 /* Advances S past the UTF-8 character at its beginning. Returns the Unicode
834 code point that was skipped (in the range 0 to 0x10ffff), or UINT32_MAX if S
835 was not modified because it was initially empty. */
837 ss_get_mb (struct substring *s)
844 n = u8_mbtouc (&uc, CHAR_CAST (const uint8_t *, s->string), s->length);
853 /* Returns the character represented by the UTF-8 sequence starting OFS bytes
854 into S. The return value is either a Unicode code point in the range 0 to
855 0x10ffff, or UINT32_MAX if OFS is past the last byte in S.
857 (Returns 0xfffd if OFS points into the middle, not the beginning, of a UTF-8
860 ss_at_mb (struct substring s, size_t ofs)
865 u8_mbtouc (&uc, CHAR_CAST (const uint8_t *, s.string + ofs),
873 /* Returns the number of bytes represented by the UTF-8 sequence starting OFS
874 bytes into S. The return value is 0 if OFS is past the last byte in S,
875 otherwise between 1 and 4. */
877 ss_at_mblen (struct substring s, size_t ofs)
882 return u8_mbtouc (&uc, CHAR_CAST (const uint8_t *, s.string + ofs),
889 /* Initializes ST as an empty string. */
891 ds_init_empty (struct string *st)
893 st->ss = ss_empty ();
897 /* Initializes ST with initial contents S. */
899 ds_init_string (struct string *st, const struct string *s)
901 ds_init_substring (st, ds_ss (s));
904 /* Initializes ST with initial contents SS. */
906 ds_init_substring (struct string *st, struct substring ss)
908 st->capacity = MAX (8, ss.length * 2);
909 st->ss.string = xmalloc (st->capacity + 1);
910 memcpy (st->ss.string, ss.string, ss.length);
911 st->ss.length = ss.length;
914 /* Initializes ST with initial contents S. */
916 ds_init_cstr (struct string *st, const char *s)
918 ds_init_substring (st, ss_cstr (s));
923 ds_destroy (struct string *st)
927 ss_dealloc (&st->ss);
928 st->ss.string = NULL;
934 /* Swaps the contents of strings A and B. */
936 ds_swap (struct string *a, struct string *b)
938 struct string tmp = *a;
943 /* Helper function for ds_register_pool. */
945 free_string (void *st_)
947 struct string *st = st_;
951 /* Arranges for ST to be destroyed automatically as part of
954 ds_register_pool (struct string *st, struct pool *pool)
956 pool_register (pool, free_string, st);
959 /* Cancels the arrangement for ST to be destroyed automatically
962 ds_unregister_pool (struct string *st, struct pool *pool)
964 pool_unregister (pool, st);
967 /* Copies SRC into DST.
968 DST and SRC may be the same string. */
970 ds_assign_string (struct string *dst, const struct string *src)
972 ds_assign_substring (dst, ds_ss (src));
975 /* Replaces DST by SS.
976 SS may be a substring of DST. */
978 ds_assign_substring (struct string *dst, struct substring ss)
980 dst->ss.length = ss.length;
981 ds_extend (dst, ss.length);
982 memmove (dst->ss.string, ss.string, ss.length);
985 /* Replaces DST by null-terminated string SRC. SRC may overlap
988 ds_assign_cstr (struct string *dst, const char *src)
990 ds_assign_substring (dst, ss_cstr (src));
993 /* Truncates ST to zero length. */
995 ds_clear (struct string *st)
1000 /* Returns a substring that contains ST. */
1002 ds_ss (const struct string *st)
1007 /* Returns a substring that contains CNT bytes from ST
1008 starting at position START.
1010 If START is greater than or equal to the length of ST, then
1011 the substring will be the empty string. If START + CNT
1012 exceeds the length of ST, then the substring will only be
1013 ds_length(ST) - START bytes long. */
1015 ds_substr (const struct string *st, size_t start, size_t cnt)
1017 return ss_substr (ds_ss (st), start, cnt);
1020 /* Returns a substring that contains the first CNT bytes in
1021 ST. If CNT exceeds the length of ST, then the substring will
1022 contain all of ST. */
1024 ds_head (const struct string *st, size_t cnt)
1026 return ss_head (ds_ss (st), cnt);
1029 /* Returns a substring that contains the last CNT bytes in
1030 ST. If CNT exceeds the length of ST, then the substring will
1031 contain all of ST. */
1033 ds_tail (const struct string *st, size_t cnt)
1035 return ss_tail (ds_ss (st), cnt);
1038 /* Ensures that ST can hold at least MIN_CAPACITY bytes plus a null
1041 ds_extend (struct string *st, size_t min_capacity)
1043 if (min_capacity > st->capacity)
1046 if (st->capacity < min_capacity)
1047 st->capacity = 2 * min_capacity;
1049 st->ss.string = xrealloc (st->ss.string, st->capacity + 1);
1053 /* Shrink ST to the minimum capacity need to contain its content. */
1055 ds_shrink (struct string *st)
1057 if (st->capacity != st->ss.length)
1059 st->capacity = st->ss.length;
1060 st->ss.string = xrealloc (st->ss.string, st->capacity + 1);
1064 /* Truncates ST to at most LENGTH bytes long. */
1066 ds_truncate (struct string *st, size_t length)
1068 ss_truncate (&st->ss, length);
1071 /* Removes trailing bytes in TRIM_SET from ST.
1072 Returns number of bytes removed. */
1074 ds_rtrim (struct string *st, struct substring trim_set)
1076 return ss_rtrim (&st->ss, trim_set);
1079 /* Removes leading bytes in TRIM_SET from ST.
1080 Returns number of bytes removed. */
1082 ds_ltrim (struct string *st, struct substring trim_set)
1084 size_t cnt = ds_span (st, trim_set);
1086 ds_assign_substring (st, ds_substr (st, cnt, SIZE_MAX));
1090 /* Trims leading and trailing bytes in TRIM_SET from ST.
1091 Returns number of bytes removed. */
1093 ds_trim (struct string *st, struct substring trim_set)
1095 size_t cnt = ds_rtrim (st, trim_set);
1096 return cnt + ds_ltrim (st, trim_set);
1099 /* If the last byte in ST is C, removes it and returns true.
1100 Otherwise, returns false without modifying ST. */
1102 ds_chomp_byte (struct string *st, char c)
1104 return ss_chomp_byte (&st->ss, c);
1107 /* If ST ends with SUFFIX, removes it and returns true.
1108 Otherwise, returns false without modifying ST. */
1110 ds_chomp (struct string *st, struct substring suffix)
1112 return ss_chomp (&st->ss, suffix);
1115 /* Divides ST into tokens separated by any of the DELIMITERS.
1116 Each call replaces TOKEN by the next token in ST, or by an
1117 empty string if no tokens remain. Returns true if a token was
1118 obtained, false otherwise.
1120 Before the first call, initialize *SAVE_IDX to 0. Do not
1121 modify *SAVE_IDX between calls.
1123 ST divides into exactly one more tokens than it contains
1124 delimiters. That is, a delimiter at the start or end of ST or
1125 a pair of adjacent delimiters yields an empty token, and the
1126 empty string contains a single token. */
1128 ds_separate (const struct string *st, struct substring delimiters,
1129 size_t *save_idx, struct substring *token)
1131 return ss_separate (ds_ss (st), delimiters, save_idx, token);
1134 /* Divides ST into tokens separated by any of the DELIMITERS,
1135 merging adjacent delimiters so that the empty string is never
1136 produced as a token. Each call replaces TOKEN by the next
1137 token in ST, or by an empty string if no tokens remain.
1138 Returns true if a token was obtained, false otherwise.
1140 Before the first call, initialize *SAVE_IDX to 0. Do not
1141 modify *SAVE_IDX between calls. */
1143 ds_tokenize (const struct string *st, struct substring delimiters,
1144 size_t *save_idx, struct substring *token)
1146 return ss_tokenize (ds_ss (st), delimiters, save_idx, token);
1149 /* Pad ST on the right with copies of PAD until ST is at least
1150 LENGTH bytes in size. If ST is initially LENGTH
1151 bytes or longer, this is a no-op. */
1153 ds_rpad (struct string *st, size_t length, char pad)
1155 if (length > st->ss.length)
1156 ds_put_byte_multiple (st, pad, length - st->ss.length);
1159 /* Sets the length of ST to exactly NEW_LENGTH,
1160 either by truncating bytes from the end,
1161 or by padding on the right with PAD. */
1163 ds_set_length (struct string *st, size_t new_length, char pad)
1165 if (st->ss.length < new_length)
1166 ds_rpad (st, new_length, pad);
1168 st->ss.length = new_length;
1171 /* Removes N bytes from ST starting at offset START. */
1173 ds_remove (struct string *st, size_t start, size_t n)
1175 if (n > 0 && start < st->ss.length)
1177 if (st->ss.length - start <= n)
1179 /* All bytes at or beyond START are deleted. */
1180 st->ss.length = start;
1184 /* Some bytes remain and must be shifted into
1186 memmove (st->ss.string + st->ss.length,
1187 st->ss.string + st->ss.length + n,
1188 st->ss.length - start - n);
1194 /* There are no bytes to delete or no bytes at or
1195 beyond START, hence deletion is a no-op. */
1199 /* Returns true if ST is empty, false otherwise. */
1201 ds_is_empty (const struct string *st)
1203 return ss_is_empty (st->ss);
1206 /* Returns the length of ST. */
1208 ds_length (const struct string *st)
1210 return ss_length (ds_ss (st));
1213 /* Returns the string data inside ST. */
1215 ds_data (const struct string *st)
1217 return ss_data (ds_ss (st));
1220 /* Returns a pointer to the null terminator ST.
1221 This might not be an actual null byte unless ds_c_str() has
1222 been called since the last modification to ST. */
1224 ds_end (const struct string *st)
1226 return ss_end (ds_ss (st));
1229 /* Returns the byte in position IDX in ST, as a value in the
1230 range of unsigned char. Returns EOF if IDX is out of the
1231 range of indexes for ST. */
1233 ds_at (const struct string *st, size_t idx)
1235 return ss_at (ds_ss (st), idx);
1238 /* Returns the first byte in ST as a value in the range of
1239 unsigned char. Returns EOF if ST is the empty string. */
1241 ds_first (const struct string *st)
1243 return ss_first (ds_ss (st));
1246 /* Returns the last byte in ST as a value in the range of
1247 unsigned char. Returns EOF if ST is the empty string. */
1249 ds_last (const struct string *st)
1251 return ss_last (ds_ss (st));
1254 /* Returns true if ST ends with SUFFIX, false otherwise. */
1256 ds_ends_with (const struct string *st, struct substring suffix)
1258 return ss_ends_with (st->ss, suffix);
1261 /* Returns the number of consecutive bytes at the beginning
1262 of ST that are in SKIP_SET. */
1264 ds_span (const struct string *st, struct substring skip_set)
1266 return ss_span (ds_ss (st), skip_set);
1269 /* Returns the number of consecutive bytes at the beginning
1270 of ST that are not in STOP_SET. */
1272 ds_cspan (const struct string *st, struct substring stop_set)
1274 return ss_cspan (ds_ss (st), stop_set);
1277 /* Returns the position of the first occurrence of byte C in
1278 ST at or after position OFS, or SIZE_MAX if there is no such
1281 ds_find_byte (const struct string *st, char c)
1283 return ss_find_byte (ds_ss (st), c);
1286 /* Compares A and B and returns a strcmp()-type comparison
1289 ds_compare (const struct string *a, const struct string *b)
1291 return ss_compare (ds_ss (a), ds_ss (b));
1294 /* Returns the position in ST that the byte at P occupies.
1295 P must point within ST or one past its end. */
1297 ds_pointer_to_position (const struct string *st, const char *p)
1299 return ss_pointer_to_position (ds_ss (st), p);
1302 /* Allocates and returns a null-terminated string that contains
1305 ds_xstrdup (const struct string *st)
1307 return ss_xstrdup (ds_ss (st));
1310 /* Returns the allocation size of ST. */
1312 ds_capacity (const struct string *st)
1314 return st->capacity;
1317 /* Returns the value of ST as a null-terminated string. */
1319 ds_cstr (const struct string *st_)
1321 struct string *st = CONST_CAST (struct string *, st_);
1322 if (st->ss.string == NULL)
1324 st->ss.string[st->ss.length] = '\0';
1325 return st->ss.string;
1328 /* Returns the value of ST as a null-terminated string and then
1329 reinitialized ST as an empty string. The caller must free the
1330 returned string with free(). */
1332 ds_steal_cstr (struct string *st)
1334 char *s = ds_cstr (st);
1339 /* Reads bytes from STREAM and appends them to ST, stopping
1340 after MAX_LENGTH bytes, after appending a newline, or
1341 after an I/O error or end of file was encountered, whichever
1342 comes first. Returns true if at least one byte was added
1343 to ST, false if no bytes were read before an I/O error or
1344 end of file (or if MAX_LENGTH was 0).
1346 This function treats LF and CR LF sequences as new-line,
1347 translating each of them to a single '\n' in ST. */
1349 ds_read_line (struct string *st, FILE *stream, size_t max_length)
1353 for (length = 0; length < max_length; length++)
1355 int c = getc (stream);
1362 ds_put_byte (st, c);
1369 /* CR followed by LF is special: translate to \n. */
1370 ds_put_byte (st, '\n');
1375 /* CR followed by anything else is just CR. */
1376 ds_put_byte (st, '\r');
1384 ds_put_byte (st, c);
1391 /* Removes a comment introduced by `#' from ST,
1392 ignoring occurrences inside quoted strings. */
1394 remove_comment (struct string *st)
1399 for (cp = ds_data (st); cp < ds_end (st); cp++)
1404 else if (*cp == '\\')
1407 else if (*cp == '\'' || *cp == '"')
1409 else if (*cp == '#')
1411 ds_truncate (st, cp - ds_cstr (st));
1416 /* Reads a line from STREAM into ST, then preprocesses as follows:
1418 - Splices lines terminated with `\'.
1420 - Deletes comments introduced by `#' outside of single or double
1423 - Deletes trailing white space.
1425 Returns true if a line was successfully read, false on
1426 failure. If LINE_NUMBER is non-null, then *LINE_NUMBER is
1427 incremented by the number of lines read. */
1429 ds_read_config_line (struct string *st, int *line_number, FILE *stream)
1434 if (!ds_read_line (st, stream, SIZE_MAX))
1437 ds_rtrim (st, ss_cstr (CC_SPACES));
1439 while (ds_chomp_byte (st, '\\'));
1441 remove_comment (st);
1445 /* Attempts to read SIZE * CNT bytes from STREAM and append them
1447 Returns true if all the requested data was read, false otherwise. */
1449 ds_read_stream (struct string *st, size_t size, size_t cnt, FILE *stream)
1453 size_t try_bytes = xtimes (cnt, size);
1454 if (size_in_bounds_p (xsum (ds_length (st), try_bytes)))
1456 char *buffer = ds_put_uninit (st, try_bytes);
1457 size_t got_bytes = fread (buffer, 1, try_bytes, stream);
1458 ds_truncate (st, ds_length (st) - (try_bytes - got_bytes));
1459 return got_bytes == try_bytes;
1471 /* Concatenates S onto ST. */
1473 ds_put_cstr (struct string *st, const char *s)
1476 ds_put_substring (st, ss_cstr (s));
1479 /* Concatenates SS to ST. */
1481 ds_put_substring (struct string *st, struct substring ss)
1483 memcpy (ds_put_uninit (st, ss_length (ss)), ss_data (ss), ss_length (ss));
1486 /* Returns ds_end(ST) and THEN increases the length by INCR. */
1488 ds_put_uninit (struct string *st, size_t incr)
1491 ds_extend (st, ds_length (st) + incr);
1493 st->ss.length += incr;
1497 /* Moves the bytes in ST following offset OFS + OLD_LEN in ST to offset OFS +
1498 NEW_LEN and returns the byte at offset OFS. The first min(OLD_LEN, NEW_LEN)
1499 bytes at the returned position are unchanged; if NEW_LEN > OLD_LEN then the
1500 following NEW_LEN - OLD_LEN bytes are initially indeterminate.
1502 The intention is that the caller should write NEW_LEN bytes at the returned
1503 position, to effectively replace the OLD_LEN bytes previously at that
1506 ds_splice_uninit (struct string *st,
1507 size_t ofs, size_t old_len, size_t new_len)
1509 if (new_len != old_len)
1511 if (new_len > old_len)
1512 ds_extend (st, ds_length (st) + (new_len - old_len));
1513 memmove (ds_data (st) + (ofs + new_len),
1514 ds_data (st) + (ofs + old_len),
1515 ds_length (st) - (ofs + old_len));
1516 st->ss.length += new_len - old_len;
1518 return ds_data (st) + ofs;
1521 /* Formats FORMAT as a printf string and appends the result to ST. */
1523 ds_put_format (struct string *st, const char *format, ...)
1527 va_start (args, format);
1528 ds_put_vformat (st, format, args);
1532 /* Formats FORMAT as a printf string as if in the C locale and appends the result to ST. */
1534 ds_put_c_format (struct string *st, const char *format, ...)
1538 va_start (args, format);
1539 ds_put_c_vformat (st, format, args);
1543 /* Formats FORMAT as a printf string and appends the result to ST. */
1545 ds_put_vformat (struct string *st, const char *format, va_list args_)
1550 va_copy (args, args_);
1551 avail = st->ss.string != NULL ? st->capacity - st->ss.length + 1 : 0;
1552 needed = vsnprintf (st->ss.string + st->ss.length, avail, format, args);
1555 if (needed >= avail)
1557 va_copy (args, args_);
1558 vsnprintf (ds_put_uninit (st, needed), needed + 1, format, args);
1563 /* Some old libc's returned -1 when the destination string
1565 while (needed == -1)
1567 ds_extend (st, (st->capacity + 1) * 2);
1568 avail = st->capacity - st->ss.length + 1;
1570 va_copy (args, args_);
1571 needed = vsnprintf (ds_end (st), avail, format, args);
1574 st->ss.length += needed;
1578 /* Formats FORMAT as a printf string, as if in the C locale,
1579 and appends the result to ST. */
1581 ds_put_c_vformat (struct string *st, const char *format, va_list args)
1584 size_t len = sizeof buf;
1585 char *output = c_vasnprintf (buf, &len, format, args);
1588 ds_put_cstr (st, output);
1594 /* Appends byte CH to ST. */
1596 ds_put_byte (struct string *st, int ch)
1598 ds_put_uninit (st, 1)[0] = ch;
1601 /* Appends CNT copies of byte CH to ST. */
1603 ds_put_byte_multiple (struct string *st, int ch, size_t cnt)
1605 memset (ds_put_uninit (st, cnt), ch, cnt);
1608 /* Appends Unicode code point UC to ST in UTF-8 encoding. */
1610 ds_put_unichar (struct string *st, ucs4_t uc)
1612 ds_extend (st, ds_length (st) + 6);
1613 st->ss.length += u8_uctomb (CHAR_CAST (uint8_t *, ds_end (st)), uc, 6);
1616 /* If relocation has been enabled, replace ST,
1617 with its relocated version */
1619 ds_relocate (struct string *st)
1621 const char *orig = ds_cstr (st);
1622 const char *rel = relocate (orig);
1627 ds_put_cstr (st, rel);
1628 /* The documentation for relocate says that casting away const
1629 and then freeing is appropriate ... */
1630 free (CONST_CAST (char *, rel));
1637 /* Operations on uint8_t "strings" */
1639 /* Copies buffer SRC, of SRC_SIZE bytes, to DST, of DST_SIZE bytes.
1640 DST is truncated to DST_SIZE bytes or padded on the right with
1641 copies of PAD as needed. */
1643 u8_buf_copy_rpad (uint8_t *dst, size_t dst_size,
1644 const uint8_t *src, size_t src_size,
1647 if (src_size >= dst_size)
1648 memmove (dst, src, dst_size);
1651 memmove (dst, src, src_size);
1652 memset (&dst[src_size], pad, dst_size - src_size);