add errors for unimplemented features
[pspp] / src / libpspp / str.c
index cd2363a0026c88454a26fbca0145603692bb7329..2a592b9064d88368547216404cc759cb9da21b8b 100644 (file)
@@ -1,5 +1,6 @@
 /* PSPP - a program for statistical analysis.
-   Copyright (C) 1997-9, 2000, 2006, 2009, 2010 Free Software Foundation, Inc.
+   Copyright (C) 1997-9, 2000, 2006, 2009, 2010, 2011, 2012, 2014,
+   2020 Free Software Foundation, Inc.
 
    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
 #include <errno.h>
 #include <stdint.h>
 #include <stdlib.h>
+#include <unistr.h>
 
 #include "libpspp/cast.h"
+#include "libpspp/i18n.h"
 #include "libpspp/message.h"
 #include "libpspp/pool.h"
 
+#include "gl/c-ctype.h"
+#include "gl/c-vasnprintf.h"
 #include "gl/relocatable.h"
 #include "gl/minmax.h"
 #include "gl/xalloc.h"
@@ -139,9 +144,9 @@ buf_copy_str_lpad (char *dst, size_t dst_size, const char *src, char pad)
     memcpy (dst, src, dst_size);
   else
     {
-      size_t pad_cnt = dst_size - src_len;
-      memset (&dst[0], pad, pad_cnt);
-      memcpy (dst + pad_cnt, src, src_len);
+      size_t n_pad = dst_size - src_len;
+      memset (&dst[0], pad, n_pad);
+      memcpy (dst + n_pad, src, src_len);
     }
 }
 
@@ -186,7 +191,7 @@ buf_copy_rpad (char *dst, size_t dst_size,
 void
 str_copy_rpad (char *dst, size_t dst_size, const char *src)
 {
-  if (dst_size > 0) 
+  if (dst_size > 0)
     {
       size_t src_len = strlen (src);
       if (src_len < dst_size - 1)
@@ -231,26 +236,33 @@ str_copy_buf_trunc (char *dst, size_t dst_size,
   dst[dst_len] = '\0';
 }
 
-/* Converts each byte in S to uppercase. */
+/* Converts each byte in S to uppercase.
+
+   This is suitable only for ASCII strings.  Use utf8_to_upper() for UTF-8
+   strings.*/
 void
 str_uppercase (char *s)
 {
   for (; *s != '\0'; s++)
-    *s = toupper ((unsigned char) *s);
+    *s = c_toupper ((unsigned char) *s);
 }
 
-/* Converts each byte in S to lowercase. */
+/* Converts each byte in S to lowercase.
+
+   This is suitable only for ASCII strings.  Use utf8_to_lower() for UTF-8
+   strings.*/
 void
 str_lowercase (char *s)
 {
   for (; *s != '\0'; s++)
-    *s = tolower ((unsigned char) *s);
+    *s = c_tolower ((unsigned char) *s);
 }
 
 /* Converts NUMBER into a string in 26-adic notation in BUFFER,
-   which has room for SIZE bytes.  Returns true if successful,
-   false if NUMBER, plus a trailing null, is too large to fit in
-   the available space.
+   which has room for SIZE bytes.  Uses uppercase if UPPERCASE is
+   true, otherwise lowercase, Returns true if successful, false
+   if NUMBER, plus a trailing null, is too large to fit in the
+   available space.
 
    26-adic notation is "spreadsheet column numbering": 1 = A, 2 =
    B, 3 = C, ... 26 = Z, 27 = AA, 28 = AB, 29 = AC, ...
@@ -262,24 +274,65 @@ str_lowercase (char *s)
    For more information, see
    http://en.wikipedia.org/wiki/Bijective_numeration. */
 bool
