Reform string library.
[pspp] / src / libpspp / str.c
1 /* PSPP - computes sample statistics.
2    Copyright (C) 1997-9, 2000, 2006 Free Software Foundation, Inc.
3    Written by Ben Pfaff <blp@gnu.org>.
4
5    This program is free software; you can redistribute it and/or
6    modify it under the terms of the GNU General Public License as
7    published by the Free Software Foundation; either version 2 of the
8    License, or (at your option) any later version.
9
10    This program is distributed in the hope that it will be useful, but
11    WITHOUT ANY WARRANTY; without even the implied warranty of
12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13    General Public License for more details.
14
15    You should have received a copy of the GNU General Public License
16    along with this program; if not, write to the Free Software
17    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
18    02110-1301, USA. */
19
20 #include <config.h>
21
22 #include "str.h"
23
24 #include <ctype.h>
25 #include <limits.h>
26 #include <stdlib.h>
27
28 #include <libpspp/alloc.h>
29 #include <libpspp/message.h>
30
31 #include "minmax.h"
32 #include "size_max.h"
33 #include "xsize.h"
34 \f
35 /* Reverses the order of NBYTES bytes at address P, thus converting
36    between little- and big-endian byte orders.  */
37 void
38 buf_reverse (char *p, size_t nbytes)
39 {
40   char *h = p, *t = &h[nbytes - 1];
41   char temp;
42
43   nbytes /= 2;
44   while (nbytes--)
45     {
46       temp = *h;
47       *h++ = *t;
48       *t-- = temp;
49     }
50 }
51
52 /* Finds the last NEEDLE of length NEEDLE_LEN in a HAYSTACK of length
53    HAYSTACK_LEN.  Returns a pointer to the needle found. */
54 char *
55 buf_find_reverse (const char *haystack, size_t haystack_len,
56                  const char *needle, size_t needle_len)
57 {
58   int i;
59   for (i = haystack_len - needle_len; i >= 0; i--)
60     if (!memcmp (needle, &haystack[i], needle_len))
61       return (char *) &haystack[i];
62   return 0;
63 }
64
65 /* Compares the SIZE bytes in A to those in B, disregarding case,
66    and returns a strcmp()-type result. */
67 int
68 buf_compare_case (const char *a_, const char *b_, size_t size)
69 {
70   const unsigned char *a = (unsigned char *) a_;
71   const unsigned char *b = (unsigned char *) b_;
72
73   while (size-- > 0) 
74     {
75       unsigned char ac = toupper (*a++);
76       unsigned char bc = toupper (*b++);
77
78       if (ac != bc) 
79         return ac > bc ? 1 : -1;
80     }
81
82   return 0;
83 }
84
85 /* Compares A of length A_LEN to B of length B_LEN.  The shorter
86    string is considered to be padded with spaces to the length of
87    the longer. */
88 int
89 buf_compare_rpad (const char *a, size_t a_len, const char *b, size_t b_len)
90 {
91   size_t min_len;
92   int result;
93
94   min_len = a_len < b_len ? a_len : b_len;
95   result = memcmp (a, b, min_len);
96   if (result != 0)
97     return result;
98   else 
99     {
100       size_t idx;
101       
102       if (a_len < b_len) 
103         {
104           for (idx = min_len; idx < b_len; idx++)
105             if (' ' != b[idx])
106               return ' ' > b[idx] ? 1 : -1;
107         }
108       else 
109         {
110           for (idx = min_len; idx < a_len; idx++)
111             if (a[idx] != ' ')
112               return a[idx] > ' ' ? 1 : -1;
113         }
114       return 0;
115     }
116 }
117
118 /* Compares strin A to string B.  The shorter string is
119    considered to be padded with spaces to the length of the
120    longer. */
121 int
122 str_compare_rpad (const char *a, const char *b)
123 {
124   return buf_compare_rpad (a, strlen (a), b, strlen (b));
125 }
126
127 /* Copies string SRC to buffer DST, of size DST_SIZE bytes.
128    DST is truncated to DST_SIZE bytes or padded on the right with
129    spaces as needed. */
130 void
131 buf_copy_str_rpad (char *dst, size_t dst_size, const char *src)
132 {
133   size_t src_len = strlen (src);
134   if (src_len >= dst_size)
135     memcpy (dst, src, dst_size);
136   else
137     {
138       memcpy (dst, src, src_len);
139       memset (&dst[src_len], ' ', dst_size - src_len);
140     }
141 }
142
143 /* Copies string SRC to buffer DST, of size DST_SIZE bytes.
144    DST is truncated to DST_SIZE bytes or padded on the left with
145    spaces as needed. */
146 void
147 buf_copy_str_lpad (char *dst, size_t dst_size, const char *src)
148 {
149   size_t src_len = strlen (src);
150   if (src_len >= dst_size)
151     memcpy (dst, src, dst_size);
152   else
153     {
154       size_t pad_cnt = dst_size - src_len;
155       memset (&dst[0], ' ', pad_cnt);
156       memcpy (dst + pad_cnt, src, src_len);
157     }
158 }
159
160 /* Copies buffer SRC, of SRC_SIZE bytes, to DST, of DST_SIZE bytes.
161    DST is truncated to DST_SIZE bytes or padded on the right with
162    spaces as needed. */
163 void
164 buf_copy_rpad (char *dst, size_t dst_size,
165                const char *src, size_t src_size)
166 {
167   if (src_size >= dst_size)
168     memmove (dst, src, dst_size);
169   else
170     {
171       memmove (dst, src, src_size);
172       memset (&dst[src_size], ' ', dst_size - src_size);
173     }
174 }
175
176 /* Copies string SRC to string DST, which is in a buffer DST_SIZE
177    bytes long.
178    Truncates DST to DST_SIZE - 1 characters or right-pads with
179    spaces to DST_SIZE - 1 characters if necessary. */
180 void
181 str_copy_rpad (char *dst, size_t dst_size, const char *src)
182 {
183   size_t src_len = strlen (src);
184   if (src_len < dst_size - 1)
185     {
186       memcpy (dst, src, src_len);
187       memset (&dst[src_len], ' ', dst_size - 1 - src_len);
188     }
189   else
190     memcpy (dst, src, dst_size - 1);
191   dst[dst_size - 1] = 0;
192 }
193
194 /* Copies SRC to DST, which is in a buffer DST_SIZE bytes long.
195    Truncates DST to DST_SIZE - 1 characters, if necessary. */
196 void
197 str_copy_trunc (char *dst, size_t dst_size, const char *src) 
198 {
199   size_t src_len = strlen (src);
200   assert (dst_size > 0);
201   if (src_len + 1 < dst_size)
202     memcpy (dst, src, src_len + 1);
203   else 
204     {
205       memcpy (dst, src, dst_size - 1);
206       dst[dst_size - 1] = '\0';
207     }
208 }
209
210 /* Copies buffer SRC, of SRC_LEN bytes,
211    to DST, which is in a buffer DST_SIZE bytes long.
212    Truncates DST to DST_SIZE - 1 characters, if necessary. */
213 void
214 str_copy_buf_trunc (char *dst, size_t dst_size,
215                     const char *src, size_t src_size) 
216 {
217   size_t dst_len;
218   assert (dst_size > 0);
219
220   dst_len = src_size < dst_size ? src_size : dst_size - 1;
221   memcpy (dst, src, dst_len);
222   dst[dst_len] = '\0';
223 }
224
225 /* Converts each character in S to uppercase. */
226 void
227 str_uppercase (char *s) 
228 {
229   for (; *s != '\0'; s++)
230     *s = toupper ((unsigned char) *s);
231 }
232
233 /* Converts each character in S to lowercase. */
234 void
235 str_lowercase (char *s) 
236 {
237   for (; *s != '\0'; s++)
238     *s = tolower ((unsigned char) *s);
239 }
240
241 /* Formats FORMAT into DST, as with sprintf(), and returns the
242    address of the terminating null written to DST. */
243 char *
244 spprintf (char *dst, const char *format, ...) 
245 {
246   va_list args;
247   int count;
248
249   va_start (args, format);
250   count = vsprintf (dst, format, args);
251   va_end (args);
252
253   return dst + count;
254 }
255 \f
256 /* Substrings. */
257
258 /* Returns an empty substring. */
259 struct substring
260 ss_empty (void) 
261 {
262   struct substring ss;
263   ss.string = NULL;
264   ss.length = 0;
265   return ss;
266 }
267
268 /* Returns a substring whose contents are the given C-style
269    string CSTR. */
270 struct substring
271 ss_cstr (const char *cstr) 
272 {
273   return ss_buffer (cstr, strlen (cstr));
274 }
275
276 /* Returns a substring whose contents are the CNT characters in
277    BUFFER. */   
278 struct substring
279 ss_buffer (const char *buffer, size_t cnt) 
280 {
281   struct substring ss;
282   ss.string = (char *) buffer;
283   ss.length = cnt;
284   return ss;
285 }
286
287 /* Returns a substring whose contents are the CNT characters
288    starting at the (0-based) position START in SS. */
289 struct substring
290 ss_substr (struct substring ss, size_t start, size_t cnt)
291 {
292   if (start < ss.length)
293     return ss_buffer (ss.string + start, MIN (cnt, ss.length - start));
294   else 
295     return ss_buffer (ss.string + ss.length, 0);
296 }
297
298 /* Returns a substring whose contents are the first CNT
299    characters in SS. */
300 struct substring
301 ss_head (struct substring ss, size_t cnt) 
302 {
303   return ss_buffer (ss.string, MIN (cnt, ss.length));
304 }
305
306 /* Returns a substring whose contents are the last CNT characters
307    in SS. */
308 struct substring
309 ss_tail (struct substring ss, size_t cnt) 
310 {
311   if (cnt < ss.length)
312     return ss_buffer (ss.string + (ss.length - cnt), cnt);
313   else
314     return ss;
315 }
316
317 /* Makes a malloc()'d copy of the contents of OLD
318    and stores it in NEW. */
319 void
320 ss_alloc_substring (struct substring *new, struct substring old) 
321 {
322   new->string = xmalloc (old.length);
323   new->length = old.length;
324   memcpy (new->string, old.string, old.length);
325 }
326
327 /* Allocates room for a CNT-character string in NEW. */
328 void
329 ss_alloc_uninit (struct substring *new, size_t cnt) 
330 {
331   new->string = xmalloc (cnt);
332   new->length = cnt;
333 }
334
335 /* Frees the string that SS points to. */
336 void
337 ss_dealloc (struct substring *ss) 
338 {
339   free (ss->string);
340 }
341
342 /* Truncates SS to at most CNT characters in length. */
343 void
344 ss_truncate (struct substring *ss, size_t cnt) 
345 {
346   if (ss->length > cnt)
347     ss->length = cnt;
348 }
349
350 /* Removes trailing characters in TRIM_SET from SS.
351    Returns number of characters removed. */
352 size_t
353 ss_rtrim (struct substring *ss, struct substring trim_set) 
354 {
355   size_t cnt = 0;
356   while (cnt < ss->length
357          && ss_find_char (trim_set,
358                           ss->string[ss->length - cnt - 1]) != SIZE_MAX) 
359     cnt++;
360   ss->length -= cnt;
361   return cnt;
362 }  
363
364 /* Removes leading characters in TRIM_SET from SS.
365    Returns number of characters removed. */
366 size_t
367 ss_ltrim (struct substring *ss, struct substring trim_set)
368 {
369   size_t cnt = ss_span (*ss, trim_set);
370   ss_advance (ss, cnt);
371   return cnt;
372 }
373
374 /* Trims leading and trailing characters in TRIM_SET from SS. */
375 void
376 ss_trim (struct substring *ss, struct substring trim_set) 
377 {
378   ss_ltrim (ss, trim_set);
379   ss_rtrim (ss, trim_set);
380 }
381
382 /* If the last character in SS is C, removes it and returns true.
383    Otherwise, returns false without changing the string. */
384 bool
385 ss_chomp (struct substring *ss, char c) 
386 {
387   if (ss_last (*ss) == c)
388     {
389       ss->length--;
390       return true;
391     }
392   else
393     return false;
394 }
395
396 /* Divides SS into tokens separated by any of the DELIMITERS.
397    Each call replaces TOKEN by the next token in SS, or by an
398    empty string if no tokens remain.  Returns true if a token was
399    obtained, false otherwise.
400
401    Before the first call, initialize *SAVE_IDX to 0.  Do not
402    modify *SAVE_IDX between calls.
403
404    SS divides into exactly one more tokens than it contains
405    delimiters.  That is, a delimiter at the start or end of SS or
406    a pair of adjacent delimiters yields an empty token, and the
407    empty string contains a single token. */
408 bool
409 ss_separate (struct substring ss, struct substring delimiters,
410              size_t *save_idx, struct substring *token) 
411 {
412   if (*save_idx <= ss_length (ss))
413     {
414       struct substring tmp = ss_substr (ss, *save_idx, SIZE_MAX);
415       size_t length = ss_cspan (tmp, delimiters);
416       *token = ss_head (tmp, length);
417       *save_idx += length + 1;
418       return true;
419     }
420   else 
421     {
422       *token = ss_empty ();
423       return false; 
424     }
425 }
426
427 /* Divides SS into tokens separated by any of the DELIMITERS,
428    merging adjacent delimiters so that the empty string is never
429    produced as a token.  Each call replaces TOKEN by the next
430    token in SS, or by an empty string if no tokens remain.
431    Returns true if a token was obtained, false otherwise.
432
433    Before the first call, initialize *SAVE_IDX to 0.  Do not
434    modify *SAVE_IDX between calls. */
435 bool
436 ss_tokenize (struct substring ss, struct substring delimiters,
437              size_t *save_idx, struct substring *token)
438 {
439   ss_advance (&ss, *save_idx);
440   *save_idx += ss_ltrim (&ss, delimiters);
441   *save_idx += ss_get_chars (&ss, ss_cspan (ss, delimiters), token);
442   return ss_length (*token) > 0;
443 }
444
445 /* Removes the first CNT characters from SS. */
446 void
447 ss_advance (struct substring *ss, size_t cnt) 
448 {
449   if (cnt > ss->length)
450     cnt = ss->length;
451   ss->string += cnt;
452   ss->length -= cnt;
453 }
454
455 /* If the first character in SS is C, removes it and returns true.
456    Otherwise, returns false without changing the string. */
457 bool
458 ss_match_char (struct substring *ss, char c) 
459 {
460   if (ss_first (*ss) == c)
461     {
462       ss->string++;
463       ss->length--;
464       return true;
465     }
466   else
467     return false;
468 }
469
470 /* Removes the first character from SS and returns it.
471    If SS is empty, returns EOF without modifying SS. */
472 int
473 ss_get_char (struct substring *ss) 
474 {
475   int c = ss_first (*ss);
476   if (c != EOF) 
477     {
478       ss->string++;
479       ss->length--;
480     }
481   return c;
482 }
483
484 /* Stores the prefix of SS up to the first DELIMITER in OUT (if
485    any).  Trims those same characters from SS.  DELIMITER is
486    removed from SS but not made part of OUT.  Returns true if
487    DELIMITER was found (and removed), false otherwise. */
488 bool
489 ss_get_until (struct substring *ss, char delimiter, struct substring *out)
490 {
491   ss_get_chars (ss, ss_cspan (*ss, ss_buffer (&delimiter, 1)), out);
492   return ss_match_char (ss, delimiter);
493 }
494
495 /* Stores the first CNT characters in SS in OUT (or fewer, if SS
496    is shorter than CNT characters).  Trims the same characters
497    from the beginning of SS. */
498 size_t
499 ss_get_chars (struct substring *ss, size_t cnt, struct substring *out) 
500 {
501   *out = ss_head (*ss, cnt);
502   ss_advance (ss, cnt);
503   return cnt;
504 }
505
506 /* Returns true if SS is empty (contains no characters),
507    false otherwise. */
508 bool
509 ss_is_empty (struct substring ss) 
510 {
511   return ss.length == 0;
512 }
513
514 /* Returns the number of characters in SS. */
515 size_t
516 ss_length (struct substring ss) 
517 {
518   return ss.length;
519 }
520
521 /* Returns a pointer to the characters in SS. */
522 char *
523 ss_data (struct substring ss) 
524 {
525   return ss.string;
526 }
527
528 /* Returns a pointer just past the last character in SS. */
529 char *
530 ss_end (struct substring ss) 
531 {
532   return ss.string + ss.length;
533 }
534
535 /* Returns the character in position IDX in SS, as a value in the
536    range of unsigned char.  Returns EOF if IDX is out of the
537    range of indexes for SS. */
538 int
539 ss_at (struct substring ss, size_t idx) 
540 {
541   return idx < ss.length ? (unsigned char) ss.string[idx] : EOF;
542 }
543
544 /* Returns the first character in SS as a value in the range of
545    unsigned char.  Returns EOF if SS is the empty string. */
546 int
547 ss_first (struct substring ss) 
548 {
549   return ss_at (ss, 0);
550 }
551
552 /* Returns the last character in SS as a value in the range of
553    unsigned char.  Returns EOF if SS is the empty string. */
554 int
555 ss_last (struct substring ss) 
556 {
557   return ss.length > 0 ? (unsigned char) ss.string[ss.length - 1] : EOF;
558 }
559
560 /* Returns the number of contiguous characters at the beginning
561    of SS that are in SKIP_SET. */
562 size_t
563 ss_span (struct substring ss, struct substring skip_set) 
564 {
565   size_t i;
566   for (i = 0; i < ss.length; i++) 
567     if (ss_find_char (skip_set, ss.string[i]) == SIZE_MAX)
568       break; 
569   return i;
570 }
571
572 /* Returns the number of contiguous characters at the beginning
573    of SS that are not in SKIP_SET. */
574 size_t
575 ss_cspan (struct substring ss, struct substring stop_set) 
576 {
577   size_t i;
578   for (i = 0; i < ss.length; i++) 
579     if (ss_find_char (stop_set, ss.string[i]) != SIZE_MAX)
580       break; 
581   return i;
582 }
583
584 /* Returns the offset in SS of the first instance of C,
585    or SIZE_MAX if C does not occur in SS. */
586 size_t
587 ss_find_char (struct substring ss, char c) 
588 {
589   const char *p = memchr (ss.string, c, ss.length);
590   return p != NULL ? p - ss.string : SIZE_MAX;
591 }
592
593 /* Compares A and B and returns a strcmp()-type comparison
594    result. */
595 int
596 ss_compare (struct substring a, struct substring b)
597 {
598   int retval = memcmp (a.string, b.string, MIN (a.length, b.length));
599   if (retval == 0)
600     retval = a.length < b.length ? -1 : a.length > b.length;
601   return retval;
602 }
603
604 /* Returns the position in SS that the character at P occupies.
605    P must point within SS or one past its end. */
606 size_t
607 ss_pointer_to_position (struct substring ss, const char *p)
608 {
609   size_t pos = p - ss.string;
610   assert (pos <= ss.length);
611   return pos;
612 }
613
614 /* Allocates and returns a null-terminated string that contains
615    SS. */
616 char *
617 ss_xstrdup (struct substring ss) 
618 {
619   char *s = xmalloc (ss.length + 1);
620   memcpy (s, ss.string, ss.length);
621   s[ss.length] = '\0';
622   return s;
623 }
624 \f
625 /* Initializes ST as an empty string. */
626 void
627 ds_init_empty (struct string *st)
628 {
629   st->ss = ss_empty ();
630   st->capacity = 0;
631 }
632
633 /* Initializes ST with initial contents S. */
634 void
635 ds_init_string (struct string *st, const struct string *s) 
636 {
637   ds_init_substring (st, ds_ss (s));
638 }
639
640 /* Initializes ST with initial contents SS. */
641 void
642 ds_init_substring (struct string *st, struct substring ss)
643 {
644   st->capacity = MAX (8, ss.length * 2);
645   st->ss.string = xmalloc (st->capacity + 1);
646   memcpy (st->ss.string, ss.string, ss.length);
647   st->ss.length = ss.length;
648 }
649
650 /* Initializes ST with initial contents S. */
651 void
652 ds_init_cstr (struct string *st, const char *s) 
653 {
654   ds_init_substring (st, ss_cstr (s));
655 }
656
657 /* Frees ST. */
658 void
659 ds_destroy (struct string *st)
660 {
661   if (st != NULL) 
662     {
663       ss_dealloc (&st->ss);
664       st->ss.string = NULL;
665       st->ss.length = 0;
666       st->capacity = 0; 
667     }
668 }
669
670 /* Swaps the contents of strings A and B. */
671 void
672 ds_swap (struct string *a, struct string *b) 
673 {
674   struct string tmp = *a;
675   *a = *b;
676   *b = tmp;
677 }
678
679 /* Copies SRC into DST.
680    DST and SRC may be the same string. */
681 void
682 ds_assign_string (struct string *dst, const struct string *src) 
683 {
684   ds_assign_substring (dst, ds_ss (src));
685 }
686
687 /* Replaces DST by SS.
688    SS may be a substring of DST. */
689 void
690 ds_assign_substring (struct string *dst, struct substring ss)
691 {
692   dst->ss.length = ss.length;
693   ds_extend (dst, ss.length);
694   memmove (dst->ss.string, ss.string, ss.length);
695 }
696
697 /* Replaces DST by null-terminated string SRC.  SRC may overlap
698    with DST. */
699 void
700 ds_assign_cstr (struct string *dst, const char *src)
701 {
702   ds_assign_substring (dst, ss_cstr (src));
703 }
704
705 /* Truncates ST to zero length. */
706 void
707 ds_clear (struct string *st)
708 {
709   st->ss.length = 0;
710 }
711
712 /* Returns a substring that contains ST. */
713 struct substring
714 ds_ss (const struct string *st) 
715 {
716   return st->ss;
717 }
718
719 /* Returns a substring that contains CNT characters from ST
720    starting at position START.
721
722    If START is greater than or equal to the length of ST, then
723    the substring will be the empty string.  If START + CNT
724    exceeds the length of ST, then the substring will only be
725    ds_length(ST) - START characters long. */
726 struct substring
727 ds_substr (const struct string *st, size_t start, size_t cnt) 
728 {
729   return ss_substr (ds_ss (st), start, cnt);
730 }
731
732 /* Returns a substring that contains the first CNT characters in
733    ST.  If CNT exceeds the length of ST, then the substring will
734    contain all of ST. */
735 struct substring
736 ds_head (const struct string *st, size_t cnt) 
737 {
738   return ss_head (ds_ss (st), cnt);
739 }
740
741 /* Returns a substring that contains the last CNT characters in
742    ST.  If CNT exceeds the length of ST, then the substring will
743    contain all of ST. */
744 struct substring
745 ds_tail (const struct string *st, size_t cnt)
746 {
747   return ss_tail (ds_ss (st), cnt);
748 }
749
750 /* Ensures that ST can hold at least MIN_CAPACITY characters plus a null
751    terminator. */
752 void
753 ds_extend (struct string *st, size_t min_capacity)
754 {
755   if (min_capacity > st->capacity)
756     {
757       st->capacity *= 2;
758       if (st->capacity < min_capacity)
759         st->capacity = 2 * min_capacity;
760
761       st->ss.string = xrealloc (st->ss.string, st->capacity + 1);
762     }
763 }
764
765 /* Shrink ST to the minimum capacity need to contain its content. */
766 void
767 ds_shrink (struct string *st)
768 {
769   if (st->capacity != st->ss.length)
770     {
771       st->capacity = st->ss.length;
772       st->ss.string = xrealloc (st->ss.string, st->capacity + 1);
773     }
774 }
775
776 /* Truncates ST to at most LENGTH characters long. */
777 void
778 ds_truncate (struct string *st, size_t length)
779 {
780   ss_truncate (&st->ss, length);
781 }
782
783 /* Removes trailing characters in TRIM_SET from ST.
784    Returns number of characters removed. */
785 size_t
786 ds_rtrim (struct string *st, struct substring trim_set) 
787 {
788   return ss_rtrim (&st->ss, trim_set);
789 }
790
791 /* Removes leading characters in TRIM_SET from ST.
792    Returns number of characters removed. */
793 size_t
794 ds_ltrim (struct string *st, struct substring trim_set) 
795 {
796   size_t cnt = ds_span (st, trim_set);
797   if (cnt > 0)
798     ds_assign_substring (st, ds_substr (st, cnt, SIZE_MAX));
799   return cnt;
800 }
801
802 /* Trims leading and trailing characters in TRIM_SET from ST.
803    Returns number of charactesr removed. */
804 size_t
805 ds_trim (struct string *st, struct substring trim_set) 
806 {
807   size_t cnt = ds_rtrim (st, trim_set);
808   return cnt + ds_ltrim (st, trim_set);
809 }
810
811 /* If the last character in ST is C, removes it and returns true.
812    Otherwise, returns false without modifying ST. */
813 bool
814 ds_chomp (struct string *st, char c) 
815 {
816   return ss_chomp (&st->ss, c);
817 }
818
819 /* Divides ST into tokens separated by any of the DELIMITERS.
820    Each call replaces TOKEN by the next token in ST, or by an
821    empty string if no tokens remain.  Returns true if a token was
822    obtained, false otherwise.
823
824    Before the first call, initialize *SAVE_IDX to 0.  Do not
825    modify *SAVE_IDX between calls.
826
827    ST divides into exactly one more tokens than it contains
828    delimiters.  That is, a delimiter at the start or end of ST or
829    a pair of adjacent delimiters yields an empty token, and the
830    empty string contains a single token. */
831 bool
832 ds_separate (const struct string *st, struct substring delimiters,
833              size_t *save_idx, struct substring *token)
834 {
835   return ss_separate (ds_ss (st), delimiters, save_idx, token);
836 }
837
838 /* Divides ST into tokens separated by any of the DELIMITERS,
839    merging adjacent delimiters so that the empty string is never
840    produced as a token.  Each call replaces TOKEN by the next
841    token in ST, or by an empty string if no tokens remain.
842    Returns true if a token was obtained, false otherwise.
843
844    Before the first call, initialize *SAVE_IDX to 0.  Do not
845    modify *SAVE_IDX between calls. */
846 bool
847 ds_tokenize (const struct string *st, struct substring delimiters,
848              size_t *save_idx, struct substring *token)
849 {
850   return ss_tokenize (ds_ss (st), delimiters, save_idx, token);
851 }
852
853 /* Pad ST on the right with copies of PAD until ST is at least
854    LENGTH characters in size.  If ST is initially LENGTH
855    characters or longer, this is a no-op. */
856 void
857 ds_rpad (struct string *st, size_t length, char pad) 
858 {
859   if (length > st->ss.length)
860     ds_put_char_multiple (st, pad, length - st->ss.length);
861 }
862
863 /* Returns true if ST is empty, false otherwise. */
864 bool
865 ds_is_empty (const struct string *st) 
866 {
867   return ss_is_empty (st->ss);
868 }
869
870 /* Returns the length of ST. */
871 size_t
872 ds_length (const struct string *st)
873 {
874   return ss_length (ds_ss (st));
875 }
876
877 /* Returns the string data inside ST. */
878 char *
879 ds_data (const struct string *st)
880 {
881   return ss_data (ds_ss (st));
882 }
883
884 /* Returns a pointer to the null terminator ST.
885    This might not be an actual null character unless ds_c_str() has
886    been called since the last modification to ST. */
887 char *
888 ds_end (const struct string *st)
889 {
890   return ss_end (ds_ss (st));
891 }
892
893 /* Returns the character in position IDX in ST, as a value in the
894    range of unsigned char.  Returns EOF if IDX is out of the
895    range of indexes for ST. */
896 int
897 ds_at (const struct string *st, size_t idx) 
898 {
899   return ss_at (ds_ss (st), idx);
900 }
901
902 /* Returns the first character in ST as a value in the range of
903    unsigned char.  Returns EOF if ST is the empty string. */
904 int
905 ds_first (const struct string *st) 
906 {
907   return ss_first (ds_ss (st));
908 }
909
910 /* Returns the last character in ST as a value in the range of
911    unsigned char.  Returns EOF if ST is the empty string. */
912 int
913 ds_last (const struct string *st) 
914 {
915   return ss_last (ds_ss (st));
916 }
917
918 /* Returns the number of consecutive characters at the beginning
919    of ST that are in SKIP_SET. */
920 size_t
921 ds_span (const struct string *st, struct substring skip_set)
922 {
923   return ss_span (ds_ss (st), skip_set);
924 }
925
926 /* Returns the number of consecutive characters at the beginning
927    of ST that are not in STOP_SET.  */
928 size_t
929 ds_cspan (const struct string *st, struct substring stop_set)
930 {
931   return ss_cspan (ds_ss (st), stop_set);
932 }
933
934 /* Returns the position of the first occurrence of character C in
935    ST at or after position OFS, or SIZE_MAX if there is no such
936    occurrence. */
937 size_t
938 ds_find_char (const struct string *st, char c)
939 {
940   return ss_find_char (ds_ss (st), c);
941 }
942
943 /* Compares A and B and returns a strcmp()-type comparison
944    result. */
945 int
946 ds_compare (const struct string *a, const struct string *b)
947 {
948   return ss_compare (ds_ss (a), ds_ss (b));
949 }
950
951 /* Returns the position in ST that the character at P occupies.
952    P must point within ST or one past its end. */
953 size_t
954 ds_pointer_to_position (const struct string *st, const char *p)
955 {
956   return ss_pointer_to_position (ds_ss (st), p);
957 }
958
959 /* Allocates and returns a null-terminated string that contains
960    ST. */
961 char *
962 ds_xstrdup (const struct string *st) 
963 {
964   return ss_xstrdup (ds_ss (st));
965 }
966
967 /* Returns the allocation size of ST. */
968 size_t
969 ds_capacity (const struct string *st)
970 {
971   return st->capacity;
972 }
973
974 /* Returns the value of ST as a null-terminated string. */
975 char *
976 ds_cstr (const struct string *st_)
977 {
978   struct string *st = (struct string *) st_;
979   if (st->ss.string == NULL) 
980     ds_extend (st, 1);
981   st->ss.string[st->ss.length] = '\0';
982   return st->ss.string;
983 }
984
985 /* Appends to ST a newline-terminated line read from STREAM.
986    Newline is the last character of ST on return, unless an I/O error
987    or end of file is encountered after reading some characters.
988    Returns true if a line is successfully read, false if no characters at
989    all were read before an I/O error or end of file was
990    encountered. */
991 bool
992 ds_read_line (struct string *st, FILE *stream)
993 {
994   int c;
995
996   c = getc (stream);
997   if (c == EOF)
998     return false;
999
1000   for (;;)
1001     {
1002       ds_put_char (st, c);
1003       if (c == '\n')
1004         return true;
1005
1006       c = getc (stream);
1007       if (c == EOF)
1008         return true;
1009     }
1010 }
1011
1012 /* Removes a comment introduced by `#' from ST,
1013    ignoring occurrences inside quoted strings. */
1014 static void
1015 remove_comment (struct string *st)
1016 {
1017   char *cp;
1018   int quote = 0;
1019       
1020   for (cp = ds_data (st); cp < ds_end (st); cp++)
1021     if (quote)
1022       {
1023         if (*cp == quote)
1024           quote = 0;
1025         else if (*cp == '\\')
1026           cp++;
1027       }
1028     else if (*cp == '\'' || *cp == '"')
1029       quote = *cp;
1030     else if (*cp == '#')
1031       {
1032         ds_truncate (st, cp - ds_cstr (st));
1033         break;
1034       }
1035 }
1036
1037 /* Reads a line from STREAM into ST, then preprocesses as follows:
1038
1039    - Splices lines terminated with `\'.
1040
1041    - Deletes comments introduced by `#' outside of single or double
1042      quotes.
1043
1044    - Deletes trailing white space.  
1045
1046    Returns true if a line was successfully read, false on
1047    failure.  If LINE_NUMBER is non-null, then *LINE_NUMBER is
1048    incremented by the number of lines read. */
1049 bool
1050 ds_read_config_line (struct string *st, int *line_number, FILE *stream)
1051 {
1052   ds_clear (st);
1053   do
1054     {
1055       if (!ds_read_line (st, stream))
1056         return false;
1057       (*line_number)++;
1058       ds_rtrim (st, ss_cstr (CC_SPACES));
1059     }
1060   while (ds_chomp (st, '\\'));
1061  
1062   remove_comment (st);
1063   return true;
1064 }
1065
1066 /* Attempts to read SIZE * CNT bytes from STREAM and append them
1067    to ST.
1068    Returns number of bytes actually read. */
1069 size_t
1070 ds_read_stream (struct string *st, size_t size, size_t cnt, FILE *stream) 
1071 {
1072   if (size != 0)
1073     {
1074       size_t try_bytes = xtimes (cnt, size);
1075       if (size_in_bounds_p (xsum (ds_length (st), try_bytes)))
1076         {
1077           char *buffer = ds_put_uninit (st, try_bytes);
1078           size_t got_bytes = fread (buffer, size, cnt, stream);
1079           ds_truncate (st, ds_length (st) - (try_bytes - got_bytes));
1080           return got_bytes; 
1081         }
1082     }
1083   return 0;
1084 }
1085
1086 /* Concatenates S onto ST. */
1087 void
1088 ds_put_cstr (struct string *st, const char *s)
1089 {
1090   if (s != NULL)
1091     ds_put_substring (st, ss_cstr (s));
1092 }
1093
1094 /* Concatenates SS to ST. */
1095 void
1096 ds_put_substring (struct string *st, struct substring ss)
1097 {
1098   memcpy (ds_put_uninit (st, ss_length (ss)), ss_data (ss), ss_length (ss));
1099 }
1100
1101 /* Returns ds_end(ST) and THEN increases the length by INCR. */
1102 char *
1103 ds_put_uninit (struct string *st, size_t incr)
1104 {
1105   char *end;
1106   ds_extend (st, ds_length (st) + incr);
1107   end = ds_end (st);
1108   st->ss.length += incr;
1109   return end;
1110 }
1111
1112 /* Formats FORMAT as a printf string and appends the result to ST. */
1113 void
1114 ds_put_format (struct string *st, const char *format, ...)
1115 {
1116   va_list args;
1117
1118   va_start (args, format);
1119   ds_put_vformat (st, format, args);
1120   va_end (args);
1121 }
1122
1123 /* Formats FORMAT as a printf string and appends the result to ST. */
1124 void
1125 ds_put_vformat (struct string *st, const char *format, va_list args_)
1126 {
1127   int avail, needed;
1128   va_list args;
1129
1130   va_copy (args, args_);
1131   avail = st->ss.string != NULL ? st->capacity - st->ss.length + 1 : 0;
1132   needed = vsnprintf (st->ss.string + st->ss.length, avail, format, args);
1133   va_end (args);
1134
1135   if (needed >= avail)
1136     {
1137       va_copy (args, args_);
1138       vsprintf (ds_put_uninit (st, needed), format, args);
1139       va_end (args);
1140     }
1141   else 
1142     {
1143       /* Some old libc's returned -1 when the destination string
1144          was too short. */
1145       while (needed == -1)
1146         {
1147           ds_extend (st, (st->capacity + 1) * 2);
1148           avail = st->capacity - st->ss.length + 1;
1149
1150           va_copy (args, args_);
1151           needed = vsnprintf (ds_end (st), avail, format, args);
1152           va_end (args);
1153         } 
1154       st->ss.length += needed;
1155     }
1156 }
1157
1158 /* Appends character CH to ST. */
1159 void
1160 ds_put_char (struct string *st, int ch)
1161 {
1162   ds_put_uninit (st, 1)[0] = ch;
1163 }
1164
1165 /* Appends CNT copies of character CH to ST. */
1166 void
1167 ds_put_char_multiple (struct string *st, int ch, size_t cnt) 
1168 {
1169   memset (ds_put_uninit (st, cnt), ch, cnt);
1170 }