diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/expl3/l3candidates.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/expl3/l3candidates.dtx | 163 |
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} |