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.dtx193
1 files changed, 128 insertions, 65 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx b/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx
index 68f71f540cc..059ca848304 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx
@@ -35,8 +35,8 @@
%%
%
%<*driver|package>
-\RequirePackage{l3names}
-\GetIdInfo$Id: l3fp.dtx 3986 2012-07-15 19:23:51Z joseph $
+\RequirePackage{l3bootstrap}
+\GetIdInfo$Id: l3fp.dtx 4089 2012-08-14 04:52:20Z bruno $
{L3 Floating points}
%</driver|package>
%<*driver>
@@ -71,33 +71,40 @@
%
% \begin{documentation}
%
-% A 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 mantissa and a
% separate exponent. The module implements expandably a wide set of
-% arithmetic, trigonometric, and other operations on floating point
+% arithmetic, trigonometric, and other operations on decimal floating point
% numbers, to be used within floating point expressions. Floating point
% expressions support the following operations with their usual
% precedence.
% \begin{itemize}
% \item Basic arithmetic: addition $x+y$, subtraction $x-y$,
% multiplication $x*y$, division $x/y$, and parentheses.
-% \item Trigonometry: $\sin x$, $\cos x$, $\tan x$, $\cot x$.
+% \item Comparison operators: $x\mathop{\mathtt{<}}y$,
+% $x\mathop{\mathtt{<=}}y$, $x\mathop{\mathtt{>?}}y$,
+% $x\mathop{\mathtt{!=}}y$ \emph{etc.}
+% \item Boolean logic: negation $\mathop{!}x$, conjunction
+% $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 Comparison operators: $x<y$, $x<=y$, $x>?y$, $x!=y$ \emph{etc.}
-% \item Boolean logic: negation $!x$, conjunction $\&\&$, disjunction
-% $\vert\vert$, ternary operator $x?y:z$.
-% \item [\emph{not yet}] Inverse trigonometric functions:
+% \item Trigonometry: $\sin x$, $\cos x$, $\tan x$, $\cot x$.
+% \emph{Not yet:} $\sec x$, $\csc x$.
+% \item [\emph{(not yet)}] Inverse trigonometric functions:
% $\operatorname{asin} x$, $\operatorname{acos} x$,
-% $\operatorname{atan} x$, $\operatorname{acot} x$.
-% \item [\emph{not yet}] Hyperbolic functions and their inverse
-% functions: $\sinh x$, $\cosh x$, $\tanh x$, $\coth x$, and
+% $\operatorname{atan} x$, $\operatorname{acot} x$,
+% $\operatorname{asec} x$, $\operatorname{acsc} x$.
+% \item [\emph{(not yet)}] Hyperbolic functions and their inverse
+% functions: $\sinh x$, $\cosh x$, $\tanh x$, $\coth x$,
+% $\operatorname{sech} x$, $\operatorname{csch}$, and
% $\operatorname{asinh} x$, $\operatorname{acosh} x$,
-% $\operatorname{atanh} x$, $\operatorname{acoth} x$.
+% $\operatorname{atanh} x$, $\operatorname{acoth} x$,
+% $\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{round} 0(x,n)$ round towards zero,
-% $\operatorname{round}\pm(x,n)$ round towards $\pm\infty$. And
-% (\emph{not yet}) modulo, and \enquote{quantize}.
+% closest, $\operatorname{round0}(x,n)$ round towards zero,
+% $\operatorname{round\pm}(x,n)$ round towards $\pm\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$.
@@ -134,7 +141,8 @@
%
% \section{Creating and initialising floating point variables}
%
-% \begin{function}[updated = 2012-05-08]{\fp_new:N, \fp_new:c}
+% \begin{function}[updated = 2012-05-08, tested = m3fp001]
+% {\fp_new:N, \fp_new:c}
% \begin{syntax}
% \cs{fp_new:N} \meta{fp~var}
% \end{syntax}
@@ -143,7 +151,8 @@
% initially be $+0$.
% \end{function}
%
-% \begin{function}[updated = 2012-05-08]{\fp_const:Nn, \fp_const:cn}
+% \begin{function}[updated = 2012-05-08, tested = m3fp001]
+% {\fp_const:Nn, \fp_const:cn}
% \begin{syntax}
% \cs{fp_const:Nn} \meta{fp~var} \Arg{floating point expression}
% \end{syntax}
@@ -152,7 +161,7 @@
% the result of evaluating the \meta{floating point expression}.
% \end{function}
%
-% \begin{function}[updated = 2012-05-08]
+% \begin{function}[updated = 2012-05-08, tested = m3fp001]
% {\fp_zero:N, \fp_zero:c, \fp_gzero:N, \fp_gzero:c}
% \begin{syntax}
% \cs{fp_zero:N} \meta{fp~var}
@@ -160,7 +169,7 @@
% Sets the \meta{fp~var} to~$+0$.
% \end{function}
%
-% \begin{function}[updated = 2012-05-08]
+% \begin{function}[updated = 2012-05-08, tested = m3fp001]
% {\fp_zero_new:N, \fp_zero_new:c, \fp_gzero_new:N, \fp_gzero_new:c}
% \begin{syntax}
% \cs{fp_zero_new:N} \meta{fp~var}
@@ -250,10 +259,11 @@
% Evaluates the \meta{floating point expression} and expresses the
% 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, floating point
-% numbers outside the range $[- 2^{14} + 2^{-17}, 2^{14} - 2^{-17}]$
-% overflow \TeX{}'s maximum dimension. The values $\pm\infty$ and
-% \texttt{nan} trigger an \enquote{invalid operation} exception.
+% 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
+% \enquote{invalid operation} exception.
% \end{function}
%
% \begin{function}[EXP, updated = 2012-07-08]
@@ -293,15 +303,16 @@
% \cs{fp_to_tl:n} \Arg{floating point expression}
% \end{syntax}
% Evaluates the \meta{floating point expression} and expresses the
-% result in (almost) the shortest possible form. Numbers greater or
-% equal to $10^{16}$, or less than $10^{-3}$ are expressed in
+% 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
% \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}. The special values $\pm 0$, $\pm \inf$ and
-% \texttt{nan} are rendered as |0|, |-0|, \texttt{inf}, \texttt{-inf},
-% and \texttt{nan} respectively.
+% \cs{fp_to_decimal:n}. Negative numbers start with |-|. The
+% special values $\pm 0$, $\pm \inf$ and \texttt{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}
@@ -384,7 +395,8 @@
% The value of $1^{\circ}$ in radians. Multiply an angle given in
% degrees by this value to obtain a result in radians, suitable to be
% used for trigonometric functions. Within floating point
-% expressions, this can be accessed by \texttt{deg}.
+% expressions, this can be accessed as \texttt{deg}. Note that
+% \texttt{180 deg = pi} exactly.
% \end{variable}
%
% \begin{variable}{\l_tmpa_fp, \l_tmpb_fp}
@@ -403,7 +415,9 @@
%
% \section{Floating point exceptions}
% \label{sec:fp-exceptions}
-%^^A todo: redoc
+%
+% \emph{The functions defined in this section are experimental, and
+% their functionality may be altered or removed altogether.}
%
% \enquote{Exceptions} may occur when performing some floating point
% operations, such as \texttt{0 / 0}, or \texttt{10 ** 1e9999}. The
@@ -417,39 +431,48 @@
% number. This results in $\pm 0$.
% \item \emph{Invalid operation} occurs for operations with no defined
% outcome, for instance $0/0$, or $\sin(\infty)$, and almost any
-% operation involving a \nan{}. This results in a \nan{}.
+% operation involving a \nan{}. This normally results in a \nan{},
+% except for conversion functions whose target type does not have a
+% notion of \nan{} (\emph{e.g.}, \cs{fp_to_dim:n}).
% \item \emph{Division by zero} occurs when dividing a non-zero number
% by $0$, or when evaluating \emph{e.g.}, $\ln(0)$ or $\cot(0)$. This
% results in $\pm\infty$.
% \item \emph{Inexact} occurs whenever the result of a computation is
-% not exact, in other words, almost always. This exception is
-% entirely ignored in \LaTeX3.
+% not exact, in other words, almost always. At the moment, this
+% exception is entirely ignored in \LaTeX3.
% \end{itemize}
% To each exception is associated a \enquote{flag}, which can be either
-% \emph{on} or \emph{off}. By default, when an exception occurs, the
-% corresponding flag is turned on. The state of the flag can be tested
+% \emph{on} or \emph{off}. By default, the \enquote{invalid operation}
+% exception triggers an (expandable) error, and raises the corresponding
+% flag. Other exceptions only raise the corresponding flag. The state
+% of the flag can be tested
% and modified. The behaviour when an exception occurs can be modified
% (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-05-28]{\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}
% \end{syntax}
% Tests if the flag for the \meta{exception} is on, which normally
% means the given \meta{exception} has occurred.
+% \emph{This function is experimental, and may be altered or removed.}
% \end{function}
%
-% \begin{function}[added = 2012-05-28]{\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}
% Locally turns off the flag which indicates whether the
% \meta{exception} has occurred.
+% \emph{This function is experimental, and may be altered or removed.}
% \end{function}
%
-% \begin{function}[EXP, added = 2012-05-28]{\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}
@@ -457,9 +480,11 @@
% \meta{exception} has occurred. Note that this function is
% expandable: it is used internally by \pkg{l3fp} to signal when
% exceptions do occur.
+% \emph{This function is experimental, and may be altered or removed.}
% \end{function}
%
-% \begin{function}[added = 2012-05-28]{\fp_trap:nn}
+% \begin{function}[added = 2012-07-19, updated = 2012-08-08,
+% tested = m3fp-traps001]{\fp_trap:nn}
% \begin{syntax}
% \cs{fp_trap:nn} \Arg{exception} \Arg{trap type}
% \end{syntax}
@@ -476,9 +501,10 @@
% the \TeX{} run and display some information about the current
% operation in the terminal.
% \end{itemize}
+% \emph{This function is experimental, and may be altered or removed.}
% \end{function}
%
-% \section{Floating point expressions}
+% \section{Viewing floating points}
%
% \begin{function}[added = 2012-05-08, updated = 2012-05-27]
% {\fp_show:N, \fp_show:c, \fp_show:n}
@@ -490,10 +516,12 @@
% result in the terminal.
% \end{function}
%
+% \section{Floating point expressions}
+%
% \subsection{Input of floating point numbers} \label{sec:fp-floats}
%
-%^^A todo: write a grammar
-%^^A todo: clarify what has changed compared to the previous l3fp
+% ^^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}
@@ -505,7 +533,7 @@
% \item \texttt{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}
+% \item [\emph{(not yet)}] subnormal numbers $\pm 0.d_1d_2\ldots{}d_{16}
% \cdot 10^{-\ExplSyntaxOn\int_use:N \c__fp_max_exponent_int}$ with
% $d_1=0$.
% \end{itemize}
@@ -562,8 +590,6 @@
% \subsection{Precedence of operators}
% \label{sec:fp-precedence}
%
-% ^^A List "juxtaposition" somewhere in the list.
-%
% We list here all the operations supported in floating point
% expressions, in order of decreasing precedence: operations listed
% earlier bind more tightly than operations listed below them.
@@ -592,9 +618,11 @@
%
% 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{false} otherwise.
+% is \texttt{false} if it is $\pm 0$, and \texttt{true} otherwise.
%
-% The exceptions listed below are mostly not implemented yet. ^^A todo:
+% 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{syntax}
@@ -621,7 +649,7 @@
% \end{function}
%
% \begingroup \catcode`\|=12
-% \begin{function}{TWO BARS} ^^A To fix
+% \begin{function}{TWO BARS} ^^A todo:fix
% \begin{syntax}
% \cs{fp_eval:n} \{ \meta{operand_1} \texttt{||} \meta{operand_2} \}
% \end{syntax}
@@ -696,8 +724,8 @@
% \end{syntax}
% Raises \meta{operand_1} to the power \meta{operand_2}. This operation
% is right associative, hence \texttt{2 ** 2 ** 3} equals
-% $2\sp{2\sp{3}} = 256$. The \enquote{invalid operation} exception
-% occurs if \meta{operand_1} is negative or $-0$, \meta{operand_2} is
+% $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
@@ -710,7 +738,8 @@
% \cs{fp_eval:n} \{ |abs(| \meta{fpexpr} |)| \}
% \end{syntax}
% Computes the absolute value of the \meta{fpexpr}. This function
-% never raises an exception when \meta{fpexpr} is a number.
+% does not raise any exception beyond those raised when computing its
+% operand \meta{fpexpr}.
% \end{function}
%
% \begin{function}{exp}
@@ -718,7 +747,7 @@
% \cs{fp_eval:n} \{ |exp(| \meta{fpexpr} |)| \}
% \end{syntax}
% Computes the exponential of the \meta{fpexpr}. The
-% \enquote{inexact}, \enquote{underflow} and \enquote{overflow}
+% \enquote{underflow} and \enquote{overflow}
% exceptions occur when appropriate.
% \end{function}
%
@@ -728,9 +757,9 @@
% \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. \enquote{Division by zero}
-% occurs when evaluating the logarithm of $\pm 0$. The
-% \enquote{inexact}, \enquote{underflow} and \enquote{overflow}
+% 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.
% \end{function}
%
@@ -822,7 +851,10 @@
% \cs{dim_to_fp:n} \Arg{dimexpr}
% \end{syntax}
% Expands to an internal floating point number equal to the value of
-% the \meta{dimexpr} in \texttt{pt}.
+% the \meta{dimexpr} in \texttt{pt}. Since dimension expressions are
+% evaluated much faster than their floating point equivalent,
+% \cs{dim_to_fp:n} can be used to speed up parts of a computation
+% where a low precision is acceptable.
% \end{function}
%
% \begin{function}[EXP, added = 2012-05-14, updated = 2012-07-08]{\fp_abs:n}
@@ -862,7 +894,10 @@
% \begin{itemize}
% \item Decide what exponent range to consider.
% \item Change the internal representation of fp, by replacing braced
-% groups of $4$ digits by delimited arguments.
+% 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 Modulo and remainder, and rounding functions |quantize|,
% |quantize0|, |quantize+|, |quantize-|, |quantize=|, |round=|.
% Should the modulo also be provided as (catcode 12) |%|?
@@ -891,26 +926,54 @@
% \item Add an |array(1,2,3)| and |i=complex(0,1)|.
% \item Provide an experimental |map| function? Perhaps easier to
% implement if it is a single character, |@sin(1,2)|?
-% \item Provide \cs{fp_if_nan:nTF}?
+% \item Provide \cs{fp_if_nan:nTF}, and an |isnan| function?
% \end{itemize}
% \pkg{Pgfmath} also provides box-measurements (depth, height, width), but
% boxes are not possible expandably.
%
% Bugs. (Exclamation points mark important bugs.)
% \begin{itemize}
-% \item[!] \cs{fp_eval:n} |{nan}| mustn't produce an error.
-% \item $1-10^{-16}$ should not give $1$.
+% \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}$.
% \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 \texttt{0e9999999999} gives a \TeX{} \enquote{number too
% large} error.
-% \item \texttt{tan} and \texttt{cot} give very slightly wrong results
-% for arguments near $10^{-8}$.
-% \item[!] Multiplying $0$ with $\infty$ doesn't trigger an invalid
-% operation error.
% \item Conversion to integers with \cs{fp_to_int:n} does not check
% for overflow.
% \item Subnormals are not implemented.
+% \item |max(-inf)| will lose any information attached to this |-inf|.
+% \item The overflow trap receives the wrong argument in
+% \pkg{l3fp-expo} (see |exp(1e5678)| in \file{m3fp-traps001}).
+% \end{itemize}
+%
+% Possible optimizations/improvements.
+% \begin{itemize}
+% \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}.
+% \item Some functions should get an |_o| ending to indicate that they
+% expand after their result.
+% \item More care should be given to distinguish expandable/restricted
+% expandable (auxiliary and internal) functions.
+% \item The code for the \texttt{ternary} set of functions is ugly.
+% \item There are many |~| missing in the doc to avoid bad line-breaks.
+% \item The algorithm for computing the logarithm of the significand
+% could be made to use a $5$ terms Taylor series instead of $10$
+% terms by taking $c = 2000/(\lfloor 200x\rfloor +1) \in [10,95]$
+% instead of $c\in [1,10]$. Also, it would then be possible to
+% simplify the computation of $t$, using methods similar to
+% \cs{@@_fixed_div_to_float:ww}. However, we would then have to
+% hard-code the logarithms of $44$ small integers instead of $9$.
+% \item Improve notations in the explanations of the division
+% algorithm (\pkg{l3fp-basics}).
+% \item Understand and document \cs{@@_basics_pack_weird_low:NNNNw}
+% and \cs{@@_basics_pack_weird_high:NNNNNNNNw} better. Move the
+% other \texttt{basics_pack} auxiliaries to \pkg{l3fp-aux} under a
+% better name.
% \end{itemize}
%
% \end{documentation}