RE: split-string description in the ELR

[Drew Adams <drew.adams@oracle.com>]

> Without Eli's comment I would never have thought of using split-string to
> trim a string. But even reading the reference did not make it's use super
> clear. In the description "trim" is just an option to trim the substrings
> resulting from splitting the string and it is not obvious that it can be
> used on it's own to trim a given string.
> 
> Could a small modification of the reference be in order to emphasize that
> use (with an example eventually) ?

Good idea.  Additionally, or instead, we could create a function
that is an alias and that has "trim" in the name.

----

FWIW, I define function `split-string-by-regexp' to do just
what vanilla `split-string' does, and I redefine `split-string'
to handle additional ways to specify the splitting.  The
redefined function does `split-string-by-regexp' by default.

Here are the signature and doc string of the redefined `split-string':

(split-string STRING &optional HOW OMIT-NULLS TRIM FLIP TEST)

 Split STRING into substrings.
 Arg HOW determines how splitting is done.  it is one of the following:
 * a regexp (a string) - see function `split-string-by-regexp'
 * a list whose first element is a text property (a symbol) and whose
   second element is the property value - see function
   `split-string-by-property'
 * a predicate that accepts a character as its first argument - see
   function `split-string-by-predicate'

 If optional arg OMIT-NULLS is t, then empty substrings are omitted
 from the returned list.  If nil, zero-length substrings are retained,
 which correctly parses CSV format, for example.

 If TRIM is non-nil, it should be a regular expression to match text to
 trim from the beginning and end of each substring.  If trimming makes
 a substring empty, it is treated according to OMIT-NULLS.

 Optional arg TEST is used only if HOW is a (PROPERTY VALUE) list, in
 which case it is passed to function `split-string-by-property' (which
 see).  Otherwise, it is ignored.

 Modifies the match data; use `save-match-data' if necessary.

Each of the HOW possibilities corresponds also to a separate
function:
 split-string-by-regexp
 split-string-by-property
 split-string-by-predicate

https://www.emacswiki.org/emacs/download/subr%2b.el