[latex3-commits] [git/LaTeX3-latex3-latex3] master: Updated documentation for \str_range:nnn [ci skip] (beaeee9)

[GitHub]

Repository : https://github.com/latex3/latex3
On branch  : master
Link       : https://github.com/latex3/latex3/commit/beaeee9523d364854e09a6668fabc55fc208c9a7

>---------------------------------------------------------------

commit beaeee9523d364854e09a6668fabc55fc208c9a7
Author: Enrico Gregorio <enrico.gregorio at univr.it>
Date:   Mon Dec 17 14:56:12 2018 +0100

    Updated documentation for \str_range:nnn [ci skip]
    
    Updated documentation for \str_range:nnn to match \tl_range:nnn


>---------------------------------------------------------------

beaeee9523d364854e09a6668fabc55fc208c9a7
 l3kernel/l3str.dtx |   48 +++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 43 insertions(+), 5 deletions(-)

diff --git a/l3kernel/l3str.dtx b/l3kernel/l3str.dtx
index 0eb50ae..0b6f024 100644
--- a/l3kernel/l3str.dtx
+++ b/l3kernel/l3str.dtx
@@ -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}