[latex3-commits] [git/LaTeX3-latex3-latex3] master: Enhanced documentation for tl_range:nnn [ci skip] (dce27ff)

[GitHub]

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

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

commit dce27ff98aa678b5444aec9dd90f8f8249521a79
Author: Enrico Gregorio <enrico.gregorio at univr.it>
Date:   Tue Dec 4 14:26:38 2018 +0100

    Enhanced documentation for tl_range:nnn [ci skip]
    
    Enhanced the documentation for tl_range:nnn according to https://github.com/latex3/latex3/pull/495#issuecomment-443731312


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

dce27ff98aa678b5444aec9dd90f8f8249521a79
 l3kernel/l3candidates.dtx |   71 +++++++++++++++++++++++++++++++++------------
 1 file changed, 53 insertions(+), 18 deletions(-)

diff --git a/l3kernel/l3candidates.dtx b/l3kernel/l3candidates.dtx
index d051bf6..a740d79 100644
--- a/l3kernel/l3candidates.dtx
+++ b/l3kernel/l3candidates.dtx
@@ -1244,28 +1244,63 @@
 %   \end{syntax}
 %   Leaves in the input stream the items from the \meta{start index} to the
 %   \meta{end index} inclusive.  Spaces and braces are preserved between
-%   the items returned (but never at either end of the list).  Positive
-%   \meta{indices} are counted
-%   from the start of the \meta{token list}, $1$~being the first item, and
-%   negative \meta{indices} are counted from the end of the token list,
-%   $-1$~being the last item.  If either of \meta{start index} or
-%   \meta{end index} is~$0$, the result is empty.  For instance,
+%   the items returned (but never at either end of the list).  
+%
+%   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$.
+
+%   Spaces in between items in the actual range are preserved. Spaces at either end
+%   of the token list will be removed anyway (think to the token list being passed to
+%   |\tl_trim_spaces:n| to begin with.
+%   
+%   Thus, with $l=7$ as in the examples below, all of the following are equivalent
+%   and result in the whole token list
 %   \begin{verbatim}
-%     \iow_term:x { \tl_range:nnn { abcd~{e{}}f } { 2 } { 5 } }
-%     \iow_term:x { \tl_range:nnn { abcd~{e{}}f } { -4 } { -1 } }
-%     \iow_term:x { \tl_range:nnn { abcd~{e{}}f } { -2 } { -1 } }
-%     \iow_term:x { \tl_range:nnn { abcd~{e{}}f } { 0 } { -1 } }
+%     \tl_range:nnn { abcd~{e{}}fg } { 1 } { 7 }
+%     \tl_range:nnn { abcd~{e{}}fg } { 1 } { 12 }
+%     \tl_range:nnn { abcd~{e{}}fg } { -7 } { 7 }
+%     \tl_range:nnn { abcd~{e{}}fg } { -12 } { 7 }
 %   \end{verbatim}
-%   prints \verb*|bcd {e{}}|, \verb*|cd {e{}}f|, \verb*|{e{}}f| and an empty
-%   line to the terminal. The \meta{start index} must always be smaller than
-%   or equal to the \meta{end index}: if this is not the case then no output
-%   is generated. Thus
+%   Here are some more interesting examples. The calls
 %   \begin{verbatim}
-%     \iow_term:x { \tl_range:nnn { abcd~{e{}}f } { 5 } { 2 } }
-%     \iow_term:x { \tl_range:nnn { abcd~{e{}}f } { -1 } { -4 } }
+%     \iow_term:x { \tl_range:nnn { abcd{e{}}fg } { 2 } { 5 } }
+%     \iow_term:x { \tl_range:nnn { abcd{e{}}fg } { 2 } { -3 } }
+%     \iow_term:x { \tl_range:nnn { abcd{e{}}fg } { -6 } { 5 } }
+%     \iow_term:x { \tl_range:nnn { abcd{e{}}fg } { -6 } { -3 } }
 %   \end{verbatim}
-%   both yield empty token lists.  For improved performance, see
-%   \cs{tl_range_braced:nnn} and \cs{tl_range_unbraced:nnn}.
+%   are all equivalent and will print |bcd{e{}}| on the terminal; similarly
+%   \begin{verbatim}
+%     \iow_term:x { \tl_range:nnn { abcd~{e{}}fg } { 2 } { 5 } }
+%     \iow_term:x { \tl_range:nnn { abcd~{e{}}fg } { 2 } { -3 } }
+%     \iow_term:x { \tl_range:nnn { abcd~{e{}}fg } { -6 } { 5 } }
+%     \iow_term:x { \tl_range:nnn { abcd~{e{}}fg } { -6 } { -3 } }
+%   \end{verbatim}
+%   are all equivalent and will print |bcd {e{}}| on the
+%   terminal (note the space in the middle). To the contrary,
+%   \begin{verbatim}
+%     \tl_range:nnn { abcd~{e{}}f } { 2 } { 4 }
+%   \end{verbatim}
+%   will discard the space after `d`.
+%   
+%   If we want to get the items from the third to the last, the call
+%   is |\tl_range:nnn { <tl> } { 3 } { -1 }|. Similarly, for discarding
+%   the last item, we can do |\tl_range:nnn { <tl> } { 1 } { -2 }|.
+%   
+%   The behavior of \cs{tl_range:Nnn} is exactly the same, acting on the
+%   contents of the tl variable.
+%   
+%   For improved performance, see  \cs{tl_range_braced:nnn} and
+%   \cs{tl_range_unbraced:nnn}.
 %   \begin{texnote}
 %     The result is returned within the \tn{unexpanded}
 %     primitive (\cs{exp_not:n}), which means that the \meta{item}