-str_format_26adic (unsigned long int number, char buffer[], size_t size)
+str_format_26adic (unsigned long int number, bool uppercase,
+                   char buffer[], size_t size)
 {
+  const char *alphabet
+    = uppercase ? "ABCDEFGHIJKLMNOPQRSTUVWXYZ" : "abcdefghijklmnopqrstuvwxyz";
   size_t length = 0;
 
   while (number-- > 0)
     {
       if (length >= size)
-        return false;
-      buffer[length++] = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"[number % 26];
+        goto overflow;
+      buffer[length++] = alphabet[number % 26];
       number /= 26;
     }
 
   if (length >= size)
-    return false;
+    goto overflow;
   buffer[length] = '\0';
 
   buf_reverse (buffer, length);
   return true;
+
+overflow:
+  if (length > 0)
+    buffer[0] = '\0';
+  return false;
+}
+
+/* Copies IN to buffer OUT with size OUT_SIZE, appending a null terminator.  If
+   IN is too long for OUT, or if IN contains a new-line, replaces the tail with
+   "...".
+
+   OUT_SIZE must be at least 16. */
+void
+str_ellipsize (struct substring in, char *out, size_t out_size)
+{
+  assert (out_size >= 16);
+
+  size_t out_maxlen = out_size - 1;
+  if (in.length > out_maxlen - 3)
+    out_maxlen -= 3;
+
+  size_t out_len = 0;
+  while (out_len < in.length
+         && in.string[out_len] != '\n'
+         && in.string[out_len] != '\0'
+         && (in.string[out_len] != '\r'
+             || out_len + 1 >= in.length
+             || in.string[out_len + 1] != '\n'))
+    {
+      int mblen = u8_mblen (CHAR_CAST (const uint8_t *, in.string + out_len),
+                            in.length - out_len);
+      if (mblen < 0 || out_len + mblen > out_maxlen)
+        break;
+      out_len += mblen;
+    }
+
+  memcpy (out, in.string, out_len);
+  strcpy (&out[out_len], out_len < in.length ? "..." : "");
 }
 
 /* Sets the SIZE bytes starting at BLOCK to C,
@@ -293,32 +346,32 @@ mempset (void *block, int c, size_t size)
 \f
 /* Substrings. */
 
-/* Returns a substring whose contents are the CNT bytes
+/* Returns a substring whose contents are the N bytes
    starting at the (0-based) position START in SS. */
 struct substring
-ss_substr (struct substring ss, size_t start, size_t cnt)
+ss_substr (struct substring ss, size_t start, size_t n)
 {
   if (start < ss.length)
-    return ss_buffer (ss.string + start, MIN (cnt, ss.length - start));
+    return ss_buffer (ss.string + start, MIN (n, ss.length - start));
   else
     return ss_buffer (ss.string + ss.length, 0);
 }
 
-/* Returns a substring whose contents are the first CNT
+/* Returns a substring whose contents are the first N
    bytes in SS. */
 struct substring
-ss_head (struct substring ss, size_t cnt)
+ss_head (struct substring ss, size_t n)
 {
-  return ss_buffer (ss.string, MIN (cnt, ss.length));
+  return ss_buffer (ss.string, MIN (n, ss.length));
 }
 
-/* Returns a substring whose contents are the last CNT bytes
+/* Returns a substring whose contents are the last N bytes
    in SS. */
 struct substring
-ss_tail (struct substring ss, size_t cnt)
+ss_tail (struct substring ss, size_t n)
 {
-  if (cnt < ss.length)
-    return ss_buffer (ss.string + (ss.length - cnt), cnt);
+  if (n < ss.length)
+    return ss_buffer (ss.string + (ss.length - n), n);
   else
     return ss;
 }
@@ -332,31 +385,38 @@ ss_alloc_substring (struct substring *new, struct substring old)
   new->length = old.length;
 }
 
-/* Allocates room for a CNT-byte string in NEW. */
+/* Allocates room for a N-byte string in NEW. */
 void
-ss_alloc_uninit (struct substring *new, size_t cnt)
+ss_alloc_uninit (struct substring *new, size_t n)
 {
-  new->string = xmalloc (cnt);
-  new->length = cnt;
+  new->string = xmalloc (n);
+  new->length = n;
 }
 
-/* Makes a pool_alloc_unaligned()'d copy of the contents of OLD
-   in POOL, and stores it in NEW. */
+void
+ss_realloc (struct substring *ss, size_t size)
+{
+  ss->string = xrealloc (ss->string, size);
+}
+
+/* Makes a pool_alloc_unaligned()'d, null-terminated copy of the contents of
+   OLD in POOL, and stores it in NEW. */
 void
 ss_alloc_substring_pool (struct substring *new, struct substring old,
                          struct pool *pool)
 {
-  new->string = pool_alloc_unaligned (pool, old.length);
+  new->string = pool_alloc_unaligned (pool, old.length + 1);
   new->length = old.length;
   memcpy (new->string, old.string, old.length);
+  new->string[old.length] = '\0';
 }
 
