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.dtx151
1 files changed, 73 insertions, 78 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx b/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx
index ea20f8d1bc8..14b450c1320 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-2016 The LaTeX3 Project
+%% File: l3fp.dtx Copyright (C) 2011-2017 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
@@ -24,7 +24,7 @@
\documentclass[full]{l3doc}
%</driver>
%<*driver|package>
-\GetIdInfo$Id: l3fp.dtx 6805 2016-12-28 22:15:52Z joseph $
+\GetIdInfo$Id: l3fp.dtx 6923 2017-02-14 03:07:25Z bruno $
{L3 Floating points}
%</driver|package>
%<*driver>
@@ -136,12 +136,15 @@
% for higher-level commands. For example, one could provide a function
% to typeset nicely the result of floating point computations.
% \begin{verbatim}
+% \documentclass{article}
% \usepackage{xparse, siunitx}
% \ExplSyntaxOn
% \NewDocumentCommand { \calcnum } { m }
% { \num { \fp_to_scientific:n {#1} } }
% \ExplSyntaxOff
+% \begin{document}
% \calcnum { 2 pi * sin ( 2.3 ^ 5 ) }
+% \end{document}
% \end{verbatim}
%
% \section{Creating and initialising floating point variables}
@@ -315,7 +318,7 @@
% 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 and no decimal
-% separator when there is a single significant digit (see
+% separator when there is a single significant digit (this differs from
% \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
@@ -362,7 +365,7 @@
% \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 either operand is~\nan{}, and this relation
+% case occurs exactly when one or both operands 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
@@ -406,7 +409,7 @@
% 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
+% latter case occurs exactly when one or both 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
@@ -632,7 +635,8 @@
%
% \enquote{Exceptions} may occur when performing some floating point
% operations, such as \texttt{0 / 0}, or \texttt{10 ** 1e9999}. The
-% \textsc{IEEE} standard defines $5$ types of exceptions.
+% relevant \textsc{IEEE} standard defines $5$ types of exceptions,
+% of which we implement~$4$.
% \begin{itemize}
% \item \emph{Overflow} occurs whenever the result of an operation is
% too large to be represented as a normal floating point number. This
@@ -641,68 +645,38 @@
% too close to $0$ to be represented as a normal floating point
% 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 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}).
+% outcome, for instance $0/0$ or $\sin(\infty)$, and results in a \nan{}.
+% It also occurs for conversion functions whose target type does not
+% have the appropriate infinite or \nan{} value (\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. At the moment, this
-% exception is entirely ignored in \LaTeX3.
+% by $0$, or when evaluating functions at poles, \emph{e.g.},
+% $\ln(0)$ or $\cot(0)$. This results in $\pm\infty$.
+% \item [\emph{(not yet)}] \emph{Inexact} occurs whenever the result of
+% a computation is 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, 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-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-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-08-08, tested = m3fp-traps001]
-% {\fp_flag_on:n}
-% \begin{syntax}
-% \cs{fp_flag_on:n} \Arg{exception}
-% \end{syntax}
-% Locally turns on the flag to indicate (or pretend) that the
-% \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-07-19, updated = 2012-08-08,
+% To each exception we associate a \enquote{flag}: \texttt{fp_overflow},
+% \texttt{fp_underflow}, \texttt{fp_invalid_operation} and
+% \texttt{fp_division_by_zero}. The state of these flags can be tested
+% and modified with commands from \pkg{l3flag}
+%
+% By default, the \enquote{invalid operation} exception triggers an
+% (expandable) error, and raises the corresponding flag. Other
+% exceptions raise the corresponding flag but do not trigger an error.
+% The behaviour when an exception occurs can be modified (using
+% \cs{fp_trap:nn}) to either produce an error and raise the flag, or
+% only raise the flag, or do nothing at all.
+%
+% \begin{function}[added = 2012-07-19, updated = 2017-02-13,
% tested = m3fp-traps001]{\fp_trap:nn}
% \begin{syntax}
% \cs{fp_trap:nn} \Arg{exception} \Arg{trap type}
% \end{syntax}
-% All occurrences of the \meta{exception} (\texttt{invalid_operation},
-% \texttt{division_by_zero}, \texttt{overflow}, or \texttt{underflow})
-% within the current group are treated as \meta{trap type}, which can
-% be
+% All occurrences of the \meta{exception} (\texttt{overflow},
+% \texttt{underflow}, \texttt{invalid_operation} or
+% \texttt{division_by_zero}) within the current
+% group are treated as \meta{trap type}, which can be
% \begin{itemize}
% \item \texttt{none}: the \meta{exception} will be entirely
% ignored, and leave no trace;
@@ -715,6 +689,16 @@
% \emph{This function is experimental, and may be altered or removed.}
% \end{function}
%
+% \begin{variable}
+% {
+% flag fp_overflow,
+% flag fp_underflow,
+% flag fp_invalid_operation,
+% flag fp_division_by_zero
+% }
+% Flags denoting the occurrence of various floating-point exceptions.
+% \end{variable}
+%
% \section{Viewing floating points}
%
% \begin{function}[added = 2012-05-08, updated = 2015-08-07,
@@ -727,6 +711,16 @@
% result in the terminal.
% \end{function}
%
+% \begin{function}[added = 2014-08-22, updated = 2015-08-07]
+% {\fp_log:N, \fp_log:c, \fp_log:n}
+% \begin{syntax}
+% \cs{fp_log:N} \meta{fp~var}
+% \cs{fp_log:n} \Arg{floating point expression}
+% \end{syntax}
+% Evaluates the \meta{floating point expression} and writes the
+% result in the log file.
+% \end{function}
+%
% \section{Floating point expressions}
%
% \subsection{Input of floating point numbers} \label{sec:l3fp:fp-floats}
@@ -774,11 +768,17 @@
% replaced by $\pm\infty$), or an underflow (resulting in $\pm 0$).
%
% The result is thus $\pm 0$ if and only if \meta{significand} contains no
-% non-zero digit (\emph{i.e.}, consists only in~|0| characters, and an
-% optional |.| character), or if there is an underflow. Note that a
+% non-zero digit (\emph{i.e.}, consists only in characters~|0|, and an
+% optional period), or if there is an underflow. Note that a
% single dot is currently a valid floating point number, equal to~$+0$,
% but that is not guaranteed to remain true.
%
+% The \meta{significand} must be non-empty, so |e1| and |e-1| are not
+% valid floating point numbers. Note that the latter could be mistaken
+% with the difference of \enquote{\texttt{e}} and $1$. To avoid
+% confusions, the base of natural logarithms cannot be input as |e| and
+% should be input as \texttt{exp(1)} or \cs{c_e_fp}.
+%
% Special numbers are input as follows:
% \begin{itemize}
% \item \texttt{inf} represents $+\infty$, and can be preceded by any
@@ -789,13 +789,6 @@
% \nan{}.
% \end{itemize}
%
-% Note that~|e-1| is not a representation of $10^{-1}$, because it could
-% be mistaken with the difference of \enquote{\texttt{e}} and $1$. This
-% is consistent with several other programming languages. However, in
-% order to avoid confusions, |e-1| is not considered to be this
-% difference either. To input the base of natural logarithms, use
-% \texttt{exp(1)} or \cs{c_e_fp}.
-%
% \subsection{Precedence of operators}
% \label{sec:l3fp:fp-precedence}
%
@@ -932,11 +925,14 @@
% \end{syntax}
% Raises \meta{operand_1} to the power \meta{operand_2}. This
% operation is right associative, hence \texttt{2 ** 2 ** 3} equals
-% $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, unless the result is zero (in that case, the sign is
-% chosen arbitrarily to be $+0$). \enquote{Division by zero} occurs
-% when raising $\pm 0$ to a strictly negative power.
+% $2^{2^{3}} = 256$. If \meta{operand_1} is negative or $-0$ then:
+% the result's sign is $+$ if the \meta{operand_2} is infinite and
+% $(-1)^p$ if the \meta{operand_2} is $p/q$ with $p$ integer and $q$
+% odd; the result is $+0$ if
+% |abs(|\meta{operand_1}|)^|\meta{operand_2} evaluates to zero; in
+% other cases the \enquote{invalid operation} exception occurs because
+% the sign cannot be determined. \enquote{Division by zero} occurs
+% when raising $\pm 0$ to a finite strictly negative power.
% \enquote{Underflow} and \enquote{overflow} occur when appropriate.
% \end{function}
%
@@ -1281,7 +1277,7 @@
% \section{Disclaimer and roadmap}
%
% The package may break down if the escape character is among
-% |0123456789_+|; if it receives a \TeX{} primitive conditional affected
+% |0123456789_+|, or 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.
@@ -1336,7 +1332,6 @@
% \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
% operation were set up in the corresponding module, rather than
% centralizing in \pkg{l3fp-parse}.