+ if (st != NULL)
+ {
+ ss_dealloc (&st->ss);
+ st->ss.string = NULL;
+ st->ss.length = 0;
+ st->capacity = 0;
+ }
+}
+
+/* Swaps the contents of strings A and B. */
+void
+ds_swap (struct string *a, struct string *b)
+{
+ struct string tmp = *a;
+ *a = *b;
+ *b = tmp;
+}
+
+/* Helper function for ds_register_pool. */
+static void
+free_string (void *st_)
+{
+ struct string *st = st_;
+ ds_destroy (st);
+}
+
+/* Arranges for ST to be destroyed automatically as part of
+ POOL. */
+void
+ds_register_pool (struct string *st, struct pool *pool)
+{
+ pool_register (pool, free_string, st);
+}
+
+/* Cancels the arrangement for ST to be destroyed automatically
+ as part of POOL. */
+void
+ds_unregister_pool (struct string *st, struct pool *pool)
+{
+ pool_unregister (pool, st);
+}
+
+/* Copies SRC into DST.
+ DST and SRC may be the same string. */
+void
+ds_assign_string (struct string *dst, const struct string *src)
+{
+ ds_assign_substring (dst, ds_ss (src));
+}
+
+/* Replaces DST by SS.
+ SS may be a substring of DST. */
+void
+ds_assign_substring (struct string *dst, struct substring ss)
+{
+ dst->ss.length = ss.length;
+ ds_extend (dst, ss.length);
+ memmove (dst->ss.string, ss.string, ss.length);
+}
+
+/* Replaces DST by null-terminated string SRC. SRC may overlap
+ with DST. */
+void
+ds_assign_cstr (struct string *dst, const char *src)
+{
+ ds_assign_substring (dst, ss_cstr (src));
+}
+
+/* Truncates ST to zero length. */
+void
+ds_clear (struct string *st)
+{
+ st->ss.length = 0;
+}
+
+/* Returns a substring that contains ST. */
+struct substring
+ds_ss (const struct string *st)
+{
+ return st->ss;
+}
+
+/* Returns a substring that contains CNT bytes from ST
+ starting at position START.
+
+ If START is greater than or equal to the length of ST, then
+ the substring will be the empty string. If START + CNT
+ exceeds the length of ST, then the substring will only be
+ ds_length(ST) - START bytes long. */
+struct substring
+ds_substr (const struct string *st, size_t start, size_t cnt)
+{
+ return ss_substr (ds_ss (st), start, cnt);
+}
+
+/* Returns a substring that contains the first CNT bytes in
+ ST. If CNT exceeds the length of ST, then the substring will
+ contain all of ST. */
+struct substring
+ds_head (const struct string *st, size_t cnt)
+{
+ return ss_head (ds_ss (st), cnt);
+}
+
+/* Returns a substring that contains the last CNT bytes in
+ ST. If CNT exceeds the length of ST, then the substring will
+ contain all of ST. */
+struct substring
+ds_tail (const struct string *st, size_t cnt)
+{
+ return ss_tail (ds_ss (st), cnt);
+}
+
+/* Ensures that ST can hold at least MIN_CAPACITY bytes plus a null
+ terminator. */
+void
+ds_extend (struct string *st, size_t min_capacity)
+{
+ if (min_capacity > st->capacity)
+ {
+ st->capacity *= 2;
+ if (st->capacity < min_capacity)
+ st->capacity = 2 * min_capacity;
+
+ st->ss.string = xrealloc (st->ss.string, st->capacity + 1);
+ }
+}
+
+/* Shrink ST to the minimum capacity need to contain its content. */
+void
+ds_shrink (struct string *st)
+{
+ if (st->capacity != st->ss.length)
+ {
+ st->capacity = st->ss.length;
+ st->ss.string = xrealloc (st->ss.string, st->capacity + 1);
+ }
+}
+
+/* Truncates ST to at most LENGTH bytes long. */
+void
+ds_truncate (struct string *st, size_t length)
+{
+ ss_truncate (&st->ss, length);
+}
+
+/* Removes trailing bytes in TRIM_SET from ST.
+ Returns number of bytes removed. */
+size_t
+ds_rtrim (struct string *st, struct substring trim_set)
+{
+ return ss_rtrim (&st->ss, trim_set);
+}
+
+/* Removes leading bytes in TRIM_SET from ST.
+ Returns number of bytes removed. */
+size_t
+ds_ltrim (struct string *st, struct substring trim_set)
+{
+ size_t cnt = ds_span (st, trim_set);
+ if (cnt > 0)
+ ds_assign_substring (st, ds_substr (st, cnt, SIZE_MAX));
+ return cnt;
+}
+
+/* Trims leading and trailing bytes in TRIM_SET from ST.
+ Returns number of bytes removed. */
+size_t
+ds_trim (struct string *st, struct substring trim_set)
+{
+ size_t cnt = ds_rtrim (st, trim_set);
+ return cnt + ds_ltrim (st, trim_set);
+}
+
+/* If the last byte in ST is C, removes it and returns true.
+ Otherwise, returns false without modifying ST. */
+bool
+ds_chomp_byte (struct string *st, char c)
+{
+ return ss_chomp_byte (&st->ss, c);
+}
+
+/* If ST ends with SUFFIX, removes it and returns true.
+ Otherwise, returns false without modifying ST. */
+bool
+ds_chomp (struct string *st, struct substring suffix)
+{
+ return ss_chomp (&st->ss, suffix);
+}
+
+/* Divides ST into tokens separated by any of the DELIMITERS.
+ Each call replaces TOKEN by the next token in ST, or by an
+ empty string if no tokens remain. Returns true if a token was
+ obtained, false otherwise.
+
+ Before the first call, initialize *SAVE_IDX to 0. Do not
+ modify *SAVE_IDX between calls.
+
+ ST divides into exactly one more tokens than it contains
+ delimiters. That is, a delimiter at the start or end of ST or
+ a pair of adjacent delimiters yields an empty token, and the
+ empty string contains a single token. */
+bool
+ds_separate (const struct string *st, struct substring delimiters,
+ size_t *save_idx, struct substring *token)
+{
+ return ss_separate (ds_ss (st), delimiters, save_idx, token);
+}
+
+/* Divides ST into tokens separated by any of the DELIMITERS,
+ merging adjacent delimiters so that the empty string is never
+ produced as a token. Each call replaces TOKEN by the next
+ token in ST, or by an empty string if no tokens remain.
+ Returns true if a token was obtained, false otherwise.
+
+ Before the first call, initialize *SAVE_IDX to 0. Do not
+ modify *SAVE_IDX between calls. */
+bool
+ds_tokenize (const struct string *st, struct substring delimiters,
+ size_t *save_idx, struct substring *token)
+{
+ return ss_tokenize (ds_ss (st), delimiters, save_idx, token);
+}
+
+/* Pad ST on the right with copies of PAD until ST is at least
+ LENGTH bytes in size. If ST is initially LENGTH
+ bytes or longer, this is a no-op. */
+void
+ds_rpad (struct string *st, size_t length, char pad)
+{
+ if (length > st->ss.length)
+ ds_put_byte_multiple (st, pad, length - st->ss.length);
+}
+
+/* Sets the length of ST to exactly NEW_LENGTH,
+ either by truncating bytes from the end,
+ or by padding on the right with PAD. */
+void
+ds_set_length (struct string *st, size_t new_length, char pad)
+{
+ if (st->ss.length < new_length)
+ ds_rpad (st, new_length, pad);
+ else
+ st->ss.length = new_length;