-/* Allocates room for a CNT-byte string in NEW in POOL. */
+/* Allocates room for a N-byte string in NEW in POOL. */
 void
-ss_alloc_uninit_pool (struct substring *new, size_t cnt, struct pool *pool)
+ss_alloc_uninit_pool (struct substring *new, size_t n, struct pool *pool)
 {
-  new->string = pool_alloc_unaligned (pool, cnt);
-  new->length = cnt;
+  new->string = pool_alloc_unaligned (pool, n);
+  new->length = n;
 }
 
 /* Frees the string that SS points to. */
@@ -366,12 +426,21 @@ ss_dealloc (struct substring *ss)
   free (ss->string);
 }
 
-/* Truncates SS to at most CNT bytes in length. */
+/* Exchanges the contents of A and B. */
 void
-ss_truncate (struct substring *ss, size_t cnt)
+ss_swap (struct substring *a, struct substring *b)
 {
-  if (ss->length > cnt)
-    ss->length = cnt;
+  struct substring tmp = *a;
+  *a = *b;
+  *b = tmp;
+}
+
+/* Truncates SS to at most N bytes in length. */
+void
+ss_truncate (struct substring *ss, size_t n)
+{
+  if (ss->length > n)
+    ss->length = n;
 }
 
 /* Removes trailing bytes in TRIM_SET from SS.
@@ -379,13 +448,13 @@ ss_truncate (struct substring *ss, size_t cnt)
 size_t
 ss_rtrim (struct substring *ss, struct substring trim_set)
 {
-  size_t cnt = 0;
-  while (cnt < ss->length
+  size_t n = 0;
+  while (n < ss->length
          && ss_find_byte (trim_set,
-                          ss->string[ss->length - cnt - 1]) != SIZE_MAX)
-    cnt++;
-  ss->length -= cnt;
-  return cnt;
+                          ss->string[ss->length - n - 1]) != SIZE_MAX)
+    n++;
+  ss->length -= n;
+  return n;
 }
 
 /* Removes leading bytes in TRIM_SET from SS.
@@ -393,9 +462,9 @@ ss_rtrim (struct substring *ss, struct substring trim_set)
 size_t
 ss_ltrim (struct substring *ss, struct substring trim_set)
 {
-  size_t cnt = ss_span (*ss, trim_set);
-  ss_advance (ss, cnt);
-  return cnt;
+  size_t n = ss_span (*ss, trim_set);
+  ss_advance (ss, n);
+  return n;
 }
 
 /* Trims leading and trailing bytes in TRIM_SET from SS. */
@@ -409,7 +478,7 @@ ss_trim (struct substring *ss, struct substring trim_set)
 /* If the last byte in SS is C, removes it and returns true.
    Otherwise, returns false without changing the string. */
 bool
