diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3fp.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3fp.dtx | 229 |
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?? |