diff options
author | Karl Berry <karl@freefriends.org> | 2012-08-31 17:58:55 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2012-08-31 17:58:55 +0000 |
commit | 3301423440393adfdbbcfa0d8471e4b4c63df1e6 (patch) | |
tree | 6aa86f66a252f654a2bd2f28ee7b680fdac1b0a3 /Master/texmf-dist/source/latex/l3kernel/l3fp.dtx | |
parent | a511edd7e6a05e250f2b2d8062a470734e3af33d (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.dtx | 422 |
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} |