-ss_chomp (struct substring *ss, char c)
+ss_chomp_byte (struct substring *ss, char c)
 {
   if (ss_last (*ss) == c)
     {
@@ -420,6 +489,20 @@ ss_chomp (struct substring *ss, char c)
     return false;
 }
 
+/* If SS ends with SUFFIX, removes it and returns true.
+   Otherwise, returns false without changing the string. */
+bool
+ss_chomp (struct substring *ss, struct substring suffix)
+{
+  if (ss_ends_with (*ss, suffix))
+    {
+      ss->length -= suffix.length;
+      return true;
+    }
+  else
+    return false;
+}
+
 /* Divides SS into tokens separated by any of the DELIMITERS.
    Each call replaces TOKEN by the next token in SS, or by an
    empty string if no tokens remain.  Returns true if a token was
@@ -464,21 +547,25 @@ bool
 ss_tokenize (struct substring ss, struct substring delimiters,
              size_t *save_idx, struct substring *token)
 {
+  bool found_token;
+
   ss_advance (&ss, *save_idx);
   *save_idx += ss_ltrim (&ss, delimiters);
   ss_get_bytes (&ss, ss_cspan (ss, delimiters), token);
-  *save_idx += ss_length (*token) + 1;
-  return ss_length (*token) > 0;
+
+  found_token = ss_length (*token) > 0;
+  *save_idx += ss_length (*token) + (found_token?1:0);
+  return found_token;
 }
 
-/* Removes the first CNT bytes from SS. */
+/* Removes the first N bytes from SS. */
 void
-ss_advance (struct substring *ss, size_t cnt)
+ss_advance (struct substring *ss, size_t n)
 {
-  if (cnt > ss->length)
-    cnt = ss->length;
-  ss->string += cnt;
-  ss->length -= cnt;
+  if (n > ss->length)
+    n = ss->length;
+  ss->string += n;
+  ss->length -= n;
 }
 
 /* If the first byte in SS is C, removes it and returns true.
@@ -528,6 +615,21 @@ ss_match_string (struct substring *ss, const struct substring target)
     return false;
 }
 
+/* If SS begins with TARGET, except possibly for case differences, removes it
+   and returns true.  Otherwise, returns false without changing SS. */
+bool
+ss_match_string_case (struct substring *ss, const struct substring target)
+{
+  size_t length = ss_length (target);
+  if (ss_equals_case (ss_head (*ss, length), target))
+    {
+      ss_advance (ss, length);
+      return true;
+    }
+  else
+    return false;
+}
+
 /* Removes the first byte from SS and returns it.
    If SS is empty, returns EOF without modifying SS. */
 int
@@ -553,15 +655,15 @@ ss_get_until (struct substring *ss, char delimiter, struct substring *out)
   return ss_match_byte (ss, delimiter);
 }
 
-/* Stores the first CNT bytes in SS in OUT (or fewer, if SS
-   is shorter than CNT bytes).  Trims the same bytes
-   from the beginning of SS.  Returns CNT. */
+/* Stores the first N bytes in SS in OUT (or fewer, if SS
+   is shorter than N bytes).  Trims the same bytes
+   from the beginning of SS.  Returns N. */
 size_t
-ss_get_bytes (struct substring *ss, size_t cnt, struct substring *out)
+ss_get_bytes (struct substring *ss, size_t n, struct substring *out)
 {
-  *out = ss_head (*ss, cnt);
-  ss_advance (ss, cnt);
-  return cnt;
+  *out = ss_head (*ss, n);
+  ss_advance (ss, n);
+  return n;
 }
 
 /* Parses and removes an optionally signed decimal integer from
@@ -648,6 +750,40 @@ ss_last (struct substring ss)
   return ss.length > 0 ? (unsigned char) ss.string[ss.length - 1] : EOF;
 }
 
+/* Returns true if SS starts with PREFIX, false otherwise. */
+bool
+ss_starts_with (struct substring ss, struct substring prefix)
+{
+  return (ss.length >= prefix.length
+          && !memcmp (ss.string, prefix.string, prefix.length));
+}
+
+/* Returns true if SS starts with PREFIX in any case, false otherwise. */
+bool
+ss_starts_with_case (struct substring ss, struct substring prefix)
+{
+  return (ss.length >= prefix.length
+          && !memcasecmp (ss.string, prefix.string, prefix.length));
+}
+
+/* Returns true if SS ends with SUFFIX, false otherwise. */
+bool
+ss_ends_with (struct substring ss, struct substring suffix)
+{
+  return (ss.length >= suffix.length
+          && !memcmp (&ss.string[ss.length - suffix.length], suffix.string,
+                      suffix.length));
+}
+
+/* Returns true if SS ends with SUFFIX in any case, false otherwise. */
+bool
+ss_ends_with_case (struct substring ss, struct substring suffix)
+{
+  return (ss.length >= suffix.length
+          && !memcasecmp (&ss.string[ss.length - suffix.length], suffix.string,
+                          suffix.length));
+}
+
 /* Returns the number of contiguous bytes at the beginning
    of SS that are in SKIP_SET. */
 size_t
@@ -677,10 +813,20 @@ ss_cspan (struct substring ss, struct substring stop_set)
 size_t
 ss_find_byte (struct substring ss, char c)
 {
-  const char *p = memchr (ss.string, c, ss.length);
+  const char *p = memchr (ss.string, (int) c, ss.length);
   return p != NULL ? p - ss.string : SIZE_MAX;
 }
 
