summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3fp.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3fp.dtx229
1 files changed, 146 insertions, 83 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx b/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx
index dc000923765..fea05abbb12 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx
@@ -36,7 +36,7 @@
%
%<*driver|package>
\RequirePackage{l3bootstrap}
-\GetIdInfo$Id: l3fp.dtx 4601 2013-11-18 23:13:28Z bruno $
+\GetIdInfo$Id: l3fp.dtx 4633 2013-12-31 17:28:46Z joseph $
{L3 Floating points}
%</driver|package>
%<*driver>
@@ -82,7 +82,8 @@
% precedence.
% \begin{itemize}
% \item Basic arithmetic: addition $x+y$, subtraction $x-y$,
-% multiplication $x*y$, division $x/y$, and parentheses.
+% multiplication $x*y$, division $x/y$, square root~$\sqrt{x}$,
+% and parentheses.
% \item Comparison operators: $x\mathop{\mathtt{<}}y$,
% $x\mathop{\mathtt{<=}}y$, $x\mathop{\mathtt{>?}}y$,
% $x\mathop{\mathtt{!=}}y$ \emph{etc.}
@@ -112,13 +113,14 @@
% $\operatorname{asech} x$, $\operatorname{acsch} x$.
% \item Extrema: $\max(x,y,\ldots)$, $\min(x,y,\ldots)$,
% $\operatorname{abs}(x)$.
-% \item Rounding functions: $\operatorname{round}(x,n)$ round to
-% closest, $\operatorname{round0}(x,n)$ round towards zero,
-% $\operatorname{round\pm}(x,n)$ round towards $\pm\infty$. And
+% \item Rounding functions: $\operatorname{round}(x,n)$ rounds to
+% closest, $\operatorname{trunc}(x,n)$ rounds towards zero,
+% $\operatorname{floor}(x,n)$ rounds towards~$-\infty$,
+% $\operatorname{ceil}(x,n)$ rounds towards~$+\infty$. And
% \emph{(not yet)} modulo, and \enquote{quantize}.
% \item Constants: \texttt{pi}, \texttt{deg} (one degree in radians).
% \item Dimensions, automatically expressed in points, \emph{e.g.},
-% \texttt{pc} is $12$.
+% \texttt{pc} is~$12$.
% \item Automatic conversion (no need for \cs{\meta{type}_use:N}) of
% integer, dimension, and skip variables to floating points,
% expressing dimensions in points and ignoring the stretch and
@@ -159,7 +161,7 @@
% \end{syntax}
% Creates a new \meta{fp~var} or raises an error if the name is
% already taken. The declaration is global. The \meta{fp~var} will
-% initially be $+0$.
+% initially be~$+0$.
% \end{function}
%
% \begin{function}[updated = 2012-05-08, tested = m3fp001]
@@ -187,7 +189,7 @@
% \end{syntax}
% Ensures that the \meta{fp~var} exists globally
% by applying \cs{fp_new:N} if necessary, then applies
-% \cs{fp_(g)zero:N} to leave the \meta{fp~var} set to zero.
+% \cs{fp_(g)zero:N} to leave the \meta{fp~var} set to~$+0$.
% \end{function}
%
% \section{Setting floating point variables}
@@ -239,7 +241,7 @@
% \cs{fp_eval:n} \Arg{floating point expression}
% \end{syntax}
% Evaluates the \meta{floating point expression} and expresses the
-% result as a decimal number with~$16$ significant figures and no
+% result as a decimal number with no
% 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
@@ -255,11 +257,11 @@
% \cs{fp_to_decimal:n} \Arg{floating point expression}
% \end{syntax}
% Evaluates the \meta{floating point expression} and expresses the
-% result as a decimal number with $16$ significant figures and no
+% result as a decimal number with no
% 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 \nan{} trigger an \enquote{invalid operation}
+% $\pm\infty$ and~\nan{} trigger an \enquote{invalid operation}
% exception.
% \end{function}
%
@@ -270,12 +272,12 @@
% \cs{fp_to_dim:n} \Arg{floating point expression}
% \end{syntax}
% Evaluates the \meta{floating point expression} and expresses the
-% result as a dimension (in \texttt{pt}) suitable for use in dimension
+% result as a dimension (in~\texttt{pt}) suitable for use in dimension
% expressions. The output is identical to \cs{fp_to_decimal:n}, with
-% an additional trailing \texttt{pt}. In particular, the result may
+% 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 \nan{} trigger an
+% dimension. The values $\pm\infty$ and~\nan{} trigger an
% \enquote{invalid operation} exception.
% \end{function}
%
@@ -286,10 +288,11 @@
% \cs{fp_to_int:n} \Arg{floating point expression}
% \end{syntax}
% Evaluates the \meta{floating point expression}, and rounds the
-% result to the closest integer, with ties rounded to an even integer.
+% result to the closest integer, rounding exact ties 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 \nan{} trigger
+% valid \TeX{}~integers, leading to overflow errors if used in an
+% integer expression. The values $\pm\infty$ and~\nan{} trigger
% an \enquote{invalid operation} exception.
% \end{function}
%
@@ -301,12 +304,12 @@
% \cs{fp_to_scientific:n} \Arg{floating point expression}
% \end{syntax}
% Evaluates the \meta{floating point expression} and expresses the
-% result in scientific notation with $16$ significant figures:
+% result in scientific notation:
% \begin{quote}
% \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 \nan{} trigger an \enquote{invalid
+% The values $\pm\infty$ and~\nan{} trigger an \enquote{invalid
% operation} exception.
% \end{function}
%
@@ -319,13 +322,14 @@
% Evaluates the \meta{floating point expression} and expresses the
% result in (almost) the shortest possible form. Numbers in the
% ranges $(0,10^{-3})$ and $[10^{16},\infty)$ are expressed in
-% scientific notation with trailing zeros trimmed (see
+% scientific notation with trailing zeros trimmed and no decimal
+% separator when there is a single significant digit (see
% \cs{fp_to_scientific:n}). Numbers in the range $[10^{-3},10^{16})$
% 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 \nan{} are rendered as
-% |0|, |-0|, \texttt{inf}, \texttt{-inf}, and \texttt{nan}
+% \cs{fp_to_decimal:n}. Negative numbers start with~|-|. The
+% special values $\pm 0$, $\pm\infty$ and~\nan{} are rendered as
+% |0|, |-0|, \texttt{inf}, \texttt{-inf}, and~\texttt{nan}
% respectively.
% \end{function}
%
@@ -335,11 +339,11 @@
% \cs{fp_use:N} \meta{fp~var}
% \end{syntax}
% Inserts the value of the \meta{fp~var} into the input stream as a
-% decimal number with $16$ significant figures and no exponent.
+% decimal number with no exponent.
% 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
-% \nan{} trigger an \enquote{invalid operation} exception. This
+% expressed without a decimal separator. The values $\pm\infty$
+% and~\nan{} trigger an \enquote{invalid operation} exception. This
% function is identical to \cs{fp_to_decimal:N}.
% \end{function}
%
@@ -356,30 +360,20 @@
% \end{function}
%
% \begin{function}[EXP, pTF, updated = 2012-05-08,
-% tested = m3fp-logic001]{\fp_compare:nNn, \fp_compare:n}
+% tested = m3fp-logic001]{\fp_compare:nNn}
% \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}
-% \cs{fp_compare_p:n} \{ \meta{fpexpr_1} \meta{relation} \meta{fpexpr_2} \}
-% \cs{fp_compare:nTF} \{ \meta{fpexpr_1} \meta{relation} \meta{fpexpr_2} \} \Arg{true code} \Arg{false code}
% \end{syntax}
% Compares the \meta{fpexpr_1} and the \meta{fpexpr_2}, and returns
% \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 \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 non-empty string of
-% those four symbols, plus optional leading |!| (which negate the
-% \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 \nan{} is distinct from any value, even another
-% \nan{}, hence $x=x$ is not true for a \nan{}.
-% Since a \nan{} is not comparable to any floating point, to test if a
-% value is \nan{}, one can use the following, where~$0$ is an
-% arbitrary 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 either operand is~\nan{}, and this relation
+% is denoted by the symbol~|?|. Note that a~\nan{} is distinct from
+% any value, even another~\nan{}, hence $x=x$ is not true for
+% a~\nan{}. To test if a value is~\nan{}, compare it to an arbitrary
+% number with the \enquote{not ordered} relation.
% \begin{verbatim}
% \fp_compare:nNnTF { <value> } ? { 0 }
% { } % <value> is nan
@@ -387,6 +381,54 @@
% \end{verbatim}
% \end{function}
%
+% \begin{function}[EXP, pTF, updated = 2012-12-14,
+% tested = m3fp-logic001]{\fp_compare:n}
+% \begin{syntax}
+% \cs{fp_compare_p:n} \\
+% ~~\{ \\
+% ~~~~\meta{fpexpr_1} \meta{relation_1} \\
+% ~~~~\ldots{} \\
+% ~~~~\meta{fpexpr_N} \meta{relation_N} \\
+% ~~~~\meta{fpexpr_{N+1}} \\
+% ~~\} \\
+% \cs{fp_compare:nTF}
+% ~~\{ \\
+% ~~~~\meta{fpexpr_1} \meta{relation_1} \\
+% ~~~~\ldots{} \\
+% ~~~~\meta{fpexpr_N} \meta{relation_N} \\
+% ~~~~\meta{fpexpr_{N+1}} \\
+% ~~\} \\
+% ~~\Arg{true code} \Arg{false code}
+% \end{syntax}
+% Evaluates the \meta{floating point expressions} as described for
+% \cs{fp_eval:n} and compares consecutive result using the
+% corresponding \meta{relation}, namely it compares \meta{intexpr_1}
+% and \meta{intexpr_2} using the \meta{relation_1}, then
+% \meta{intexpr_2} and \meta{intexpr_3} using the \meta{relation_2},
+% until finally comparing \meta{intexpr_N} and \meta{intexpr_{N+1}}
+% using the \meta{relation_N}. The test yields \texttt{true} if all
+% comparisons are \texttt{true}. Each \meta{floating point
+% expression} is evaluated only once. Contrarily to
+% \cs{int_compare:nTF}, all \meta{floating point expressions} are
+% computed, even if one comparison is \texttt{false}. 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~\nan{}, and
+% this relation is denoted by the symbol~|?|. Each \meta{relation}
+% can be any (non-empty) combination of |<|, |=|, |>|, and~|?|, plus
+% an optional leading~|!| (which negates the \meta{relation}), with
+% the restriction that the \meta{relation} may not start with~|?|, as
+% this symbol has a different meaning (in combination with~|:|) within
+% floatin point expressions. The comparison $x$~\meta{relation}~$y$
+% is then \texttt{true} if the \meta{relation} does not start with~|!|
+% and the actual relation (|<|, |=|, |>|, or~|?|) between $x$ and~$y$
+% appears within the \meta{relation}, or on the contrary if the
+% \meta{relation} starts with~|!| and the relation between $x$ and~$y$
+% does not appear within the \meta{relation}. Common choices of
+% \meta{relation} include |>=|~(greater or equal), |!=|~(not equal),
+% |!?|~or~|<=>| (comparable).
+% \end{function}
+%
% \section{Floating point expression loops}
%
% \begin{function}[rEXP, added = 2012-08-16, tested = m3fp-logic003]
@@ -513,8 +555,8 @@
% \end{variable}
%
% \begin{variable}[updated = 2012-05-08, updated = 2013-11-17]{\c_pi_fp}
-% The value of $\pi$. This can be input directly in a floating point
-% expression as \texttt{pi}.
+% The value of~$\pi$. This can be input directly in a floating point
+% expression as~\texttt{pi}.
% \end{variable}
%
% \begin{variable}[added = 2012-05-08, updated = 2013-11-17]
@@ -787,20 +829,29 @@
% \begin{syntax}
% \cs{fp_eval:n} \{ \meta{operand_1} \texttt{&&} \meta{operand_2} \}
% \end{syntax}
-% If \meta{operand_1} is false (equal to $\pm 0$), use that value,
+% If \meta{operand_1} is false (equal to~$\pm 0$), use that value,
% otherwise the value of \meta{operand_2}. Both \meta{operands} are
% evaluated in all cases.
% \end{function}
% \endgroup
%
-% \begin{function}[tested = m3fp-logic001]{\<, =, >, ?}
+% \begin{function}[tested = m3fp-logic001, updated = 2013-12-14]
+% {\<, =, >, ?}
% \begin{syntax}
-% \cs{fp_eval:n} \{ \meta{operand_1} \meta{comparison} \meta{operand_2} \}
+% \cs{fp_eval:n} \\
+% ~~\{ \\
+% ~~~~\meta{operand_1} \meta{relation_1} \\
+% ~~~~\ldots{} \\
+% ~~~~\meta{operand_N} \meta{relation_N} \\
+% ~~~~\meta{operand_{N+1}} \\
+% ~~\}
% \end{syntax}
-% The \meta{comparison} consists of a non-empty string of |<|, |=|,
-% |>|, and |?|, optionally preceded by |!|. It may not start with
-% |?|. This evaluates to $+1$ if the \meta{comparison} between the
-% \meta{operand_1} and \meta{operand_2} is true, and $+0$ otherwise.
+% Each \meta{relation} consists of a non-empty string of |<|, |=|,
+% |>|, and~|?|, optionally preceded by~|!|, and may not start
+% with~|?|. This evaluates to $+1$ if all comparisons
+% \meta{operand_i} \meta{relation_j} \meta{operand_{i+1}} are true, and
+% $+0$ otherwise. All \meta{operands} are evaluated in all cases.
+% See \cs{fp_compare:nTF} for details.
% \end{function}
%
% \begin{function}[tested = m3fp-basics001]{+, -}
@@ -893,27 +944,38 @@
% \nan{}. Those operations do not raise exceptions.
% \end{function}
%
-% \begin{function}[tested = {m3fp-round001, m3fp-round002}]
-% {round, round0, round+, round-}
+% \begin{function}
+% [tested = {m3fp-round001, m3fp-round002}, added = 2013-12-14]
+% {round, trunc, ceil, floor}
% \begin{syntax}
-% \cs{fp_eval:n} \{ |round| \meta{option} |(| \meta{fpexpr} |)| \}
-% \cs{fp_eval:n} \{ |round| \meta{option} |(| \meta{fpexpr_1} , \meta{fpexpr_2} |)| \}
+% \cs{fp_eval:n} \{ |round| |(| \meta{fpexpr} |)| \}
+% \cs{fp_eval:n} \{ |round| |(| \meta{fpexpr_1} , \meta{fpexpr_2} |)| \}
% \end{syntax}
-% 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:
+% Evaluates $\meta{fpexpr_1}=x$ and $\meta{fpexpr_2}=n$, then rounds
+% $x$~to $n$~places. If $n$~is an integer, this rounds~$x$ to a
+% multiple of~$10^{-n}$; if $n=+\infty$, this always yields~$x$; if
+% $n=-\infty$, this yields one of $\pm 0$, $\pm\infty$, or~\nan{}; if
+% $n$~is neither $\pm\infty$ nor an integer, then an \enquote{invalid
+% operation} exception is raised. When \meta{fpexpr_2} is omitted,
+% $n=0$, \emph{i.e.}, \meta{fpexpr_1} is rounded to an integer. The
+% rounding direction depends on the function:
% \begin{itemize}
-% \item by default, the operation rounds to the closest allowed number
-% (rounding ties to even);
-% \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$.
+% \item |round| yields the multiple of~$10^{-n}$ closest to~$x$, and
+% if $x$~is half-way between two such multiples, the even multiple
+% is chosen (\enquote{ties to even});
+% \item |floor|, or the deprecated |round-|, yields the largest
+% multiple of~$10^{-n}$ smaller or equal to~$x$ (\enquote{round
+% towards negative infinity});
+% \item |ceil|, or the deprecated |round+|, yields the smallest
+% multiple of~$10^{-n}$ greater or equal to~$x$ (\enquote{round
+% towards positive infinity});
+% \item |trunc|, or the deprecated |round0|, yields a multiple
+% of~$10^{-n}$ with the same sign as~$x$ and with the largest
+% absolute value less that that of~$x$ (\enquote{round towards
+% zero}).
% \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$).
+% \enquote{Overflow} occurs if $x$~is finite and the result is
+% infinite (this can only happen if $\meta{fpexpr_2}\string<-9984$).
% \end{function}
%
% \begin{function}[updated = 2013-11-17, tested = m3fp-trig001]
@@ -1058,6 +1120,17 @@
% exception can occur.
% \end{function}
%
+% \begin{function}[added = 2013-12-14, tested = m3fp-basics005]{sqrt}
+% \begin{syntax}
+% \cs{fp_eval:n} \{ |sqrt(| \meta{fpexpr} |)| \}
+% \end{syntax}
+% Computes the square root of the \meta{fpexpr}. The \enquote{invalid
+% operation} is raised when the \meta{fpexpr} is negative; no other
+% exception can occur. Special values yield $\sqrt{-0} = -0$,
+% $\sqrt{+0} = +0$, $\sqrt{+\infty} = +\infty$ and
+% $\sqrt{\text{\nan{}}}=\text{\nan{}}$.
+% \end{function}
+%
% \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},
@@ -1143,10 +1216,8 @@
%
% The following need to be done. I'll try to time-order the items.
% \begin{itemize}
-% \item Rename |round0| to |trunc|, |round+| to |ceil|, and |round-|
-% to |floor|.
% \item Decide what exponent range to consider.
-% \item Improve the treatment of signalling versus quiet \texttt{nan}.
+% \item Support signalling \texttt{nan}.
% \item Modulo and remainder, and rounding functions |quantize|,
% |quantize0|, |quantize+|, |quantize-|, |quantize=|, |round=|.
% Should the modulo also be provided as (catcode 12) |%|?
@@ -1178,15 +1249,13 @@
%
% Bugs. (Exclamation points mark important bugs.)
% \begin{itemize}
-% \item[!] $-3<-2<-1$ is wrongly parsed as $(-3<-2)<-1$.
% \item Check that functions are monotonic when they should.
% \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 When rounding towards $-\infty$, |\dim_to_fp:n {0pt}| should
% return $-0$, not $+0$.
-% \item The result of $(\pm0)+(\pm0)$ should depend on the rounding
-% mode.
+% \item The result of $(\pm0)+(\pm0)$, of $x+(-x)$, and of $(-x)+x$
+% should depend on the rounding mode.
% \item \texttt{0e9999999999} gives a \TeX{} \enquote{number too
% large} error.
% \item Subnormals are not implemented.
@@ -1226,12 +1295,6 @@
% \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?
-% \item (Likely not.)
-% Change the internal representation of fp, by replacing braced
-% groups of $4$ digits by delimited arguments. Also consider
-% changing the fp structure a bit to allow using
-% \cs{pdftex_strcmp:D} to compare (not in \LuaTeX{}: it is too
-% slow)?
% \item Support multi-character prefix operators (\emph{e.g.}, |@/| or
% whatever)? Perhaps for including comments inside the computation
% itself??