diff options
author | Karl Berry <karl@freefriends.org> | 2012-08-16 22:41:08 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2012-08-16 22:41:08 +0000 |
commit | ca1c73f9a8de69e467230c4a57ccf8b07cd275a9 (patch) | |
tree | 6272657307f73c14327d6b8bce5d6b7ff97c3f66 /Master/texmf-dist/source/latex/l3kernel/l3fp.dtx | |
parent | 22c251adda514ed7b453066de05b2f89707d0fe6 (diff) |
finish l3 update
git-svn-id: svn://tug.org/texlive/trunk@27427 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 | 193 |
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} |