+/* Returns the offset in HAYSTACK of the first instance of NEEDLE,
+   or SIZE_MAX if NEEDLE does not occur in HAYSTACK. */
+size_t
+ss_find_substring (struct substring haystack, struct substring needle)
+{
+  const char *p = memmem (haystack.string, haystack.length,
+                          needle.string, needle.length);
+  return p != NULL ? p - haystack.string : SIZE_MAX;
+}
+
 /* Compares A and B and returns a strcmp()-type comparison
    result. */
 int
@@ -740,6 +886,97 @@ ss_xstrdup (struct substring ss)
   s[ss.length] = '\0';
   return s;
 }
+/* UTF-8. */
+
+/* Returns the character represented by the UTF-8 sequence at the start of S.
+   The return value is either a Unicode code point in the range 0 to 0x10ffff,
+   or UINT32_MAX if S is empty. */
+ucs4_t
+ss_first_mb (struct substring s)
+{
+  return ss_at_mb (s, 0);
+}
+
+/* Returns the number of bytes in the UTF-8 character at the beginning of S.
+
+   The return value is 0 if S is empty, otherwise between 1 and 4. */
+int
+ss_first_mblen (struct substring s)
+{
+  return ss_at_mblen (s, 0);
+}
+
+/* Advances S past the UTF-8 character at its beginning.  Returns the Unicode
+   code point that was skipped (in the range 0 to 0x10ffff), or UINT32_MAX if S
+   was not modified because it was initially empty. */
+ucs4_t
+ss_get_mb (struct substring *s)
+{
+  if (s->length > 0)
+    {
+      ucs4_t uc;
+      int n;
+
+      n = u8_mbtouc (&uc, CHAR_CAST (const uint8_t *, s->string), s->length);
+      s->string += n;
+      s->length -= n;
+      return uc;
+    }
+  else
+    return UINT32_MAX;
+}
+
+/* Returns the character represented by the UTF-8 sequence starting OFS bytes
+   into S.  The return value is either a Unicode code point in the range 0 to
+   0x10ffff, or UINT32_MAX if OFS is past the last byte in S.
+
+   (Returns 0xfffd if OFS points into the middle, not the beginning, of a UTF-8
+   sequence.)  */
+ucs4_t
+ss_at_mb (struct substring s, size_t ofs)
+{
+  if (s.length > ofs)
+    {
+      ucs4_t uc;
+      u8_mbtouc (&uc, CHAR_CAST (const uint8_t *, s.string + ofs),
+                 s.length - ofs);
+      return uc;
+    }
+  else
+    return UINT32_MAX;
+}
+
+/* Returns the number of bytes represented by the UTF-8 sequence starting OFS
+   bytes into S.  The return value is 0 if OFS is past the last byte in S,
+   otherwise between 1 and 4. */
+int
+ss_at_mblen (struct substring s, size_t ofs)
+{
+  if (s.length > ofs)
+    {
+      ucs4_t uc;
+      return u8_mbtouc (&uc, CHAR_CAST (const uint8_t *, s.string + ofs),
+                        s.length - ofs);
+    }
+  else
+    return 0;
+}
+
+size_t
+ss_utf8_count_columns (struct substring s)
+{
+  return utf8_count_columns (s.string, s.length);
+}
+
+/* Returns a substring of S starting at 0-based display column START and
+   running for N display columns. */
+struct substring
+ss_utf8_columns (struct substring s, size_t start, size_t n)
+{
+  ss_advance (&s, utf8_columns_to_bytes (s.string, s.length, start));
+  s.length = utf8_columns_to_bytes (s.string, s.length, n);
+  return s;
+}
 \f
 /* Initializes ST as an empty string. */
 void
@@ -859,35 +1096,35 @@ ds_ss (const struct string *st)
   return st->ss;
 }
 
-/* Returns a substring that contains CNT bytes from ST
+/* Returns a substring that contains N 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
+   the substring will be the empty string.  If START + N
    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)
+ds_substr (const struct string *st, size_t start, size_t n)
 {
-  return ss_substr (ds_ss (st), start, cnt);
+  return ss_substr (ds_ss (st), start, n);
 }
 
-/* Returns a substring that contains the first CNT bytes in
-   ST.  If CNT exceeds the length of ST, then the substring will
+/* Returns a substring that contains the first N bytes in
+   ST.  If N exceeds the length of ST, then the substring will
    contain all of ST. */
 struct substring
