From 8f9c0c18438f850a16d9aaa1560a81860ffff810 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mattias=20Engdeg=C3=A5rd?= Date: Sat, 27 Dec 2025 19:01:16 +0100 Subject: [PATCH] Don't use the term 'null' for empty strings Zero-length strings are just 'empty'; 'null' can be confusing in several ways. * lisp/subr.el (split-string, string-lines): * doc/lispref/strings.texi (Creating Strings): Change argument names from 'omit-nulls' to 'omit-empty'. --- doc/lispref/strings.texi | 16 ++++++++-------- lisp/subr.el | 24 ++++++++++-------------- test/lisp/subr-tests.el | 2 +- 3 files changed, 19 insertions(+), 23 deletions(-) diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 0d340c35e32..7481c4e3caf 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -289,7 +289,7 @@ string to be used as a shell command, see @ref{Shell Arguments, combine-and-quote-strings}. @end defun -@defun split-string string &optional separators omit-nulls trim +@defun split-string string &optional separators omit-empty trim This function splits @var{string} into substrings based on the regular expression @var{separators} (@pxref{Regular Expressions}). Each match for @var{separators} defines a splitting point; the substrings between @@ -297,18 +297,18 @@ splitting points are made into a list, which is returned. If @var{separators} is @code{nil} (or omitted), the default is the value of @code{split-string-default-separators} and the function -behaves as if @var{omit-nulls} were @code{t}. +behaves as if @var{omit-empty} were @code{t}. -If @var{omit-nulls} is @code{nil} (or omitted), the result contains -null strings whenever there are two consecutive matches for +If @var{omit-empty} is @code{nil} (or omitted), the result contains +empty strings whenever there are two consecutive matches for @var{separators}, or a match is adjacent to the beginning or end of -@var{string}. If @var{omit-nulls} is @code{t}, these null strings are +@var{string}. If @var{omit-empty} is @code{t}, these empty strings are omitted from the result. If the optional argument @var{trim} is non-@code{nil}, it should be a regular expression to match text to trim from the beginning and end of each substring. Trimming may make the substring empty and omitted from -the result if @var{omit-nulls} is @code{t} as above. +the result if @var{omit-empty} is @code{t} as above. If you need to split a string into a list of individual command-line arguments suitable for @code{call-process} or @code{start-process}, @@ -387,9 +387,9 @@ display purposes; use @code{truncate-string-to-width} or (@pxref{Size of Displayed Text}). @end defun -@defun string-lines string &optional omit-nulls keep-newlines +@defun string-lines string &optional omit-empty keep-newlines Split @var{string} into a list of strings on newline boundaries. If -the optional argument @var{omit-nulls} is non-@code{nil}, remove empty +the optional argument @var{omit-empty} is non-@code{nil}, remove empty lines from the results. If the optional argument @var{keep-newlines} is non-@code{nil}, don't remove the trailing newlines from the result strings. diff --git a/lisp/subr.el b/lisp/subr.el index 81dbaaaa69e..ef23bf97b8c 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -5867,11 +5867,7 @@ A regexp matching strings of whitespace. May be locale-dependent Warning: binding this to a different value and using it as default is likely to have undesired semantics.") -;; The specification says that if both SEPARATORS and OMIT-NULLS are -;; defaulted, OMIT-NULLS should be treated as t. Simplifying the logical -;; expression leads to the equivalent implementation that if SEPARATORS -;; is defaulted, OMIT-NULLS is treated as t. -(defun split-string (string &optional separators omit-nulls trim) +(defun split-string (string &optional separators omit-empty trim) "Split STRING into substrings bounded by matches for SEPARATORS. The beginning and end of STRING, and each match for SEPARATORS, are @@ -5882,17 +5878,17 @@ which is returned. If SEPARATORS is non-nil, it should be a regular expression matching text that separates, but is not part of, the substrings. If omitted or nil, it defaults to `split-string-default-separators', whose value is -normally \"[ \\f\\t\\n\\r\\v]+\", and OMIT-NULLS is then forced to t. +normally \"[ \\f\\t\\n\\r\\v]+\", and OMIT-EMPTY is then forced to t. SEPARATORS should never be a regexp that matches the empty string. -If OMIT-NULLS is t, zero-length substrings are omitted from the list (so +If OMIT-EMPTY is t, zero-length substrings are omitted from the list (so that for the default value of SEPARATORS leading and trailing whitespace are effectively trimmed). If nil, all 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 the substring empty, it is treated as null. +makes the substring empty and OMIT-EMPTY is t, it is dropped from the result. Note that the effect of `(split-string STRING)' is the same as `(split-string STRING split-string-default-separators t)'. In the rare @@ -5901,7 +5897,7 @@ whitespace, use `(split-string STRING split-string-default-separators)'. Modifies the match data; use `save-match-data' if necessary." (declare (important-return-value t)) - (let* ((keep-empty (and separators (not omit-nulls))) + (let* ((keep-empty (and separators (not omit-empty))) (len (length string)) (trim-left-re (and trim (concat "\\`\\(?:" trim "\\)"))) (trim-right-re (and trim (concat "\\(?:" trim "\\)\\'"))) @@ -7751,14 +7747,14 @@ is inserted before adjusting the number of empty lines." ((< (- (point) start) lines) (insert (make-string (- lines (- (point) start)) ?\n)))))) -(defun string-lines (string &optional omit-nulls keep-newlines) +(defun string-lines (string &optional omit-empty keep-newlines) "Split STRING into a list of lines. -If OMIT-NULLS, empty lines will be removed from the results. +If OMIT-EMPTY, empty lines will be removed from the results. If KEEP-NEWLINES, don't strip trailing newlines from the result lines." (declare (side-effect-free t)) (if (equal string "") - (if omit-nulls + (if omit-empty nil (list "")) (let ((lines nil) @@ -7767,13 +7763,13 @@ lines." (let ((newline (string-search "\n" string start))) (if newline (progn - (when (or (not omit-nulls) + (when (or (not omit-empty) (not (= start newline))) (let ((line (substring string start (if keep-newlines (1+ newline) newline)))) - (when (not (and keep-newlines omit-nulls + (when (not (and keep-newlines omit-empty (equal line "\n"))) (push line lines)))) (setq start (1+ newline))) diff --git a/test/lisp/subr-tests.el b/test/lisp/subr-tests.el index bfad4cf9a44..61ba69ce6fe 100644 --- a/test/lisp/subr-tests.el +++ b/test/lisp/subr-tests.el @@ -1582,7 +1582,7 @@ final or penultimate step during initialization.")) ",+" t "-+") '("A" "B" "C---D"))) - ;; default SEPARATORS forces OMIT-NULLS to `t' + ;; default SEPARATORS forces OMIT-EMPTY to `t' (should (equal (split-string " \nAB\tCDE\f\r\fF \f\v") '("AB" "CDE" "F")))