diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3fp.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/l3fp.dtx | 151 |
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}. |