summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx126
1 files changed, 95 insertions, 31 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx b/Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx
index c31a0e478de..27baad8b08d 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3candidates.dtx
@@ -36,7 +36,7 @@
%
%<*driver|package>
\RequirePackage{l3bootstrap}
-\GetIdInfo$Id: l3candidates.dtx 4602 2013-11-18 23:19:01Z bruno $
+\GetIdInfo$Id: l3candidates.dtx 4633 2013-12-31 17:28:46Z joseph $
{L3 Experimental additions to l3kernel}
%</driver|package>
%<*driver>
@@ -456,6 +456,76 @@
% before being assigned to the \meta{floating point variable}.
% \end{function}
%
+% \begin{function}[EXP]{\fp_function:Nw}
+% \begin{syntax}
+% \cs{fp_eval:n}
+% ~~|{|
+% ~~~~\cs{fp_function:Nw} \meta{function}
+% ~~~~~~|(| \meta{fpexpr_1} |,| \ldots{} |,| \meta{fpexpr_n} |)|
+% ~~|}|
+% \end{syntax}
+% Finds one or more arguments \meta{fpexpr_1} \ldots{} \meta{fpexpr_n}
+% following the \meta{function}, and evaluate them. Then calls the
+% \meta{function} followed by a single brace group containing
+% \Arg{result_1} \ldots{} \Arg{result_n}. For instance,
+% \begin{verbatim}
+% \cs_new_nopar:Npn \mypkg_log:w
+% { \fp_function:Nw \__mypkg_log:n }
+% \cs_new:Npn \__mypkg_log:n #1
+% {
+% \int_case:nnF { \tl_count:n {#1} }
+% {
+% { 1 } { \__mypkg_log_aux:nn #1 { 10 } }
+% { 2 } { \__mypkg_log_aux:nn #1 }
+% }
+% { \ERROR \c_nan_fp }
+% }
+% \cs_new:Npn \__mypkg_log_aux:nn #1#2 { ln(#1) / ln(#2) }
+% \fp_show:n { \mypkg_log:w (8, 2) + \mypkg_log:w (1e17) }
+% \end{verbatim}
+% shows $20 = \log_2(8) + \log(10^{17})$. The function |\mypkg_log:w|
+% behaves like other built-in functions such as |ln|, but allows $1$
+% or~$2$ arguments, and computes either the base~$10$ logarithm or the
+% logarithm of the first argument in a base given by the second
+% argument. Checking the number of arguments is acheived by
+% |\__mypkg_log:n|, which provides the default base~$10$ when there is
+% only one argument. The computation itself is done by
+% |\__mypkg_log_aux:nn|.
+% \end{function}
+%
+% \begin{function}{\fp_new_function:Npn}
+% \begin{syntax}
+% \cs{fp_new_function:Npn} \meta{function} \meta{parameters} \Arg{code}
+% \cs{fp_eval:n} |{| \meta{function} |(| \meta{fpexpr_1} |,| \ldots{} |,| \meta{fpexpr_n} |)| |}|
+% \end{syntax}
+% Defines the \meta{function} for use within floating point
+% expressions, expecting some \meta{parameters}, and evaluating the
+% \meta{code}, which must be expandable. When the \meta{function}
+% appears in a floating point expression, arguments \meta{fpexpr_1},
+% \ldots{}, \meta{fpexpr_n} are found and evaluated in the same way as
+% for built-in functions such as~|max|. If the number of arguments
+% matches the number of \meta{parameters}, the arguments replace |#1|,
+% \ldots{}, |#|$n$ in the \meta{code}, which is then evaluated to
+% produce a floating point result. Otherwise, the result is
+% \texttt{nan} after an error. The \meta{parameter text} must not
+% contain delimited arguments, that is, it must be empty or one of
+% |#1|, |#1#2|, |#1#2#3|, \ldots{} |#1#2#3#4#5#6#7#8#9|. The
+% arguments replacing parameters in the \meta{code} are internal
+% floating point numbers; operations such as |#1^2| thus correctly
+% take into account the sign of~|#1|. For instance,
+% \begin{verbatim}
+% \fp_new_function:Npn \mypkg_sqrt:w #1 { #1^.5 }
+% \fp_new_function:Npn \mypkg_veclen:w #1#2
+% { \mypkg_sqrt:w ( #1^2 + #2^2 ) }
+% \fp_show:n { \mypkg_veclen:w ( 42 / 7 , 2 * 4 - 0 ) }
+% \end{verbatim}
+% shows~$10$. In the example, |\mypkg_veclen:w| receives the
+% arguments $6=42/7$ and~$8=2\times 4-0$, thus expands to
+% |\mypkg_sqrt:w ( 6^2 + 8^2 )|, then |\mypkg_sqrt:w| receives
+% $100=6^2+8^2$ as an argument, and evaluates the square root $10 =
+% 100^{0.5}$.
+% \end{function}
+%
% \section{Additions to \pkg{l3prop}}
%
% \begin{function}[rEXP]
@@ -2160,9 +2230,8 @@
% key \cs{q_recursion_tail}, which cannot appear in normal keys since
% those are strings. The odd construction |\use:n {#1}| allows |#1|
% to contain any token without interfering with \cs{prop_map_break:}.
-% Argument |#2| of \cs{@@_map_tokens:nwwn} is empty, with two
-% exceptions: it is \cs{s_@@} the first time and \cs{s_obj_end} the
-% last.
+% Argument |#2| of \cs{@@_map_tokens:nwwn} is \cs{s_@@} the first
+% time, and is otherwise empty.
% \begin{macrocode}
\cs_new:Npn \prop_map_tokens:Nn #1#2
{
@@ -2226,8 +2295,9 @@
% then the stop code |{ ? \__prg_break: } { }| will be used by the auxiliary,
% terminating the loop and returning nothing at all.
% \begin{macrocode}
-\cs_new:Npn \seq_item:Nn #1 { \exp_after:wN \@@_item:wNn #1 #1 }
-\cs_new:Npn \@@_item:wNn \s_@@ #1 \s_obj_end #2#3
+\cs_new:Npn \seq_item:Nn #1
+ { \exp_after:wN \@@_item:wNn #1 \q_stop #1 }
+\cs_new:Npn \@@_item:wNn \s_@@ #1 \q_stop #2#3
{
\exp_args:Nf \@@_item:nnn
{
@@ -2260,31 +2330,31 @@
% \seq_mapthread_function:cNN, \seq_mapthread_function:ccN
% }
% \begin{macro}[aux]
-% {\@@_mapthread_function:wNN, \@@_mapthread_function:wNw}
-% \begin{macro}[aux]{\@@_mapthread_function:Nnnwnn}
-% The idea here is to first expand both of the sequences, adding the
+% {\@@_mapthread_function:NNw, \@@_mapthread_function:Nnnwnn}
+% The idea here is to first expand both sequences, adding the
% usual |{ ? \__prg_break: } { }| to the end of each one. This is
% most conveniently done in two steps using an auxiliary function.
% The mapping then throws away the first tokens of |#2| and |#5|,
-% which for items in the sequences will both be \cs{s_@@}
+% which for items in the sequences will both be
% \cs{@@_item:n}. The function to be mapped will then be applied to
% the two entries. When the code hits the end of one of the
-% sequences, the break material will stop the entire loop and tidy up.
-% This avoids needing to find the count of the two sequences, or
+% sequences, \cs{__prg_break:} stops the entire loop and tidy up.
+% This avoids needing to count items in the sequences, or
% worrying about which is longer.
% \begin{macrocode}
\cs_new:Npn \seq_mapthread_function:NNN #1#2#3
- { \exp_after:wN \@@_mapthread_function:wNN #2 #1 #3 }
-\cs_new:Npn \@@_mapthread_function:wNN \s_@@ #1 \s_obj_end #2#3
{
- \exp_after:wN \@@_mapthread_function:wNw #2 #3
- #1 { ? \__prg_break: } { }
+ \exp_after:wN \@@_mapthread_function:NNw
+ \exp_after:wN #3
+ \exp_after:wN #1
+ #2 { ? \__prg_break: } { }
\__prg_break_point:
}
-\cs_new:Npn \@@_mapthread_function:wNw \s_@@ #1 \s_obj_end #2
+\cs_new:Npn \@@_mapthread_function:NNw #1#2
{
- \@@_mapthread_function:Nnnwnn #2
- #1 { ? \__prg_break: } { }
+ \exp_after:wN \@@_mapthread_function:Nnnwnn
+ \exp_after:wN #1
+ #2 { ? \__prg_break: } { }
\q_stop
}
\cs_new:Npn \@@_mapthread_function:Nnnwnn #1#2#3#4 \q_stop #5#6
@@ -2299,7 +2369,6 @@
% \end{macrocode}
% \end{macro}
% \end{macro}
-% \end{macro}
%
% \begin{macro}
% {
@@ -2319,22 +2388,22 @@
\cs_new_protected:Npn \seq_set_from_clist:NN #1#2
{
\tl_set:Nx #1
- { \s_@@ \clist_map_function:NN #2 \@@_wrap_item:n \s_obj_end }
+ { \s_@@ \clist_map_function:NN #2 \@@_wrap_item:n }
}
\cs_new_protected:Npn \seq_set_from_clist:Nn #1#2
{
\tl_set:Nx #1
- { \s_@@ \clist_map_function:nN {#2} \@@_wrap_item:n \s_obj_end }
+ { \s_@@ \clist_map_function:nN {#2} \@@_wrap_item:n }
}
\cs_new_protected:Npn \seq_gset_from_clist:NN #1#2
{
\tl_gset:Nx #1
- { \s_@@ \clist_map_function:NN #2 \@@_wrap_item:n \s_obj_end }
+ { \s_@@ \clist_map_function:NN #2 \@@_wrap_item:n }
}
\cs_new_protected:Npn \seq_gset_from_clist:Nn #1#2
{
\tl_gset:Nx #1
- { \s_@@ \clist_map_function:nN {#2} \@@_wrap_item:n \s_obj_end }
+ { \s_@@ \clist_map_function:nN {#2} \@@_wrap_item:n }
}
\cs_generate_variant:Nn \seq_set_from_clist:NN { Nc }
\cs_generate_variant:Nn \seq_set_from_clist:NN { c , cc }
@@ -2348,9 +2417,8 @@
%
% \begin{macro}
% {\seq_reverse:N, \seq_reverse:c, \seq_greverse:N, \seq_greverse:c}
-% \begin{macro}[aux]{\@@_tmp:w}
% \begin{macro}[aux]{\@@_reverse:NN}
-% \begin{macro}[aux]{\@@_reverse_setup:w, \@@_reverse_item:nwn}
+% \begin{macro}[aux, EXP]{\@@_reverse_item:nwn}
% Previously, \cs{seq_reverse:N} was coded by collecting the items
% in reverse order after an \cs{exp_stop_f:} marker.
% \begin{verbatim}
@@ -2383,7 +2451,6 @@
% of \cs{exp_not:n}. The previous calls are cleanly removed
% from the stack, and the memory consumption becomes linear.
% \begin{macrocode}
-\cs_new_protected_nopar:Npn \@@_tmp:w { }
\cs_new_protected_nopar:Npn \seq_reverse:N
{ \@@_reverse:NN \tl_set:Nx }
\cs_new_protected_nopar:Npn \seq_greverse:N
@@ -2392,11 +2459,9 @@
{
\cs_set_eq:NN \@@_tmp:w \@@_item:n
\cs_set_eq:NN \@@_item:n \@@_reverse_item:nwn
- #1 #2 { \exp_after:wN \@@_reverse_setup:w #2 }
+ #1 #2 { #2 \exp_not:n { } }
\cs_set_eq:NN \@@_item:n \@@_tmp:w
}
-\cs_new:Npn \@@_reverse_setup:w #1 \s_obj_end
- { #1 \exp_not:n { } \s_obj_end }
\cs_new:Npn \@@_reverse_item:nwn #1 #2 \exp_not:n #3
{
#2
@@ -2408,7 +2473,6 @@
% \end{macro}
% \end{macro}
% \end{macro}
-% \end{macro}
%
% \begin{macro}{\seq_set_filter:NNn, \seq_gset_filter:NNn}
% \begin{macro}[aux]{\@@_set_filter:NNNn}