summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2012-08-31 17:58:55 +0000
committerKarl Berry <karl@freefriends.org>2012-08-31 17:58:55 +0000
commit3301423440393adfdbbcfa0d8471e4b4c63df1e6 (patch)
tree6aa86f66a252f654a2bd2f28ee7b680fdac1b0a3 /Master/texmf-dist/source/latex/l3kernel/l3fp.dtx
parenta511edd7e6a05e250f2b2d8062a470734e3af33d (diff)
l3kernel 3160 (31aug12)
git-svn-id: svn://tug.org/texlive/trunk@27559 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.dtx422
1 files changed, 270 insertions, 152 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx b/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx
index 059ca848304..5cf7c0ccf91 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx
@@ -36,19 +36,22 @@
%
%<*driver|package>
\RequirePackage{l3bootstrap}
-\GetIdInfo$Id: l3fp.dtx 4089 2012-08-14 04:52:20Z bruno $
+\GetIdInfo$Id: l3fp.dtx 4151 2012-08-28 11:51:52Z bruno $
{L3 Floating points}
%</driver|package>
%<*driver>
\documentclass[full]{l3doc}
\usepackage{amsmath}
-\providecommand\nan{\texttt{NaN}}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
+% ^^A need to provide this inside the file:
+%
+% \providecommand\nan{\texttt{NaN}}
+%
%
% \title{^^A
% The \textsf{l3fp} package: floating points^^A
@@ -71,7 +74,7 @@
%
% \begin{documentation}
%
-% A decimal floating point number is one which is stored as a mantissa and a
+% A decimal floating point number is one which is stored as a significand and a
% separate exponent. The module implements expandably a wide set of
% arithmetic, trigonometric, and other operations on decimal floating point
% numbers, to be used within floating point expressions. Floating point
@@ -87,8 +90,8 @@
% $x\mathop{\&\&}y$, disjunction $x\mathop{\vert\vert}y$, ternary
% operator $x\mathop{?}y\mathop{:}z$.
% \item Exponentials: $\exp x$, $\ln x$, $x^y$.
-% \item Trigonometry: $\sin x$, $\cos x$, $\tan x$, $\cot x$.
-% \emph{Not yet:} $\sec x$, $\csc x$.
+% \item Trigonometry: $\sin x$, $\cos x$, $\tan x$, $\cot x$, $\sec
+% x$, $\csc x$.
% \item [\emph{(not yet)}] Inverse trigonometric functions:
% $\operatorname{asin} x$, $\operatorname{acos} x$,
% $\operatorname{atan} x$, $\operatorname{acot} x$,
@@ -181,7 +184,7 @@
%
% \section{Setting floating point variables}
%
-% \begin{function}[updated = 2012-05-08]
+% \begin{function}[updated = 2012-05-08, tested = m3fp002]
% {\fp_set:Nn, \fp_set:cn, \fp_gset:Nn, \fp_gset:cn}
% \begin{syntax}
% \cs{fp_set:Nn} \meta{fp~var} \Arg{floating point expression}
@@ -190,7 +193,7 @@
% \meta{floating point expression}.
% \end{function}
%
-% \begin{function}[updated = 2012-05-08]
+% \begin{function}[updated = 2012-05-08, tested = m3fp002]
% {
% \fp_set_eq:NN , \fp_set_eq:cN , \fp_set_eq:Nc , \fp_set_eq:cc ,
% \fp_gset_eq:NN, \fp_gset_eq:cN, \fp_gset_eq:Nc, \fp_gset_eq:cc
@@ -202,7 +205,7 @@
% value of \meta{fp~var_2}.
% \end{function}
%
-% \begin{function}[updated = 2012-05-08]
+% \begin{function}[updated = 2012-05-08, tested = m3fp002]
% {\fp_add:Nn, \fp_add:cn, \fp_gadd:Nn, \fp_gadd:cn}
% \begin{syntax}
% \cs{fp_add:Nn} \meta{fp~var} \Arg{floating point expression}
@@ -211,7 +214,7 @@
% the \meta{fp~var}.
% \end{function}
%
-% \begin{function}[updated = 2012-05-08]
+% \begin{function}[updated = 2012-05-08, tested = m3fp002]
% {\fp_sub:Nn, \fp_sub:cn, \fp_gsub:Nn, \fp_gsub:cn}
% \begin{syntax}
% \cs{fp_sub:Nn} \meta{fp~var} \Arg{floating point expression}
@@ -222,7 +225,8 @@
%
% \section{Using floating point numbers}
%
-% \begin{function}[EXP, added = 2012-05-08, updated = 2012-07-08]{\fp_eval:n}
+% \begin{function}[EXP, added = 2012-05-08, updated = 2012-07-08,
+% tested = m3fp-convert003]{\fp_eval:n}
% \begin{syntax}
% \cs{fp_eval:n} \Arg{floating point expression}
% \end{syntax}
@@ -231,11 +235,12 @@
% exponent. Leading or trailing zeros may be inserted to compensate
% for the exponent. Non-significant trailing zeros are trimmed, and
% integers are expressed without a decimal separator. The values
-% $\pm\infty$ and \texttt{nan} trigger an \enquote{invalid operation}
+% $\pm\infty$ and \nan{} trigger an \enquote{invalid operation}
% exception. This function is identical to \cs{fp_to_decimal:n}.
% \end{function}
%
-% \begin{function}[EXP, added = 2012-05-08, updated = 2012-07-08]
+% \begin{function}[EXP, added = 2012-05-08, updated = 2012-07-08,
+% tested = m3fp-convert003]
% {\fp_to_decimal:N, \fp_to_decimal:c, \fp_to_decimal:n}
% \begin{syntax}
% \cs{fp_to_decimal:N} \meta{fp~var}
@@ -246,11 +251,11 @@
% exponent. Leading or trailing zeros may be inserted to compensate
% for the exponent. Non-significant trailing zeros are trimmed, and
% integers are expressed without a decimal separator. The values
-% $\pm\infty$ and \texttt{nan} trigger an \enquote{invalid operation}
+% $\pm\infty$ and \nan{} trigger an \enquote{invalid operation}
% exception.
% \end{function}
%
-% \begin{function}[EXP, updated = 2012-07-08]
+% \begin{function}[EXP, updated = 2012-07-08, tested = m3fp-convert003]
% {\fp_to_dim:N, \fp_to_dim:c, \fp_to_dim:n}
% \begin{syntax}
% \cs{fp_to_dim:N} \meta{fp~var}
@@ -262,11 +267,11 @@
% an additional trailing \texttt{pt}. In particular, the result may
% be outside the range $[- 2^{14} + 2^{-17}, 2^{14} - 2^{-17}]$ of
% valid \TeX{} dimensions, leading to overflow errors if used as a
-% dimension. The values $\pm\infty$ and \texttt{nan} trigger an
+% dimension. The values $\pm\infty$ and \nan{} trigger an
% \enquote{invalid operation} exception.
% \end{function}
%
-% \begin{function}[EXP, updated = 2012-07-08]
+% \begin{function}[EXP, updated = 2012-07-08, tested = m3fp-convert003]
% {\fp_to_int:N, \fp_to_int:c, \fp_to_int:n}
% \begin{syntax}
% \cs{fp_to_int:N} \meta{fp~var}
@@ -276,11 +281,12 @@
% result to the closest integer, with ties rounded to an even integer.
% The result may be outside the range $[- 2^{31} + 1, 2^{31} - 1]$ of
% valid \TeX{} integers, triggering \TeX{} errors if used in an
-% integer expression. The values $\pm\infty$ and \texttt{nan} trigger
+% integer expression. The values $\pm\infty$ and \nan{} trigger
% an \enquote{invalid operation} exception.
% \end{function}
%
-% \begin{function}[EXP, added = 2012-05-08, updated = 2012-07-08]
+% \begin{function}[EXP, added = 2012-05-08, updated = 2012-07-08,
+% tested = m3fp-convert003]
% {\fp_to_scientific:N, \fp_to_scientific:c, \fp_to_scientific:n}
% \begin{syntax}
% \cs{fp_to_scientific:N} \meta{fp~var}
@@ -292,11 +298,11 @@
% \meta{optional \texttt{-}}\meta{digit}\texttt{.}\meta{15 digits}\texttt{e}\meta{optional sign}\meta{exponent}
% \end{quote}
% The leading \meta{digit} is non-zero except in the case of $\pm 0$.
-% The values $\pm\infty$ and \texttt{nan} trigger an \enquote{invalid
+% The values $\pm\infty$ and \nan{} trigger an \enquote{invalid
% operation} exception.
% \end{function}
%
-% \begin{function}[EXP, updated = 2012-07-08]
+% \begin{function}[EXP, updated = 2012-07-08, tested = m3fp-convert003]
% {\fp_to_tl:N, \fp_to_tl:c, \fp_to_tl:n}
% \begin{syntax}
% \cs{fp_to_tl:N} \meta{fp~var}
@@ -310,12 +316,13 @@
% are expressed in a decimal notation without exponent, with trailing
% zeros trimmed, and no decimal separator for integer values (see
% \cs{fp_to_decimal:n}. Negative numbers start with |-|. The
-% special values $\pm 0$, $\pm \inf$ and \texttt{nan} are rendered as
+% special values $\pm 0$, $\pm \inf$ and \nan{} are rendered as
% |0|, |-0|, \texttt{inf}, \texttt{-inf}, and \texttt{nan}
% respectively.
% \end{function}
%
-% \begin{function}[EXP, updated = 2012-07-08]{\fp_use:N, \fp_use:c}
+% \begin{function}[EXP, updated = 2012-07-08, tested = m3fp-convert003]
+% {\fp_use:N, \fp_use:c}
% \begin{syntax}
% \cs{fp_use:N} \meta{fp~var}
% \end{syntax}
@@ -324,13 +331,13 @@
% Leading or trailing zeros may be inserted to compensate for the
% exponent. Non-significant trailing zeros are trimmed. Integers are
% expressed without a decimal separator. The values $\pm\infty$ and
-% \texttt{nan} trigger an \enquote{invalid operation} exception. This
+% \nan{} trigger an \enquote{invalid operation} exception. This
% function is identical to \cs{fp_to_decimal:N}.
% \end{function}
%
% \section{Floating point conditionals}
%
-% \begin{function}[EXP, pTF, updated = 2012-05-08]
+% \begin{function}[EXP, pTF, updated = 2012-05-08, tested = m3fp002]
% {\fp_if_exist:N, \fp_if_exist:c}
% \begin{syntax}
% \cs{fp_if_exist_p:N} \meta{fp~var}
@@ -340,8 +347,8 @@
% check that the \meta{fp~var} really is a floating point variable.
% \end{function}
%
-% \begin{function}[EXP, pTF, updated = 2012-05-08]
-% {\fp_compare:nNn, \fp_compare:n}
+% \begin{function}[EXP, pTF, updated = 2012-05-08,
+% tested = m3fp-logic001]{\fp_compare:nNn, \fp_compare:n}
% \begin{syntax}
% \cs{fp_compare_p:nNn} \Arg{fpexpr_1} \meta{relation} \Arg{fpexpr_2}
% \cs{fp_compare:nNnTF} \Arg{fpexpr_1} \meta{relation} \Arg{fpexpr_2} \Arg{true code} \Arg{false code}
@@ -352,7 +359,7 @@
% \texttt{true} if the \meta{relation} is obeyed. Two floating point
% numbers $x$ and $y$ may obey four mutually exclusive relations:
% $x<y$, $x=y$, $x>y$, or $x$ and $y$ are not ordered. The latter
-% case occurs exactly when one of the operands is \texttt{nan}, and
+% case occurs exactly when one of the operands is \nan{}, and
% this relations is denoted by the symbol |?|. The \texttt{nNn}
% functions support the \meta{relations} |<|, |=|, |>|, and |?|. The
% \texttt{n} functions support as a \meta{relation} any combination of
@@ -360,9 +367,9 @@
% \meta{relation}), with the restriction that the \meta{relation} may
% not start with |?|. Common choices of \meta{relation} include |>=|
% (greater or equal), |!=| (not equal), |!?| (comparable). Note that
-% a \texttt{nan} is distinct from any value, even another
-% \texttt{nan}, hence $x=x$ is not true for a \texttt{nan}. Thus to
-% test if a value is \texttt{nan}, use
+% a \nan{} is distinct from any value, even another
+% \nan{}, hence $x=x$ is not true for a \nan{}. Thus to
+% test if a value is \nan{}, use
% \begin{verbatim}
% \fp_compare:nNnTF { <value> } != { <value> }
% { } % <value> is nan
@@ -370,6 +377,112 @@
% \end{verbatim}
% \end{function}
%
+% \section{Floating point expression loops}
+%
+% \begin{function}[rEXP, added = 2012-08-16, tested = m3fp-logic003]
+% {\fp_do_until:nNnn}
+% \begin{syntax}
+% \cs{fp_do_until:nNnn} \Arg{fpexpr_1} \meta{relation} \Arg{fpexpr_2} \Arg{code}
+% \end{syntax}
+% Places the \meta{code} in the input stream for \TeX{} to process,
+% and then evaluates the relationship between the two \meta{floating
+% point expressions} as described for \cs{fp_compare:nNnTF}. If the
+% test is \texttt{false} then the \meta{code} will be inserted into
+% the input stream again and a loop will occur until the
+% \meta{relation} is \texttt{true}.
+% \end{function}
+%
+% \begin{function}[rEXP, added = 2012-08-16, tested = m3fp-logic003]
+% {\fp_do_while:nNnn}
+% \begin{syntax}
+% \cs{fp_do_while:nNnn} \Arg{fpexpr_1} \meta{relation} \Arg{fpexpr_2} \Arg{code}
+% \end{syntax}
+% Places the \meta{code} in the input stream for \TeX{} to process,
+% and then evaluates the relationship between the two \meta{floating
+% point expressions} as described for \cs{fp_compare:nNnTF}. If the
+% test is \texttt{true} then the \meta{code} will be inserted into the
+% input stream again and a loop will occur until the \meta{relation}
+% is \texttt{false}.
+% \end{function}
+%
+% \begin{function}[rEXP, added = 2012-08-16, tested = m3fp-logic003]
+% {\fp_until_do:nNnn}
+% \begin{syntax}
+% \cs{fp_until_do:nNnn} \Arg{fpexpr_1} \meta{relation} \Arg{fpexpr_2} \Arg{code}
+% \end{syntax}
+% Evaluates the relationship between the two \meta{floating point
+% expressions} as described for \cs{fp_compare:nNnTF}, and then
+% places the \meta{code} in the input stream if the \meta{relation} is
+% \texttt{false}. After the \meta{code} has been processed by \TeX{}
+% the test will be repeated, and a loop will occur until the test is
+% \texttt{true}.
+% \end{function}
+%
+% \begin{function}[rEXP, added = 2012-08-16, tested = m3fp-logic003]
+% {\fp_while_do:nNnn}
+% \begin{syntax}
+% \cs{fp_while_do:nNnn} \Arg{fpexpr_1} \meta{relation} \Arg{fpexpr_2} \Arg{code}
+% \end{syntax}
+% Evaluates the relationship between the two \meta{floating point
+% expressions} as described for \cs{fp_compare:nNnTF}, and then
+% places the \meta{code} in the input stream if the \meta{relation} is
+% \texttt{true}. After the \meta{code} has been processed by \TeX{}
+% the test will be repeated, and a loop will occur until the test is
+% \texttt{false}.
+% \end{function}
+%
+% \begin{function}[rEXP, added = 2012-08-16, tested = m3fp-logic003]
+% {\fp_do_until:nn}
+% \begin{syntax}
+% \cs{fp_do_until:nn} \{ \meta{fpexpr_1} \meta{relation} \meta{fpexpr_2} \} \Arg{code}
+% \end{syntax}
+% Places the \meta{code} in the input stream for \TeX{} to process,
+% and then evaluates the relationship between the two \meta{floating
+% point expressions} as described for \cs{fp_compare:nTF}. If the
+% test is \texttt{false} then the \meta{code} will be inserted into
+% the input stream again and a loop will occur until the
+% \meta{relation} is \texttt{true}.
+% \end{function}
+%
+% \begin{function}[rEXP, added = 2012-08-16, tested = m3fp-logic003]
+% {\fp_do_while:nn}
+% \begin{syntax}
+% \cs{fp_do_while:nn} \{ \meta{fpexpr_1} \meta{relation} \meta{fpexpr_2} \} \Arg{code}
+% \end{syntax}
+% Places the \meta{code} in the input stream for \TeX{} to process,
+% and then evaluates the relationship between the two \meta{floating
+% point expressions} as described for \cs{fp_compare:nTF}. If the
+% test is \texttt{true} then the \meta{code} will be inserted into the
+% input stream again and a loop will occur until the \meta{relation}
+% is \texttt{false}.
+% \end{function}
+%
+% \begin{function}[rEXP, added = 2012-08-16, tested = m3fp-logic003]
+% {\fp_until_do:nn}
+% \begin{syntax}
+% \cs{fp_until_do:nn} \{ \meta{fpexpr_1} \meta{relation} \meta{fpexpr_2} \} \Arg{code}
+% \end{syntax}
+% Evaluates the relationship between the two \meta{floating point
+% expressions} as described for \cs{fp_compare:nTF}, and then places
+% the \meta{code} in the input stream if the \meta{relation} is
+% \texttt{false}. After the \meta{code} has been processed by \TeX{}
+% the test will be repeated, and a loop will occur until the test is
+% \texttt{true}.
+% \end{function}
+%
+% \begin{function}[rEXP, added = 2012-08-16, tested = m3fp-logic003]
+% {\fp_while_do:nn}
+% \begin{syntax}
+% \cs{fp_while_do:nn} \{ \meta{fpexpr_1} \meta{relation} \meta{fpexpr_2} \} \Arg{code}
+% \end{syntax}
+% Evaluates the relationship between the two \meta{floating point
+% expressions} as described for \cs{fp_compare:nTF}, and then places
+% the \meta{code} in the input stream if the \meta{relation} is
+% \texttt{true}. After the \meta{code} has been processed by \TeX{}
+% the test will be repeated, and a loop will occur until the test is
+% \texttt{false}.
+% \end{function}
+%
% \section{Some useful constants, and scratch variables}
%
% \begin{variable}[added = 2012-05-08]{\c_zero_fp, \c_minus_zero_fp}
@@ -450,8 +563,8 @@
% (using \cs{fp_trap:nn}) to either produce an error and turn the flag
% on, or only turn the flag on, or do nothing at all.
%
-% \begin{function}[EXP, pTF, added = 2012-08-08,
-% tested = m3fp-traps001]{\fp_if_flag_on:n}
+% \begin{function}[EXP, pTF, added = 2012-08-08, tested = m3fp-traps001]
+% {\fp_if_flag_on:n}
% \begin{syntax}
% \cs{fp_if_flag_on_p:n} \Arg{exception}
% \cs{fp_if_flag_on:nTF} \Arg{exception} \Arg{true code} \Arg{false code}
@@ -461,8 +574,8 @@
% \emph{This function is experimental, and may be altered or removed.}
% \end{function}
%
-% \begin{function}[added = 2012-08-08,
-% tested = m3fp-traps001]{\fp_flag_off:n}
+% \begin{function}[added = 2012-08-08, tested = m3fp-traps001]
+% {\fp_flag_off:n}
% \begin{syntax}
% \cs{fp_flag_off:n} \Arg{exception}
% \end{syntax}
@@ -471,8 +584,8 @@
% \emph{This function is experimental, and may be altered or removed.}
% \end{function}
%
-% \begin{function}[EXP, added = 2012-08-08,
-% tested = m3fp-traps001]{\fp_flag_on:n}
+% \begin{function}[EXP, added = 2012-08-08, tested = m3fp-traps001]
+% {\fp_flag_on:n}
% \begin{syntax}
% \cs{fp_flag_on:n} \Arg{exception}
% \end{syntax}
@@ -506,8 +619,8 @@
%
% \section{Viewing floating points}
%
-% \begin{function}[added = 2012-05-08, updated = 2012-05-27]
-% {\fp_show:N, \fp_show:c, \fp_show:n}
+% \begin{function}[added = 2012-05-08, updated = 2012-08-14,
+% tested = m3fp002]{\fp_show:N, \fp_show:c, \fp_show:n}
% \begin{syntax}
% \cs{fp_show:N} \meta{fp~var}
% \cs{fp_show:n} \Arg{floating point expression}
@@ -520,9 +633,6 @@
%
% \subsection{Input of floating point numbers} \label{sec:fp-floats}
%
-% ^^A todo: redoc subsection, write a grammar
-% ^^A todo: clarify what has changed compared to the previous l3fp
-%
% We support four types of floating point numbers:
% \begin{itemize}
% \item $\pm 0.d_1d_2\ldots{}d_{16} \cdot 10^{n}$, a normal floating
@@ -530,7 +640,7 @@
% \leq \ExplSyntaxOn \int_use:N \c__fp_max_exponent_int$;
% \item $\pm 0$, zero, with a given sign;
% \item $\pm \infty$, infinity, with a given sign;
-% \item \texttt{nan}, is \enquote{not a number}, and can be either quiet
+% \item \nan{}, is \enquote{not a number}, and can be either quiet
% or signalling (\emph{not yet}: this distinction is currently
% unsupported);
% \item [\emph{(not yet)}] subnormal numbers $\pm 0.d_1d_2\ldots{}d_{16}
@@ -543,7 +653,7 @@
% On input, a normal floating point number consists of:
% \begin{itemize}
% \item \meta{sign}: a possibly empty string of |+| and |-| characters;
-% \item \meta{mantissa}: a non-empty string of digits together with zero
+% \item \meta{significand}: a non-empty string of digits together with zero
% or one dot;
% \item \meta{exponent} optionally: the character |e|, followed by a
% possibly empty string of |+|~and~|-| tokens, and a non-empty string
@@ -551,41 +661,42 @@
% \end{itemize}
% The sign of the resulting number is |+| if \meta{sign} contains an
% even number of |-|, and |-| otherwise, hence, an empty \meta{sign}
-% denotes a non-negative input. The stored mantissa is obtained from
-% \meta{mantissa} by omitting the decimal separator and leading zeros,
+% denotes a non-negative input. The stored significand is obtained from
+% \meta{significand} by omitting the decimal separator and leading zeros,
% and rounding to $16$ significant digits, filling with trailing zeros
% if necessary. In particular, the value stored is exact if the input
-% \meta{mantissa} has at most $16$ digits. The stored \meta{exponent}
+% \meta{significand} has at most $16$ digits. The stored \meta{exponent}
% is obtained by combining the input \meta{exponent} ($0$ if absent)
-% with a shift depending on the position of the mantissa and the number
+% with a shift depending on the position of the significand and the number
% of leading zeros.
%
-% A special case arises if the resulting \meta{exponent} is either
-% too large or too small to be represented. This results either in an
-% overflow (the number is then replaced by $\pm\infty$), or an
-% underflow (resulting in $\pm 0$).
+% A special case arises if the resulting \meta{exponent} is either too
+% large or too small for the floating point number to be
+% represented. This results either in an overflow (the number is then
+% replaced by $\pm\infty$), or an underflow (resulting in $\pm 0$).
%
-% The result is thus $\pm 0$ if and only if \meta{mantissa} contains no
+% The result is thus $\pm 0$ if and only if \meta{significand} contains no
% non-zero digit (\emph{i.e.}, consists only in~|0| characters, and an
-% optional |.| character), or there is an underflow. Note that a single
-% dot is currently a valid floating point number, equal to~$+0$, but
-% that is not guaranteed to remain the case.
+% optional |.| character), or if there is an underflow. Note that a
+% single dot is currently a valid floating point number, equal to~$+0$,
+% but that is not guaranteed to remain true.
%
% Special numbers are input as follows:
% \begin{itemize}
% \item \texttt{inf} represents $+\infty$, and can be preceded by any
-% \meta{sign}.
-% \item \texttt{nan} represents a (quiet) non-number. It can be preceded
-% by any sign, but that will be ignored.
-% \item Any unrecognisable string will yield a signalling \texttt{nan}.
+% \meta{sign}, yielding $\pm\infty$ as appropriate.
+% \item \texttt{nan} represents a (quiet) non-number. It can be
+% preceded by any sign, but that will be ignored.
+% \item Any unrecognizable string triggers an error, and produces a
+% \nan{}.
% \end{itemize}
%
-% Note that~|e-1| is not a representation of $10^{-1}$, because it
-% could be mistaken with the difference of \enquote{\texttt{e}} and
-% $1$. This is consistent with several other programming languages.
-% However, in order to avoid confusions, |e-1| is not considered to
-% be this difference either. To input the base of natural logarithms,
-% use \texttt{exp(1)} or \cs{c_e_fp}.
+% Note that~|e-1| is not a representation of $10^{-1}$, because it could
+% be mistaken with the difference of \enquote{\texttt{e}} and $1$. This
+% is consistent with several other programming languages. However, in
+% order to avoid confusions, |e-1| is not considered to be this
+% difference either. To input the base of natural logarithms, use
+% \texttt{exp(1)} or \cs{c_e_fp}.
%
% \subsection{Precedence of operators}
% \label{sec:fp-precedence}
@@ -602,7 +713,7 @@
% \item Binary |+| and |-|.
% \item Comparisons |>=|, |!=|, |<?|, \emph{etc}.
% \item Logical \texttt{and}, denoted by |&&|.
-% \item Logical \texttt{or}, denoted by \verb*+||+.
+% \item Logical \texttt{or}, denoted by \verb+||+.
% \item Ternary operator |?:| (right associative).
% \end{itemize}
% The precedence of operations can be overridden using parentheses.
@@ -617,14 +728,11 @@
% \subsection{Operations} \label{sec:fp-operations}
%
% We now present the various operations allowed in floating point
-% expressions. When used as a truth value, a floating point expression
-% is \texttt{false} if it is $\pm 0$, and \texttt{true} otherwise.
+% expressions, from the lowest precedence to the highest. When used as
+% a truth value, a floating point expression is \texttt{false} if it is
+% $\pm 0$, and \texttt{true} otherwise, including when it is \nan{}.
%
-% The exceptions listed below are mostly not implemented yet.
-% ^^A todo: implement all exceptions already listed.
-% ^^A todo: add exceptions to '?:', '!<=>?', etc.
-%
-% \begin{function}{?:}
+% \begin{function}[tested = m3fp-logic002]{?:}
% \begin{syntax}
% \cs{fp_eval:n} \{ \meta{operand_1} |?| \meta{operand_2} |:| \meta{operand_3} \}
% \end{syntax}
@@ -649,7 +757,7 @@
% \end{function}
%
% \begingroup \catcode`\|=12
-% \begin{function}{TWO BARS} ^^A todo:fix
+% \begin{function}[tested = m3fp-logic002]{TWO BARS}
% \begin{syntax}
% \cs{fp_eval:n} \{ \meta{operand_1} \texttt{||} \meta{operand_2} \}
% \end{syntax}
@@ -660,7 +768,7 @@
% \endgroup
%
% \begingroup \catcode`\&=12
-% \begin{function}{&&}
+% \begin{function}[tested = m3fp-logic002]{&&}
% \begin{syntax}
% \cs{fp_eval:n} \{ \meta{operand_1} \texttt{&&} \meta{operand_2} \}
% \end{syntax}
@@ -670,7 +778,7 @@
% \end{function}
% \endgroup
%
-% \begin{function}{\<, =, >, ?}
+% \begin{function}[tested = m3fp-logic001]{\<, =, >, ?}
% \begin{syntax}
% \cs{fp_eval:n} \{ \meta{operand_1} \meta{comparison} \meta{operand_2} \}
% \end{syntax}
@@ -680,18 +788,17 @@
% \meta{operand_1} and \meta{operand_2} is true, and $+0$ otherwise.
% \end{function}
%
-% \begin{function}{+, -}
+% \begin{function}[tested = m3fp-basics001]{+, -}
% \begin{syntax}
% \cs{fp_eval:n} \{ \meta{operand_1} |+| \meta{operand_2} \}
% \cs{fp_eval:n} \{ \meta{operand_1} |-| \meta{operand_2} \}
% \end{syntax}
% Computes the sum or the difference of its two \meta{operands}. The
% \enquote{invalid operation} exception occurs for $\infty-\infty$.
-% \enquote{Inexact}, \enquote{underflow} and \enquote{overflow} occur
-% when appropriate.
+% \enquote{Underflow} and \enquote{overflow} occur when appropriate.
% \end{function}
%
-% \begin{function}{*, /}
+% \begin{function}[tested = {m3fp-basics002, m3fp-basics003}]{*, /}
% \begin{syntax}
% \cs{fp_eval:n} \{ \meta{operand_1} |*| \meta{operand_2} \}
% \cs{fp_eval:n} \{ \meta{operand_1} |/| \meta{operand_2} \}
@@ -699,12 +806,11 @@
% Computes the product or the ratio of its two \meta{operands}. The
% \enquote{invalid operation} exception occurs for $\infty/\infty$,
% $0/0$, or $0*\infty$. \enquote{Division by zero} occurs when
-% dividing a finite non-zero number by $\pm 0$. The
-% \enquote{inexact}, \enquote{underflow} and \enquote{overflow}
-% exceptions occur when appropriate.
+% dividing a finite non-zero number by $\pm 0$. \enquote{Underflow}
+% and \enquote{overflow} occur when appropriate.
% \end{function}
%
-% \begin{function}{+, -, !}
+% \begin{function}[tested = m3fp-basics004]{+, -, !}
% \begin{syntax}
% \cs{fp_eval:n} \{ |+| \meta{operand} \}
% \cs{fp_eval:n} \{ |-| \meta{operand} \}
@@ -713,116 +819,124 @@
% The unary |+| does nothing, the unary |-| changes the sign of the
% \meta{operand}, and |!| \meta{operand} evaluates to $1$ if
% \meta{operand} is false and $0$ otherwise (this is the \texttt{not}
-% boolean function).
+% boolean function). Those operations never raise exceptions.
% \end{function}
%
% \begingroup\catcode`\^=12
-% \begin{function}{**, ^}
+% \begin{function}[tested = m3fp-expo001]{**, ^}
% \begin{syntax}
% \cs{fp_eval:n} \{ \meta{operand_1} |**| \meta{operand_2} \}
% \cs{fp_eval:n} \{ \meta{operand_1} |^| \meta{operand_2} \}
% \end{syntax}
-% Raises \meta{operand_1} to the power \meta{operand_2}. This operation
-% is right associative, hence \texttt{2 ** 2 ** 3} equals
-% $2^{2^{3}} = 256$. The \enquote{invalid operation} exception
-% occurs if \meta{operand_1} is negative or $-0$, and \meta{operand_2} is
-% not an integer, and the result is non-zero. \enquote{Division by
-% zero} occurs \emph{not yet}. The \enquote{inexact},
-% \enquote{underflow} and \enquote{overflow} exceptions occur when
-% appropriate.
+% Raises \meta{operand_1} to the power \meta{operand_2}. This
+% operation is right associative, hence \texttt{2 ** 2 ** 3} equals
+% $2^{2^{3}} = 256$. The \enquote{invalid operation} exception occurs
+% if \meta{operand_1} is negative or $-0$, and \meta{operand_2} is not
+% an integer, unless the result is zero (in that case, the sign is
+% chosen arbitrarily to be $+0$). \enquote{Division by zero} occurs
+% when raising $\pm 0$ to a strictly negative power.
+% \enquote{Underflow} and \enquote{overflow} occur when appropriate.
% \end{function}
% \endgroup
%
-% \begin{function}{abs}
+% \begin{function}[tested = m3fp-basics004]{abs}
% \begin{syntax}
% \cs{fp_eval:n} \{ |abs(| \meta{fpexpr} |)| \}
% \end{syntax}
% Computes the absolute value of the \meta{fpexpr}. This function
% does not raise any exception beyond those raised when computing its
-% operand \meta{fpexpr}.
+% operand \meta{fpexpr}. See also \cs{fp_abs:n}.
% \end{function}
%
-% \begin{function}{exp}
+% \begin{function}[tested = m3fp-expo001]{exp}
% \begin{syntax}
% \cs{fp_eval:n} \{ |exp(| \meta{fpexpr} |)| \}
% \end{syntax}
-% Computes the exponential of the \meta{fpexpr}. The
-% \enquote{underflow} and \enquote{overflow}
-% exceptions occur when appropriate.
+% Computes the exponential of the \meta{fpexpr}. \enquote{Underflow}
+% and \enquote{overflow} occur when appropriate.
% \end{function}
%
-% \begin{function}{ln}
+% \begin{function}[tested = m3fp-expo001]{ln}
% \begin{syntax}
% \cs{fp_eval:n} \{ |ln(| \meta{fpexpr} |)| \}
% \end{syntax}
% Computes the natural logarithm of the \meta{fpexpr}. Negative
% numbers have no (real) logarithm, hence the \enquote{invalid
% operation} is raised in that case, including for $\ln(-0)$.
-% \enquote{Division by zero} occurs when evaluating $\ln(+0)$. The
-% \enquote{underflow} and \enquote{overflow}
-% exceptions occur when appropriate.
+% \enquote{Division by zero} occurs when evaluating $\ln(+0) =
+% -\infty$. \enquote{Underflow} and \enquote{overflow} occur when
+% appropriate.
% \end{function}
%
-% \begin{function}{max, min}
+% \begin{function}[tested = m3fp-logic002]{max, min}
% \begin{syntax}
% \cs{fp_eval:n} \{ |max(| \meta{fpexpr_1} |,| \meta{fpexpr_2} |,| \ldots{} |)| \}
% \cs{fp_eval:n} \{ |min(| \meta{fpexpr_1} |,| \meta{fpexpr_2} |,| \ldots{} |)| \}
% \end{syntax}
% Evalutes each \meta{fpexpr} and computes the largest (smallest) of
% those. If any of the \meta{fpexpr} is a \nan{}, the result is
-% \nan{}.
+% \nan{}. Those operations do not raise exceptions.
% \end{function}
%
-% \begin{function}{round, round0, round+, round-}
+% \begin{function}[tested = {m3fp-round001, m3fp-round002}]
+% {round, round0, round+, round-}
% \begin{syntax}
% \cs{fp_eval:n} \{ |round| \meta{option} |(| \meta{fpexpr} |)| \}
% \cs{fp_eval:n} \{ |round| \meta{option} |(| \meta{fpexpr_1} , \meta{fpexpr_2} |)| \}
% \end{syntax}
-% Rounds \meta{fpexpr_1} to \meta{fpexpr_2} places (this must be an
-% integer). When \meta{fpexpr_2} is missing, it is assumed to be $0$,
-% \emph{i.e.}, \meta{fpexpr_1} is rounded to an integer. The
-% \meta{option} controls the rounding direction:
+% Rounds \meta{fpexpr_1} to \meta{fpexpr_2} places. When
+% \meta{fpexpr_2} is omitted, it is assumed to be $0$, \emph{i.e.},
+% \meta{fpexpr_1} is rounded to an integer. The \meta{option}
+% controls the rounding direction:
% \begin{itemize}
-% \item by default, the function rounds to the closest allowed number
+% \item by default, the operation rounds to the closest allowed number
% (rounding ties to even);
-% \item with |0|, the function rounds towards $0$, \emph{i.e.}, truncates;
-% \item with |+|, the function rounds towards $+\infty$;
-% \item with |-|, the function rounds towards $-\infty$.
+% \item with |0|, the operation rounds towards $0$, \emph{i.e.}, truncates;
+% \item with |+|, the operation rounds towards $+\infty$;
+% \item with |-|, the operation rounds towards $-\infty$.
% \end{itemize}
+% If \meta{fpexpr_2} does not yield an integer less than $10^{8}$ in
+% absolute value, then an \enquote{invalid operation} exception is
+% raised. \enquote{Overflow} may occur if the result is infinite
+% (this cannot happen unless $\meta{fpexpr_2}\string<-9984$).
% \end{function}
%
-% \begin{function}{sin, cos, tan, cot}
+% \begin{function}[tested = m3fp-trig001]{sin, cos, tan, cot, csc, sec}
% \begin{syntax}
% \cs{fp_eval:n} \{ |sin(| \meta{fpexpr} |)| \}
% \cs{fp_eval:n} \{ |cos(| \meta{fpexpr} |)| \}
% \cs{fp_eval:n} \{ |tan(| \meta{fpexpr} |)| \}
% \cs{fp_eval:n} \{ |cot(| \meta{fpexpr} |)| \}
+% \cs{fp_eval:n} \{ |csc(| \meta{fpexpr} |)| \}
+% \cs{fp_eval:n} \{ |sec(| \meta{fpexpr} |)| \}
% \end{syntax}
-% Computes the sine, cosine, tangent or cotangent of the
-% \meta{fpexpr}. The trigonometric functions are undefined for an
-% argument of $\pm\infty$, leading to the \enquote{invalid operation}
-% exception. Additionally, evaluating tangent or cotangent at one of
-% their poles leads to a \enquote{division by zero} exception. Other
-% exceptions occur when appropriate.
+% Computes the sine, cosine, tangent, cotangent, cosecant, or secant
+% of the \meta{fpexpr}. The trigonometric functions are undefined for
+% an argument of $\pm\infty$, leading to the \enquote{invalid
+% operation} exception. Additionally, evaluating tangent,
+% cotangent, cosecant, or secant at one of their poles leads to a
+% \enquote{division by zero} exception. \enquote{Underflow} and
+% \enquote{overflow} occur when appropriate.
% \end{function}
%
-% \begin{variable}{inf, nan}
+% \begin{variable}[tested = m3fp-parse001]{inf, nan}
% The special values $+\infty$, $-\infty$, and \nan{} are represented
% as \texttt{inf}, \texttt{-inf} and \texttt{nan} (see \cs{c_inf_fp},
% \cs{c_minus_inf_fp} and \cs{c_nan_fp}).
% \end{variable}
%
-% \begin{variable}{pi}
+% \begin{variable}[tested = m3fp-parse001]{pi}
% The value of $\pi$ (see \cs{c_pi_fp}).
% \end{variable}
%
-% \begin{variable}{deg}
+% \begin{variable}[tested = m3fp-parse001]{deg}
% The value of $1^{\circ}$ in radians (see \cs{c_one_degree_fp}).
% \end{variable}
%
-% \begin{variable}{em, ex, in, pt, pc, cm, mm, dd, cc, nd, nc, bp, sp}
+% \begin{variable}[tested = m3fp-parse001]
+% {em, ex, in, pt, pc, cm, mm, dd, cc, nd, nc, bp, sp}
% \newcommand{\unit}[1]{\text{\texttt{#1}}}
-% Those units of measurement are equal to their values in \texttt{pt},
+% Those units of measurement are equal to their values in \unit{pt},
% namely
% \begin{align*}
% 1 \unit{in} & = 72.27 \unit{pt} \\
@@ -837,16 +951,17 @@
% 1 \unit{bp} & = \frac{1}{72} \unit{in} = 1.00375 \unit{pt} \\
% 1 \unit{sp} & = 2^{-16} \unit{pt} = 1.52587890625e-5 \unit{pt}.
% \end{align*}
-% The values of the (font-dependent) units \texttt{em} and \texttt{ex}
-% are gathered from \TeX{} when the surrounding floating point
-% expression is evaluated.
+% The values of the (font-dependent) units \unit{em} and \unit{ex} are
+% gathered from \TeX{} when the surrounding floating point expression
+% is evaluated.
% \end{variable}
%
-% \begin{variable}{true, false}
+% \begin{variable}[tested = m3fp-parse001]{true, false}
% Other names for $1$ and $+0$.
% \end{variable}
%
-% \begin{function}[EXP, added = 2012-05-08]{\dim_to_fp:n}
+% \begin{function}[EXP, added = 2012-05-08, tested = m3fp-convert002]
+% {\dim_to_fp:n}
% \begin{syntax}
% \cs{dim_to_fp:n} \Arg{dimexpr}
% \end{syntax}
@@ -857,29 +972,18 @@
% where a low precision is acceptable.
% \end{function}
%
-% \begin{function}[EXP, added = 2012-05-14, updated = 2012-07-08]{\fp_abs:n}
+% \begin{function}[EXP, added = 2012-05-14, updated = 2012-07-08,
+% tested = m3fp-convert003]{\fp_abs:n}
% \begin{syntax}
% \cs{fp_abs:n} \Arg{floating point expression}
% \end{syntax}
% Evaluates the \meta{floating point expression} as described for
-% \cs{fp_eval:n} and leaves the absolute value of the result in
-% the input stream.
+% \cs{fp_eval:n} and leaves the absolute value of the result in the
+% input stream. This function does not raise any exception beyond
+% those raised when evaluating its argument. Within floating point
+% expressios, |abs()| can be used.
% \end{function}
%
-% ^^A todo
-% ^^A \section{Rounding}
-% ^^A
-% ^^A This explains how to go from a floating point number to a
-% ^^A rounded value for various applications. Perhaps worth coding
-% ^^A functionalities up to what siunitx can do on this matter.
-%
-% ^^A todo
-% ^^A \section{Floating points}
-% ^^A
-% ^^A Here, there may be a discussion of what floating point numbers
-% ^^A are, and a list of relevant resources (\emph{e.g.}, some of
-% ^^A Kahan's articles), and previous \TeX{} packages.
-%
% \section{Disclaimer and roadmap}
%
% The package may break down if:
@@ -907,7 +1011,8 @@
% \texttt{any}, and \texttt{xor}?
% \item Add \texttt{csc} and \texttt{sec}.
% \item Add $\log(x,b)$ for logarithm of $x$ in base $b$.
-% \item \texttt{hypot} (Euclidean length) and $\atan(x,y) = \atan(x/y)$,
+% \item \texttt{hypot} (Euclidean length) and
+% $\operatorname{atan}(x,y) = \operatorname{atan}(x/y)$,
% also called \texttt{atan2} in other math packages.
% Cartesian-to-polar transform. Other inverse trigonometric functions
% \texttt{acos}, \texttt{asin}, \texttt{atan} (one and two arguments).
@@ -918,8 +1023,8 @@
% \item Random numbers (pgfmath provides |rnd|, |rand|, |random|), with
% seed reset at every \cs{fp_set:Nn}.
% \item Factorial (not with |!|), gamma function.
-% \item Improve coefficients of \texttt{sin}, \texttt{cos} and
-% \texttt{tan}.
+% \item Improve coefficients of the \texttt{sin} and \texttt{tan}
+% series.
% \item Treat upper and lower case letters identically in
% identifiers, and ignore underscores.
% \item Parse $-3<-2<-1$ as it should, not $(-3<-2)<-1$.
@@ -933,6 +1038,10 @@
%
% Bugs. (Exclamation points mark important bugs.)
% \begin{itemize}
+% \item[!] Some functions are not monotonic when they should. For
+% instance, $\sin(1-10^{-16})$ is wrongly greater than $\sin(1)$.
+% \item Add exceptions to |?:|, |!<=>?|, |&&|, \verb"||", and |!|.
+% \item |round| should accept any integer as its second argument.
% \item Logarithms of numbers very close to $1$ are inaccurate.
% \item \texttt{tan} and \texttt{cot} give very slightly wrong results
% for arguments near $10^{-8}$.
@@ -952,6 +1061,10 @@
%
% Possible optimizations/improvements.
% \begin{itemize}
+% \item Optimize argument reduction for trigonometric functions: we
+% don't need $6\times 4$ digits here, only $4\times 4$.
+% \item In subsection~\ref{sec:fp-floats}, write a grammar.
+% \item Fix the |TWO BARS| business with the index.
% \item It would be nice if the \texttt{parse} auxiliaries for each
% operation were set up in the corresponding module, rather than
% centralizing in \pkg{l3fp-parse}.
@@ -974,6 +1087,11 @@
% and \cs{@@_basics_pack_weird_high:NNNNNNNNw} better. Move the
% other \texttt{basics_pack} auxiliaries to \pkg{l3fp-aux} under a
% better name.
+% \item Find out if underflow can really occur for trigonometric
+% functions, and redoc as appropriate.
+% \item Add bibliography. Some of Kahan's articles, some previous
+% \TeX{} fp packages, the international standards,\ldots{}
+% \item Also take into account the \enquote{inexact} exception?
% \end{itemize}
%
% \end{documentation}