summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/expl3/l3candidates.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/expl3/l3candidates.dtx')
-rw-r--r--Master/texmf-dist/source/latex/expl3/l3candidates.dtx163
1 files changed, 91 insertions, 72 deletions
diff --git a/Master/texmf-dist/source/latex/expl3/l3candidates.dtx b/Master/texmf-dist/source/latex/expl3/l3candidates.dtx
index 4062f8828c6..842adff6471 100644
--- a/Master/texmf-dist/source/latex/expl3/l3candidates.dtx
+++ b/Master/texmf-dist/source/latex/expl3/l3candidates.dtx
@@ -1,5 +1,5 @@
% \iffalse
-%% File: l3candidates.dtx Copyright (C) 2005-2010 LaTeX3 project
+%% File: l3candidates.dtx Copyright (C) 2005-2011 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
@@ -37,7 +37,7 @@
%</driver|package>
%\fi
\errorcontextlines=999
-\GetIdInfo$Id: l3candidates.dtx 2137 2011-01-23 23:13:58Z will $
+\GetIdInfo$Id: l3candidates.dtx 2179 2011-03-06 09:06:18Z mittelba $
{L3 Experimental 'extras' module}
%\iffalse
%<*driver>
@@ -192,24 +192,40 @@
%
%
%
-% \begin{function}{\clist_length:N / (EXP)|\clist_length:n / (EXP)}
-% \begin{syntax}
-% "\clist_length:N" <clist>
-% \end{syntax}
-% Expands to the number of elements in the <clist>.
-% \end{function}
-%
-% \begin{function}{\clist_element:Nn / (EXP)|\clist_element:nn / (EXP)}
-% \begin{syntax}
-% "\clist_element:Nn" <clist> \Arg{i}
-% "\clist_element:nn" |{| <c0>|,| <c1>|,|\dots|,| <c$_{n-\1}$>|,| <c$_n$> |}| \Arg{i}
-% "\clist_element:nn" |{| <c$_{-n-\1}$>|,| <c$_{-n}$>|,|\dots|,| <c$_{-\2}$>|,| <c$_{-\1}$> |}| \Arg{i}
-% \end{syntax}
-% Expands to <c$_i$>, the <i>-th element of the <clist>.
-% The indexing counts from zero, and negative indices count from the end.
-% (Negative indexing is slightly less efficent since the length of the list
-% must first be calculated.)
-% \end{function}
+%\begin{function}{
+% \clist_length:N / (EXP) |
+% \clist_length:c / (EXP) |
+% \clist_length:n / (EXP) |
+%}
+% \begin{syntax}
+% \cs{clist_length:N} \Arg{comma-list}
+% \end{syntax}
+% Counts the number of \meta{elements} in the \Arg{comma-list} and
+% leaves this information in the input stream. The number of
+% \meta{elements} will be one more than the number of unbraced
+% \verb"," tokens of category code \( 12 \) (other) within the
+% \meta{comma-list}. This function requires two expansions,
+% giving an \meta{integer denotation}.
+%\end{function}
+%
+%\begin{function}{
+% \clist_item:Nn / (EXP) |
+% \clist_item:cn / (EXP) |
+% \clist_item:nn / (EXP) |
+%}
+% \begin{syntax}
+% \cs{clist_item:Nn} \Arg{comma-list} \Arg{offset}
+% \end{syntax}
+% Locates the \meta{element} in the \meta{comma-list} with the
+% \meta{offset} specified, and leaves the result in the input stream.
+% The \meta{offset} should be an integer expression, and is the number
+% of places from the start of the list at which the \meta{element} is
+% located. The there is no \meta{element} with the \meta{offset}
+% specified then the full expansion of the function will be empty.
+% Negative \meta{offset} values work from the end of the
+% \meta{comma-list}, such that and \meta{meta} of \( -1 \) will
+% leave the last item of the \meta{comma-list} in the input stream.
+%\end{function}
%
%
%
@@ -393,67 +409,70 @@
% \end{macrocode}
% \end{macro}
%
-%
-%
-% \begin{macro}{\clist_length:N,\clist_length:n}
+%\begin{macro}{\clist_length:N}
+%\begin{macro}{\clist_length:c}
+%\begin{macro}{\clist_length:n}
+% Counting the elements in a comma-list is straight-forward, using the
+% same approach as for other lists of tokens.
% \begin{macrocode}
-\cs_new:Npn \clist_length:N {
- \exp_args:No \clist_length:n
+\cs_new_nopar:Npn \clist_length:N #1 {
+ \tex_number:D \etex_numexpr:D
+ 0
+ \clist_map_function:NN #1 \tl_elt_count_aux:n
+ \scan_stop:
}
-\cs_new:Npn \clist_length:n #1 {
- \int_eval:n {
- 0 \clist_map_function:nN {#1} \tl_elt_count_aux:n
- }
+\cs_generate_variant:Nn \clist_length:N { c }
+\cs_new_nopar:Npn \clist_length:n #1 {
+ \tex_number:D \etex_numexpr:D
+ 0
+ \clist_map_function:nN {#1} \tl_elt_count_aux:n
+ \scan_stop:
}
% \end{macrocode}
-% \end{macro}
-%
-%
-% \begin{macro}{\clist_element:Nn,\clist_element:nn}
+%\end{macro}
+%\end{macro}
+%\end{macro}
+%
+%\begin{macro}{\clist_item:Nn}
+%\begin{macro}{\clist_item:cn}
+%\begin{macro}{\clist_item:nn}
+%\begin{macro}[aux]{\clist_element_aux:nw}
+% Recovering an item from a list is indexed from \( 0 \), with negative
+% numbers meaning ``from the end of the list''. So the first test
+% discriminates the two cases. For negative numbers, there is therefore
+% a need to know the number of items in the list before doing the
+% second phase, a recursion which will give an empty result if the
+% number is too big.
% \begin{macrocode}
-\cs_new:Npn \clist_element:Nn #1 {
- \exp_args:No \clist_element:nn #1
+\cs_new_nopar:Npn \clist_item:Nn #1#2 {
+ \exp_args:No \clist_item:nn {#1} {#2}
}
-\cs_new:Npn \clist_element:nn #1#2 {
-% \end{macrocode}
-% When negative indexing is used, calculate the length and subtract.
-% This incurs a minor performance penalty, of course, but it's nothing to
-% worry about.
-% \begin{macrocode}
- \int_compare:nNnTF {#2} < {0}
- {
- \exp_args:Nf \clist_element_aux:nw
- {\clist_length:n {#1}+#2} #1 , \q_recursion_tail , \q_recursion_stop
- }
- {
- \clist_element_aux:nw {#2} #1 , \q_recursion_tail , \q_recursion_stop
- }
-% \end{macrocode}
-% Shorter but less readable version of the code block above:
-% \begin{verbatim}
-% \exp_args:Nf \clist_element_aux:nnw
-% { #2 \int_compare:nNnT {#2} < {0} { +\clist_length:n {#1} } }
-% #1 , \q_recursion_tail , \q_recursion_stop
-% \end{verbatim}
-% Note in both cases I've used |\exp_args:Nf| directly, since I'm starting
-% to think that adding too many control sequences is bad for \TeX's
-% performance.
-% \begin{macrocode}
+\cs_generate_variant:Nn \clist_item:Nn { c }
+\cs_new:Npn \clist_item:nn #1#2 {
+ \int_compare:nNnTF {#2} < { 0 }
+ {
+ \exp_args:Nf \clist_item_aux:nw
+ { \clist_length:n {#1} + #2 }
+ #1 , \q_recursion_tail \q_recursion_stop
+ }
+ {
+ \clist_item_aux:nw {#2} #1
+ , \q_recursion_tail \q_recursion_stop
+ }
}
-\cs_new:Npn \clist_element_aux:nw #1#2, {
- \quark_if_recursion_tail_stop:n {#2}
- \int_compare:nNnTF {#1} = {0}
- {
- \use_i_delimit_by_q_recursion_stop:nw {#2}
- }
- {
- \clist_element_aux:nw {#1-1}
- }
+\cs_new:Npn \clist_item_aux:nw #1#2 , #3 {
+ \int_compare:nNnTF {#1} = { 0 }
+ { \use_i_delimit_by_q_recursion_stop:nw {#2} }
+ {
+ \quark_if_recursion_tail_stop:n {#3}
+ \clist_item_aux:nw { #1 - 1 } #3
+ }
}
% \end{macrocode}
-% \end{macro}
-%
-%
+%\end{macro}
+%\end{macro}
+%\end{macro}
+%\end{macro}
%
%
% \begin{macrocode}