-ds_head (const struct string *st, size_t cnt)
+ds_head (const struct string *st, size_t n)
 {
-  return ss_head (ds_ss (st), cnt);
+  return ss_head (ds_ss (st), n);
 }
 
-/* Returns a substring that contains the last CNT bytes in
-   ST.  If CNT exceeds the length of ST, then the substring will
+/* Returns a substring that contains the last N bytes in
+   ST.  If N exceeds the length of ST, then the substring will
    contain all of ST. */
 struct substring
-ds_tail (const struct string *st, size_t cnt)
+ds_tail (const struct string *st, size_t n)
 {
-  return ss_tail (ds_ss (st), cnt);
+  return ss_tail (ds_ss (st), n);
 }
 
 /* Ensures that ST can hold at least MIN_CAPACITY bytes plus a null
@@ -936,10 +1173,10 @@ ds_rtrim (struct string *st, struct substring trim_set)
 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;
+  size_t n = ds_span (st, trim_set);
+  if (n > 0)
+    ds_assign_substring (st, ds_substr (st, n, SIZE_MAX));
+  return n;
 }
 
 /* Trims leading and trailing bytes in TRIM_SET from ST.
@@ -947,16 +1184,24 @@ ds_ltrim (struct string *st, struct substring trim_set)
 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);
+  size_t n = ds_rtrim (st, trim_set);
+  return n + 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 (struct string *st, char c)
+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, c);
+  return ss_chomp (&st->ss, suffix);
 }
 
 /* Divides ST into tokens separated by any of the DELIMITERS.
@@ -1098,6 +1343,13 @@ ds_last (const struct string *st)
   return ss_last (ds_ss (st));
 }
 
+/* Returns true if ST ends with SUFFIX, false otherwise. */
+bool
+ds_ends_with (const struct string *st, struct substring suffix)
+{
+  return ss_ends_with (st->ss, suffix);
+}
+
 /* Returns the number of consecutive bytes at the beginning
    of ST that are in SKIP_SET. */
 size_t
@@ -1276,21 +1528,21 @@ ds_read_config_line (struct string *st, int *line_number, FILE *stream)
       (*line_number)++;
       ds_rtrim (st, ss_cstr (CC_SPACES));
     }
-  while (ds_chomp (st, '\\'));
+  while (ds_chomp_byte (st, '\\'));
 
   remove_comment (st);
   return true;
 }
 
-/* Attempts to read SIZE * CNT bytes from STREAM and append them
+/* Attempts to read SIZE * N bytes from STREAM and append them
    to ST.
    Returns true if all the requested data was read, false otherwise. */
 bool
