l3kernel (5jan19)

git-svn-id: svn://tug.org/texlive/trunk@49620 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 45 insertions, 7 deletions

diff --git a/Master/texmf-dist/source/latex/l3kernel/l3str.dtx b/Master/texmf-dist/source/latex/l3kernel/l3str.dtx
index 0eb50ae3775..4b8ea892e4c 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3str.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3str.dtx
@@ -1,6 +1,6 @@
 % \iffalse meta-comment
 %
-%% File: l3str.dtx Copyright (C) 2011-2018 The LaTeX3 Project
+%% File: l3str.dtx Copyright (C) 2011-2019 The LaTeX3 Project
 %
 % It may be distributed and/or modified under the conditions of the
 % LaTeX Project Public License (LPPL), either version 1.3c of this
@@ -41,7 +41,7 @@
 %    }^^A
 % }
 %
-% \date{Released 2018-12-12}
+% \date{Released 2019-01-01}
 %
 % \maketitle
 %
@@ -614,11 +614,23 @@
 %   \end{syntax}
 %   Converts the \meta{token list} to a \meta{string}, and leaves in the
 %   input stream the characters from the \meta{start index} to the
-%   \meta{end index} inclusive.  Positive \meta{indices} are counted
-%   from the start of the string, $1$~being the first character, and
-%   negative \meta{indices} are counted from the end of the string,
-%   $-1$~being the last character.  If either of \meta{start index} or
-%   \meta{end index} is~$0$, the result is empty.  For instance,
+%   \meta{end index} inclusive.  Spaces are preserved and counted as items
+%   (contrast this with \cs{tl_range:nnn} where spaces are not counted as
+%   items and are possibly discarded from the output).
+%
+%   Here \meta{start index} and \meta{end index} should be integer denotations.
+%   For describing in detail the functions' behavior, let $m$ and $n$ be the start
+%   and end index respectively. If either is $0$, the result is empty. A positive
+%   index means `start counting from the left end', a negative index means
+%   `start counting from the right end'. Let $l$ be the count of the token list.
+%
+%   The \emph{actual start point} is determined as $M=m$ if~$m>0$ and as $M=l+m+1$
+%   if~$m<0$. Similarly the \emph{actual end point} is $N=n$ if~$n>0$ and $N=l+n+1$
+%   if~$n<0$. If $M>N$, the result is empty. Otherwise it consists of all items from
+%   position $M$ to position $N$ inclusive; for the purpose of this rule, we can
+%   imagine that the token list extends at infinity on either side, with void items
+%   at positions $s$ for $s\le0$ or $s>l$.
+%   For instance,
 %   \begin{verbatim}
 %     \iow_term:x { \str_range:nnn { abcdef } { 2 } { 5 } }
 %     \iow_term:x { \str_range:nnn { abcdef } { -4 } { -1 } }
@@ -634,6 +646,32 @@
 %     \iow_term:x { \str_range:nnn { abcdef } { -1 } { -4 } }
 %   \end{verbatim}
 %   both yield empty strings.
+%
+%   The behavior of \cs{str_range_ignore_spaces:nnn} is similar, but spaces
+%   are removed before starting the job. The input
+%   \begin{verbatim}
+%     \iow_term:x { \str_range:nnn { abcdefg } { 2 } { 5 } }
+%     \iow_term:x { \str_range:nnn { abcdefg } { 2 } { -3 } }
+%     \iow_term:x { \str_range:nnn { abcdefg } { -6 } { 5 } }
+%     \iow_term:x { \str_range:nnn { abcdefg } { -6 } { -3 } }
+%
+%     \iow_term:x { \str_range:nnn { abc~efg } { 2 } { 5 } }
+%     \iow_term:x { \str_range:nnn { abc~efg } { 2 } { -3 } }
+%     \iow_term:x { \str_range:nnn { abc~efg } { -6 } { 5 } }
+%     \iow_term:x { \str_range:nnn { abc~efg } { -6 } { -3 } }
+%
+%     \iow_term:x { \str_range_ignore_spaces:nnn { abcdefg } { 2 } { 5 } }
+%     \iow_term:x { \str_range_ignore_spaces:nnn { abcdefg } { 2 } { -3 } }
+%     \iow_term:x { \str_range_ignore_spaces:nnn { abcdefg } { -6 } { 5 } }
+%     \iow_term:x { \str_range_ignore_spaces:nnn { abcdefg } { -6 } { -3 } }
+%
+%     \iow_term:x { \str_range_ignore_spaces:nnn { abcd~efg } { 2 } { 5 } }
+%     \iow_term:x { \str_range_ignore_spaces:nnn { abcd~efg } { 2 } { -3 } }
+%     \iow_term:x { \str_range_ignore_spaces:nnn { abcd~efg } { -6 } { 5 } }
+%     \iow_term:x { \str_range_ignore_spaces:nnn { abcd~efg } { -6 } { -3 } }
+%   \end{verbatim}
+%   will print four instances of |bcde|, four instances of |bc e| and eight
+%   instances of |bcde|.
 % \end{function}
 %
 % \section{String manipulation}