diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3fp.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3fp.dtx | 225 |
1 files changed, 175 insertions, 50 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx b/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx index d4f0a435ec9..dc000923765 100644 --- a/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx +++ b/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -%% File: l3fp.dtx Copyright (C) 2011-2012 The LaTeX3 Project +%% File: l3fp.dtx Copyright (C) 2011-2013 The LaTeX3 Project %% %% It may be distributed and/or modified under the conditions of the %% LaTeX Project Public License (LPPL), either version 1.3c of this @@ -36,7 +36,7 @@ % %<*driver|package> \RequirePackage{l3bootstrap} -\GetIdInfo$Id: l3fp.dtx 4521 2013-07-09 11:45:31Z joseph $ +\GetIdInfo$Id: l3fp.dtx 4601 2013-11-18 23:13:28Z bruno $ {L3 Floating points} %</driver|package> %<*driver> @@ -91,11 +91,19 @@ % operator $x\mathop{?}y\mathop{:}z$. % \item Exponentials: $\exp x$, $\ln x$, $x^y$. % \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$, -% $\operatorname{asec} x$, $\operatorname{acsc} x$. +% x$, $\csc x$ expecting their arguments in radians, and +% $\operatorname{sind} x$, $\operatorname{cosd} x$, +% $\operatorname{tand} x$, $\operatorname{cotd} x$, +% $\operatorname{secd} x$, $\operatorname{cscd} x$ expecting their +% arguments in degrees. +% \item Inverse trigonometric functions: $\operatorname{asin} x$, +% $\operatorname{acos} x$, $\operatorname{atan} x$, +% $\operatorname{acot} x$, $\operatorname{asec} x$, +% $\operatorname{acsc} x$ giving a result in radians, and +% $\operatorname{asind} x$, $\operatorname{acosd} x$, +% $\operatorname{atand} x$, $\operatorname{acotd} x$, +% $\operatorname{asecd} x$, $\operatorname{acscd} x$ giving a result +% in degrees. % \item [\emph{(not yet)}] Hyperbolic functions and their inverse % functions: $\sinh x$, $\cosh x$, $\tanh x$, $\coth x$, % $\operatorname{sech} x$, $\operatorname{csch}$, and @@ -490,7 +498,7 @@ % \begin{variable}[added = 2012-05-08]{\c_zero_fp, \c_minus_zero_fp} % Zero, with either sign. % \end{variable} -% +% % \begin{variable}[added = 2012-05-08]{\c_one_fp} % One as an \texttt{fp}: useful for comparisons in some places. % \end{variable} @@ -504,18 +512,18 @@ % The value of the base of the natural logarithm, $\mathrm{e} = \exp(1)$. % \end{variable} % -% \begin{variable}[updated = 2012-05-08]{\c_pi_fp} +% \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 is rounded in a slightly odd -% way, to ensure for instance that \texttt{sin(pi)} yields an exact $0$. +% expression as \texttt{pi}. % \end{variable} % -% \begin{variable}[added = 2012-05-08]{\c_one_degree_fp} +% \begin{variable}[added = 2012-05-08, updated = 2013-11-17] +% {\c_one_degree_fp} % 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 as \texttt{deg}. Note that -% \texttt{180 deg = pi} exactly. +% degrees by this value to obtain a result in radians. Note that +% trigonometric functions expecting an argument in radians or in +% degrees are both available. Within floating point expressions, this +% can be accessed as \texttt{deg}. % \end{variable} % % \begin{variable}{\l_tmpa_fp, \l_tmpb_fp} @@ -711,7 +719,8 @@ % expressions, in order of decreasing precedence: operations listed % earlier bind more tightly than operations listed below them. % \begin{itemize} -% \item Implicit multiplication by juxtaposition (\texttt{2pi}, \emph{etc}). +% \item Implicit multiplication by juxtaposition (\texttt{2pi}, +% \texttt{3(4+5)}, \emph{etc}). % \item Function calls (\texttt{sin}, \texttt{ln}, \emph{etc}). % \item Binary |**| and |^| (right associative). % \item Unary |+|, |-|, |!|. @@ -907,7 +916,8 @@ % (this cannot happen unless $\meta{fpexpr_2}\string<-9984$). % \end{function} % -% \begin{function}[tested = m3fp-trig001]{sin, cos, tan, cot, csc, sec} +% \begin{function}[updated = 2013-11-17, 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} |)| \} @@ -917,7 +927,34 @@ % \cs{fp_eval:n} \{ |sec(| \meta{fpexpr} |)| \} % \end{syntax} % Computes the sine, cosine, tangent, cotangent, cosecant, or secant -% of the \meta{fpexpr}. The trigonometric functions are undefined for +% of the \meta{fpexpr} given in radians. For arguments given in +% degrees, see \texttt{sind}, \texttt{cosd}, \emph{etc.} Note that +% since $\pi$~is irrational, $\operatorname{sin}(8pi)$ is not quite +% zero, while its analog $\operatorname{sind}(8\times 180)$ is exactly +% zero. 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{function}[added = 2013-11-02, tested = m3fp-trig003] +% {sind, cosd, tand, cotd, cscd, secd} +% \begin{syntax} +% \cs{fp_eval:n} \{ |sind(| \meta{fpexpr} |)| \} +% \cs{fp_eval:n} \{ |cosd(| \meta{fpexpr} |)| \} +% \cs{fp_eval:n} \{ |tand(| \meta{fpexpr} |)| \} +% \cs{fp_eval:n} \{ |cotd(| \meta{fpexpr} |)| \} +% \cs{fp_eval:n} \{ |cscd(| \meta{fpexpr} |)| \} +% \cs{fp_eval:n} \{ |secd(| \meta{fpexpr} |)| \} +% \end{syntax} +% Computes the sine, cosine, tangent, cotangent, cosecant, or secant +% of the \meta{fpexpr} given in degrees. For arguments given in +% radians, see \texttt{sin}, \texttt{cos}, \emph{etc.} Note that +% since $\pi$~is irrational, $\operatorname{sin}(8pi)$ is not quite +% zero, while its analog $\operatorname{sind}(8\times 180)$ is exactly +% zero. 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 @@ -925,6 +962,102 @@ % \enquote{overflow} occur when appropriate. % \end{function} % +% \begin{function}[added = 2013-11-02, tested = m3fp-trig002] +% {asin, acos, acsc, asec} +% \begin{syntax} +% \cs{fp_eval:n} \{ |asin(| \meta{fpexpr} |)| \} +% \cs{fp_eval:n} \{ |acos(| \meta{fpexpr} |)| \} +% \cs{fp_eval:n} \{ |acsc(| \meta{fpexpr} |)| \} +% \cs{fp_eval:n} \{ |asec(| \meta{fpexpr} |)| \} +% \end{syntax} +% Computes the arcsine, arccosine, arccosecant, or arcsecant of the +% \meta{fpexpr} and returns the result in radians, in the range +% $[-\pi/2,\pi/2]$ for \texttt{asin} and \texttt{acsc} and $[0,\pi]$ +% for \texttt{acos} and \texttt{asec}. For a result in degrees, use +% \texttt{asind}, \emph{etc.} If the argument of |asin| or |acos| +% lies outside the range $[-1,1]$, or the argument of |acsc| or |asec| +% inside the range $(-1,1)$, an \enquote{invalid operation} exception +% is raised. \enquote{Underflow} and \enquote{overflow} occur when +% appropriate. +% \end{function} +% +% \begin{function}[added = 2013-11-02, tested = m3fp-trig004] +% {asind, acosd, acscd, asecd} +% \begin{syntax} +% \cs{fp_eval:n} \{ |asind(| \meta{fpexpr} |)| \} +% \cs{fp_eval:n} \{ |acosd(| \meta{fpexpr} |)| \} +% \cs{fp_eval:n} \{ |acscd(| \meta{fpexpr} |)| \} +% \cs{fp_eval:n} \{ |asecd(| \meta{fpexpr} |)| \} +% \end{syntax} +% Computes the arcsine, arccosine, arccosecant, or arcsecant of the +% \meta{fpexpr} and returns the result in degrees, in the range +% $[-90,90]$ for \texttt{asin} and \texttt{acsc} and $[0,180]$ for +% \texttt{acos} and \texttt{asec}. For a result in radians, use +% \texttt{asin}, \emph{etc.} If the argument of |asin| or |acos| lies +% outside the range $[-1,1]$, or the argument of |acsc| or |asec| +% inside the range $(-1,1)$, an \enquote{invalid operation} exception +% is raised. \enquote{Underflow} and \enquote{overflow} occur when +% appropriate. +% \end{function} +% +% \begin{function}[added = 2013-11-02, tested = m3fp-trig002] +% {atan, acot} +% \begin{syntax} +% \cs{fp_eval:n} \{ |atan(| \meta{fpexpr} |)| \} +% \cs{fp_eval:n} \{ |atan(| \meta{fpexpr_1} , \meta{fpexpr_2} |)| \} +% \cs{fp_eval:n} \{ |acot(| \meta{fpexpr} |)| \} +% \cs{fp_eval:n} \{ |acot(| \meta{fpexpr_1} , \meta{fpexpr_2} |)| \} +% \end{syntax} +% Those functions yield an angle in radians: \texttt{atand} and +% \texttt{acotd} are their analogs in degrees. The one-argument +% versions compute the arctangent or arccotangent of the +% \meta{fpexpr}: arctangent takes values in the range +% $[-\pi/2,\pi/2]$, and arccotangent in the range $[0,\pi]$. The +% two-argument arctangent computes the angle in polar coordinates of +% the point with Cartesian coordinates $(\meta{fpexpr_2}, +% \meta{fpexpr_1})$: this is the arctangent of +% $\meta{fpexpr_1}/\meta{fpexpr_2}$, possibly shifted by~$\pi$ +% depending on the signs of \meta{fpexpr_1} and \meta{fpexpr_2}. The +% two-argument arccotangent computes the angle in polar coordinates of +% the point $(\meta{fpexpr_1}, \meta{fpexpr_2})$, equal to the +% arccotangent of $\meta{fpexpr_1}/\meta{fpexpr_2}$, possibly shifted +% by~$\pi$. Both two-argument functions take values in the wider +% range $[-\pi,\pi]$. The ratio $\meta{fpexpr_1}/\meta{fpexpr_2}$ +% need not be defined for the two-argument arctangent: when both +% expressions yield~$\pm 0$, or when both yield~$\pm\infty$, the +% resulting angle is one of $\{\pm\pi/4,\pm 3\pi/4\}$ depending on +% signs. Only the \enquote{underflow} exception can occur. +% \end{function} +% +% \begin{function}[added = 2013-11-02, tested = m3fp-trig004] +% {atand, acotd} +% \begin{syntax} +% \cs{fp_eval:n} \{ |atand(| \meta{fpexpr} |)| \} +% \cs{fp_eval:n} \{ |atand(| \meta{fpexpr_1} , \meta{fpexpr_2} |)| \} +% \cs{fp_eval:n} \{ |acotd(| \meta{fpexpr} |)| \} +% \cs{fp_eval:n} \{ |acotd(| \meta{fpexpr_1} , \meta{fpexpr_2} |)| \} +% \end{syntax} +% Those functions yield an angle in degrees: \texttt{atand} and +% \texttt{acotd} are their analogs in radians. The one-argument +% versions compute the arctangent or arccotangent of the +% \meta{fpexpr}: arctangent takes values in the range $[-90,90]$, and +% arccotangent in the range $[0,180]$. The two-argument arctangent +% computes the angle in polar coordinates of the point with Cartesian +% coordinates $(\meta{fpexpr_2}, \meta{fpexpr_1})$: this is the +% arctangent of $\meta{fpexpr_1}/\meta{fpexpr_2}$, possibly shifted +% by~$180$ depending on the signs of \meta{fpexpr_1} and +% \meta{fpexpr_2}. The two-argument arccotangent computes the angle +% in polar coordinates of the point $(\meta{fpexpr_1}, +% \meta{fpexpr_2})$, equal to the arccotangent of +% $\meta{fpexpr_1}/\meta{fpexpr_2}$, possibly shifted by~$180$. Both +% two-argument functions take values in the wider range $[-180,180]$. +% The ratio $\meta{fpexpr_1}/\meta{fpexpr_2}$ need not be defined for +% the two-argument arctangent: when both expressions yield~$\pm 0$, or +% when both yield~$\pm\infty$, the resulting angle is one of $\{\pm +% 45,\pm 135\}$ depending on signs. Only the \enquote{underflow} +% exception can occur. +% \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}, @@ -1004,22 +1137,16 @@ % % \section{Disclaimer and roadmap} % -% The package may break down if: -% \begin{itemize} -% \item the escape character is either a digit, or an underscore, -% \item the \tn{uccodes} are changed: the test for whether a character -% is a letter actually tests if the upper-case code of the character -% is between A and Z. -% \end{itemize} +% The package may break down if the escape character is among +% |0123456789_+|; if it receives a \TeX{} primitive conditional affected +% by \cs{exp_not:N}. % % 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 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 Improve the treatment of signalling versus quiet \texttt{nan}. % \item Modulo and remainder, and rounding functions |quantize|, % |quantize0|, |quantize+|, |quantize-|, |quantize=|, |round=|. % Should the modulo also be provided as (catcode 12) |%|? @@ -1027,14 +1154,9 @@ % \meta{format} be? More general pretty printing? % \item Add |and|, |or|, |xor|? Perhaps under the names \texttt{all}, % \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 -% $\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). -% Also \texttt{asec}, \texttt{acsc}? +% \item \texttt{hypot} (Euclidean length). +% Cartesian-to-polar transform. % \item Hyperbolic functions \texttt{cosh}, \texttt{sinh}, \texttt{tanh}. % \item Inverse hyperbolics. % \item Base conversion, input such as \texttt{0xAB.CDEF}. @@ -1045,42 +1167,37 @@ % 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$. % \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}, and an |isnan| function? +% \item Support keyword arguments? % \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[!] Some functions are not monotonic when they should. For -% instance, $\sin(1-10^{-16})$ is wrongly greater than $\sin(1)$. +% \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 \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 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 Optimize argument reduction for trigonometric functions: we -% don't need $6\times 4$ digits here, only $4\times 4$. +% \item Document that \pkg{l3trial/l3fp-types} introduces tools for +% adding new types. % \item In subsection~\ref{sec:l3fp: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 @@ -1096,8 +1213,7 @@ % 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{__fp_fixed_div_to_float:ww}. However, we would then have to +% simplify the computation of $t$. 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}). @@ -1110,6 +1226,15 @@ % \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?? % \end{itemize} % % \end{documentation} |