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.dtx225
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}