Add a SPLIT parameter to `format-spec'

* doc/lispref/strings.texi (Custom Format Strings): Document it.

* lisp/format-spec.el (format-spec): Add an optional parameter to
return a list of strings (bug#33740).

1 files changed, 11 insertions, 1 deletions

diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index a31e71d5260..4ac5057454f 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -1216,7 +1216,7 @@ The function @code{format-spec} described in this section performs a
 similar function to @code{format}, except it operates on format
 control strings that use arbitrary specification characters.
 
-@defun format-spec template spec-alist &optional ignore-missing
+@defun format-spec template spec-alist &optional ignore-missing split
 This function returns a string produced from the format string
 @var{template} according to conversions specified in @var{spec-alist},
 which is an alist (@pxref{Association Lists}) of the form
@@ -1258,6 +1258,16 @@ any; if it is @code{delete}, those format specifications are removed
 from the output; any other non-@code{nil} value is handled like
 @code{ignore}, but any occurrences of @samp{%%} are also left verbatim
 in the output.
+
+If the optional argument @var{split} is non-@code{nil}, instead of
+returning a single string, @code{format-spec} will split the result
+into a list of strings, based on where the substitutions were
+performed.  For instance:
+
+@example
+(format-spec "foo %b bar" '((?b . "zot")) nil t)
+     @result{} ("foo " "zot" " bar")
+@end example
 @end defun
 
 The syntax of format specifications accepted by @code{format-spec} is