-ds_read_stream (struct string *st, size_t size, size_t cnt, FILE *stream)
+ds_read_stream (struct string *st, size_t size, size_t n, FILE *stream)
 {
   if (size != 0)
     {
-      size_t try_bytes = xtimes (cnt, size);
+      size_t try_bytes = xtimes (n, size);
       if (size_in_bounds_p (xsum (ds_length (st), try_bytes)))
         {
           char *buffer = ds_put_uninit (st, try_bytes);
@@ -1320,7 +1572,8 @@ ds_put_cstr (struct string *st, const char *s)
 void
 ds_put_substring (struct string *st, struct substring ss)
 {
-  memcpy (ds_put_uninit (st, ss_length (ss)), ss_data (ss), ss_length (ss));
+  if (ss.length)
+    memcpy (ds_put_uninit (st, ss_length (ss)), ss_data (ss), ss_length (ss));
 }
 
 /* Returns ds_end(ST) and THEN increases the length by INCR. */
@@ -1334,6 +1587,33 @@ ds_put_uninit (struct string *st, size_t incr)
   return end;
 }
 
+/* Moves the bytes in ST following offset OFS + OLD_LEN in ST to offset OFS +
+   NEW_LEN and returns the byte at offset OFS.  The first min(OLD_LEN, NEW_LEN)
+   bytes at the returned position are unchanged; if NEW_LEN > OLD_LEN then the
+   following NEW_LEN - OLD_LEN bytes are initially indeterminate.
+
+   The intention is that the caller should write NEW_LEN bytes at the returned
+   position, to effectively replace the OLD_LEN bytes previously at that
+   position. */
+char *
+ds_splice_uninit (struct string *st,
+                  size_t ofs, size_t old_len, size_t new_len)
+{
+  if (new_len != old_len)
+    {
+      if (new_len > old_len)
+        ds_extend (st, ds_length (st) + (new_len - old_len));
+
+      assert (ds_length (st) >= ofs + old_len);
+
+      memmove (ds_data (st) + (ofs + new_len),
+               ds_data (st) + (ofs + old_len),
+               ds_length (st) - (ofs + old_len));
+      st->ss.length += new_len - old_len;
+    }
+  return ds_data (st) + ofs;
+}
+
 /* Formats FORMAT as a printf string and appends the result to ST. */
 void
 ds_put_format (struct string *st, const char *format, ...)
@@ -1345,6 +1625,17 @@ ds_put_format (struct string *st, const char *format, ...)
   va_end (args);
 }
 
+/* Formats FORMAT as a printf string as if in the C locale and appends the result to ST. */
+void
+ds_put_c_format (struct string *st, const char *format, ...)
+{
+  va_list args;
+
+  va_start (args, format);
+  ds_put_c_vformat (st, format, args);
+  va_end (args);
+}
+
 /* Formats FORMAT as a printf string and appends the result to ST. */
 void
 ds_put_vformat (struct string *st, const char *format, va_list args_)
@@ -1360,7 +1651,7 @@ ds_put_vformat (struct string *st, const char *format, va_list args_)
   if (needed >= avail)
     {
       va_copy (args, args_);
-      vsprintf (ds_put_uninit (st, needed), format, args);
+      vsnprintf (ds_put_uninit (st, needed), needed + 1, format, args);
       va_end (args);
     }
   else
@@ -1380,6 +1671,22 @@ ds_put_vformat (struct string *st, const char *format, va_list args_)
     }
 }
 
+/* Formats FORMAT as a printf string, as if in the C locale,
+   and appends the result to ST. */
+void
+ds_put_c_vformat (struct string *st, const char *format, va_list args)
+{
+  char buf[128];
+  size_t len = sizeof buf;
+  char *output = c_vasnprintf (buf, &len, format, args);
+  if (output)
+    {
+      ds_put_cstr (st, output);
+      if (output != buf)
+        free (output);
+    }
+}
+
 /* Appends byte CH to ST. */
 void
 ds_put_byte (struct string *st, int ch)
@@ -1387,13 +1694,32 @@ ds_put_byte (struct string *st, int ch)
   ds_put_uninit (st, 1)[0] = ch;
 }
 
-/* Appends CNT copies of byte CH to ST. */
+/* Appends N copies of byte CH to ST. */
 void
-ds_put_byte_multiple (struct string *st, int ch, size_t cnt)
+ds_put_byte_multiple (struct string *st, int ch, size_t n)
 {
-  memset (ds_put_uninit (st, cnt), ch, cnt);
+  memset (ds_put_uninit (st, n), ch, n);
 }
 
+/* Appends Unicode code point UC to ST in UTF-8 encoding. */
+void
+ds_put_unichar (struct string *st, ucs4_t uc)
+{
+  ds_extend (st, ds_length (st) + 6);
+  st->ss.length += u8_uctomb (CHAR_CAST (uint8_t *, ds_end (st)), uc, 6);
+}
+
+/* Appends N copies of S to ST. */
+void
+ds_put_substring_multiple (struct string *dst, struct substring src, size_t n)
+{
+  char *p = ds_put_uninit (dst, n * src.length);
+  for (size_t i = 0; i < n; i++)
+    {
+      memcpy (p, src.string, src.length);
+      p += src.length;
+    }
+}
 
 /* If relocation has been enabled, replace ST,
    with its relocated version */
@@ -1403,7 +1729,7 @@ ds_relocate (struct string *st)
   const char *orig = ds_cstr (st);
   const char *rel = relocate (orig);
 
-  if ( orig != rel)
+  if (orig != rel)
     {
       ds_clear (st);
       ds_put_cstr (st, rel);