summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2023-10-24 17:51:37 +0000
committerKarl Berry <karl@freefriends.org>2023-10-24 17:51:37 +0000
commit0bfadba8b4e7062c64d16b4ff197dd8adaa54be5 (patch)
tree1b646413f7f5827654e1c48ff82bf11c061dfa7d /Master/texmf-dist/source/latex/l3kernel/l3fp.dtx
parent640cf00679c57a79632e597d833d3197aeb9e045 (diff)
l3kernel (23oct23)
git-svn-id: svn://tug.org/texlive/trunk@68632 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3fp.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3fp.dtx136
1 files changed, 134 insertions, 2 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx b/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx
index 60a7b7534fd..578d568978f 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx
@@ -49,7 +49,7 @@
% }^^A
% }
%
-% \date{Released 2023-10-10}
+% \date{Released 2023-10-23}
%
% \maketitle
%
@@ -658,6 +658,138 @@
% the \meta{code} should make use of the \meta{tl~var}.
% \end{function}
%
+% \section{Symbolic expressions}
+%
+% Floating point expressions support variables: these can only be set locally,
+% so act like standard \cs[no-index]{l_\dots} variables.
+% \begin{quote}\let\obeyedline=\newline\obeylines^^A
+% \cs{fp_new_variable:n} |{ A }|
+% \cs{fp_set:Nn} \cs{l_tmpb_fp} |{ 1 * sin(A) + 3**2 }|
+% \cs{fp_show:n} |{| \cs{l_tmpb_fp} |}|
+% \cs{fp_show:N} \cs{l_tmpb_fp}
+% \cs{fp_set_variable:nn} |{ A }| |{ pi/2 }|
+% \cs{fp_show:n} |{| \cs{l_tmpb_fp} |}|
+% \cs{fp_show:N} \cs{l_tmpb_fp}
+% \cs{fp_set_variable:nn} |{ A }| |{ 0 }|
+% \cs{fp_show:n} |{| \cs{l_tmpb_fp} |}|
+% \cs{fp_show:N} \cs{l_tmpb_fp}
+% \end{quote}
+% defines~|A| to be a variable, then defines \cs{l_tmpb_fp} to stand for
+% |1*sin(A)+9| (note that |3**2| is evaluated, but the |1*|~product is
+% not simplified away). Until \cs{l_tmpb_fp} is changed, \cs{fp_show:N}
+% \cs{l_tmpb_fp} will show |((1*sin(A))+9)| regardless of the value
+% of~|A|. The next step defines~|A| to be equal to~|pi/2|: then
+% \cs{fp_show:n} |{| \cs{l_tmpb_fp} |}| will evaluate \cs{l_tmpb_fp} and
+% show~|10|. We then redefine~|A| to be~|0|: since \cs{l_tmpb_fp} still
+% stands for |1*sin(A)+9|, the value shown is then~|9|. Variables can
+% be set with \cs{fp_set_variable:nn} to arbitrary floating point
+% expressions including other variables.
+%
+% \begin{function}[added = 2023-10-19]{\fp_new_variable:n}
+% \begin{syntax}
+% \cs{fp_new_variable:n} \Arg{identifier}
+% \end{syntax}
+% Declares the \meta{identifier} as a variable, which allows it to be
+% used in floating point expressions. For instance,
+% \begin{quote}
+% \cs{fp_new_variable:n} |{ A }| \\
+% \cs{fp_show:n} |{ A**2 - A + 1 }|
+% \end{quote}
+% shows |(((A^2)-A)+1)|. If the declaration was missing, the parser
+% would complain about an \enquote{\texttt{Unknown fp word 'A'}}. The
+% \meta{identifier} must consist entirely of Latin letters among
+% |[a-zA-Z]|.
+% \end{function}
+%
+% \begin{function}[added = 2023-10-19]{\fp_set_variable:nn}
+% \begin{syntax}
+% \cs{fp_set_variable:nn} \Arg{identifier} \Arg{fp expr}
+% \end{syntax}
+% Defines the \meta{identifier} to stand in any further expression for
+% the result of evaluating the \meta{floating point expression} as
+% much as possible. The result may contain other variables, which are
+% then replaced by their values if they have any. For instance,
+% \begin{quote}\let\obeyedline=\newline\obeylines^^A
+% \cs{fp_new_variable:n} |{ A }|
+% \cs{fp_new_variable:n} |{ B }|
+% \cs{fp_new_variable:n} |{ C }|
+% \cs{fp_set_variable:nn} |{ A } { 3 }|
+% \cs{fp_set_variable:nn} |{ C } { A ** 2 + B * 1 }|
+% \cs{fp_show:n} |{ C + 4 }|
+% \cs{fp_set_variable:nn} |{ A } { 4 }|
+% \cs{fp_show:n} |{ C + 4 }|
+% \end{quote}
+% shows |((9+(B*1))+4)| twice: changing the value of~|A| to~|4| does
+% not alter~|C| because |A|~was replaced by its value~|3| when
+% evaluating |A**2+B*1|.
+% \end{function}
+%
+% \begin{function}[added = 2023-10-19]{\fp_clear_variable:n}
+% \begin{syntax}
+% \cs{fp_clear_variable:n} \Arg{identifier}
+% \end{syntax}
+% Removes any value given by \cs{fp_set_variable:nn} to the variable
+% with this \meta{identifier}. For instance,
+% \begin{quote}\let\obeyedline=\newline\obeylines^^A
+% \cs{fp_new_variable:n} |{ A }|
+% \cs{fp_set_variable:nn} |{ A } { 3 }|
+% \cs{fp_show:n} |{ A ^ 2 }|
+% \cs{fp_clear_variable:n} |{ A }|
+% \cs{fp_show:n} |{ A ^ 2 }|
+% \end{quote}
+% shows~|9|, then~|(A^2)|.
+% \end{function}
+%
+% \section{User-defined functions}
+%
+% It is possible to define new user functions which can be used inside
+% the argument to \cs{fp_eval:n}, etc. These functions may take one or
+% more named arguments, and should be implemented using expansion methods
+% only.
+%
+% \begin{function}[added = 2023-10-19]{\fp_new_function:n}
+% \begin{syntax}
+% \cs{fp_new_function:n} \Arg{identifier}
+% \end{syntax}
+% Declares the \meta{identifier} as a function, which allows it to be
+% used in floating point expressions. For instance,
+% \begin{quote}
+% \cs{fp_new_function:n} |{ foo }| \\
+% \cs{fp_show:n} |{ foo ( 1 + 2 , foo(3), A ) ** 2 } }|
+% \end{quote}
+% shows |(foo(3, foo(3), A))^(2)|. If the declaration was missing,
+% the parser would complain about an \enquote{\texttt{Unknown fp word 'foo'}}.
+% The \meta{identifier} must consist entirely of Latin letters |[a-zA-Z]|.
+% \end{function}
+%
+% \begin{function}[added = 2023-10-19]{\fp_set_function:nnn}
+% \begin{syntax}
+% \cs{fp_set_function:nnn} \Arg{identifier} \Arg{vars} \Arg{fp expr}
+% \end{syntax}
+% Defines the \meta{identifier} to stand in any further expression for
+% the result of evaluating the \meta{floating point expression}, with
+% the \meta{identifier} accepting the \meta{vars} (a comma list).
+% The result may contain other functions, which are
+% then replaced by their results if they have any. For instance,
+% \begin{quote}
+% \cs{fp_new_function:n} |{ foo }| \\
+% \cs{fp_set_function:nnn} |{ npow } { a,b } { a**b }| \\
+% \cs{fp_show:n} |{ npow(16,0.25) } }|
+% \end{quote}
+% shows |2|. The names of the \meta{vars} must
+% consist entirely of Latin letters |[a-zA-Z]|, but are otherwise not
+% restricted: in particular, they are independent of any variables
+% declared by \cs{fp_new_variable:n}.
+% \end{function}
+%
+% \begin{function}[added = 2023-10-19]{\fp_clear_function:n}
+% \begin{syntax}
+% \cs{fp_clear_function:n} \Arg{identifier}
+% \end{syntax}
+% Removes any definition given by \cs{fp_set_function:nnn} to the function
+% with this \meta{identifier}.
+% \end{function}
+%
% \section{Some useful constants, and scratch variables}
%
% \begin{variable}[added = 2012-05-08, module = fp]{\c_zero_fp, \c_minus_zero_fp}
@@ -1417,7 +1549,7 @@
% \begin{function}[EXP, added = 2012-09-26, tested = m3fp-convert003]
% {\fp_max:nn, \fp_min:nn}
% \begin{syntax}
-% \cs{fp_max:nn} \Arg{fp expression 1} \Arg{fp expression 2}
+% \cs{fp_max:nn} \Arg{fp expr_1} \Arg{fp expr_2}
% \end{syntax}
% Evaluates the \meta{fp exprs} as described for
% \cs{fp_eval:n} and leaves the resulting larger (\texttt{max}) or