path: root/Master/texmf-dist/source/latex/l3kernel/l3fp.dtx

% \iffalse meta-comment
%
%% File: l3fp.dtx Copyright (C) 2011-2012 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
%% license or (at your option) any later version.  The latest version
%% of this license is in the file
%%
%%    http://www.latex-project.org/lppl.txt
%%
%% This file is part of the "l3kernel bundle" (The Work in LPPL)
%% and all files in that bundle must be distributed together.
%%
%% The released version of this bundle is available from CTAN.
%%
%% -----------------------------------------------------------------------
%%
%% The development version of the bundle can be found at
%%
%%    http://www.latex-project.org/svnroot/experimental/trunk/
%%
%% for those people who are interested.
%%
%%%%%%%%%%%
%% NOTE: %%
%%%%%%%%%%%
%%
%%   Snapshots taken from the repository represent work in progress and may
%%   not work or may contain conflicting material!  We therefore ask
%%   people _not_ to put them into distributions, archives, etc. without
%%   prior consultation with the LaTeX3 Project Team.
%%
%% -----------------------------------------------------------------------
%%
%
%<*driver|package>
\RequirePackage{l3names}
\GetIdInfo$Id: l3fp.dtx 3986 2012-07-15 19:23:51Z joseph $
  {L3 Floating points}
%</driver|package>
%<*driver>
\documentclass[full]{l3doc}
\usepackage{amsmath}
\providecommand\nan{\texttt{NaN}}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
%
% \title{^^A
%   The \textsf{l3fp} package: floating points^^A
%   \thanks{This file describes v\ExplFileVersion,
%     last revised \ExplFileDate.}^^A
% }
%
% \author{^^A
%  The \LaTeX3 Project\thanks
%    {^^A
%      E-mail:
%        \href{mailto:latex-team@latex-project.org}
%          {latex-team@latex-project.org}^^A
%    }^^A
% }
%
% \date{Released \ExplFileDate}
%
% \maketitle
%
% \begin{documentation}
%
% A 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
% 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 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:
%     $\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{asinh} x$, $\operatorname{acosh} x$,
%     $\operatorname{atanh} x$, $\operatorname{acoth} 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}.
%   \item Constants: \texttt{pi}, \texttt{deg} (one degree in radians).
%   \item Dimensions, automatically expressed in points, \emph{e.g.},
%     \texttt{pc} is $12$.
%   \item Automatic conversion (no need for \cs{\meta{type}_use:N}) of
%     integer, dimension, and skip variables to floating points,
%     expressing dimensions in points and ignoring the stretch and
%     shrink components of skips.
% \end{itemize}
% Floating point numbers can be given either explicitly (in a form such
% as |1.234e-34|, or |-.0001|), or as a stored floating point variable,
% which is automatically replaced by its current value.  See
% section~\ref{sec:fp-floats} for a description of what a floating point is,
% section~\ref{sec:fp-precedence} for details about how an expression is
% parsed, and section~\ref{sec:fp-operations} to know what the various
% operations do.  Some operations may raise exceptions (error messages),
% described in section~\ref{sec:fp-exceptions}.
%
% An example of use could be the following.
% \begin{verbatim}
%   \LaTeX{} can now compute: $ \frac{\sin (3.5)}{2} + 2\cdot 10^{-3}
%   = \ExplSyntaxOn \fp_to_decimal:n {sin 3.5 /2 + 2e-3} $.
% \end{verbatim}
% But in all fairness, this module is mostly meant as an underlying tool
% for higher-level commands.  For example, one could provide a function
% to typeset nicely the result of floating point computations.
% \begin{verbatim}
%   \usepackage{xparse, siunitx}
%   \ExplSyntaxOn
%   \NewDocumentCommand { \calcnum } { m }
%     { \num { \fp_to_scientific:n {#1} } }
%   \ExplSyntaxOff
%   \calcnum { 2 pi * sin ( 2.3 ^ 5 ) }
% \end{verbatim}
%
% \section{Creating and initialising floating point variables}
%
% \begin{function}[updated = 2012-05-08]{\fp_new:N, \fp_new:c}
%   \begin{syntax}
%     \cs{fp_new:N} \meta{fp~var}
%   \end{syntax}
%   Creates a new \meta{fp~var} or raises an error if the name is
%   already taken. The declaration is global. The \meta{fp~var} will
%   initially be $+0$.
% \end{function}
%
% \begin{function}[updated = 2012-05-08]{\fp_const:Nn, \fp_const:cn}
%   \begin{syntax}
%     \cs{fp_const:Nn} \meta{fp~var} \Arg{floating point expression}
%   \end{syntax}
%   Creates a new constant \meta{fp~var} or raises an error if the name
%   is already taken. The \meta{fp~var} will be set globally equal to
%   the result of evaluating the \meta{floating point expression}.
% \end{function}
%
% \begin{function}[updated = 2012-05-08]
%   {\fp_zero:N, \fp_zero:c, \fp_gzero:N, \fp_gzero:c}
%   \begin{syntax}
%     \cs{fp_zero:N} \meta{fp~var}
%   \end{syntax}
%   Sets the \meta{fp~var} to~$+0$.
% \end{function}
%
% \begin{function}[updated = 2012-05-08]
%   {\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}
%   \end{syntax}
%   Ensures that the \meta{fp~var} exists globally
%   by applying \cs{fp_new:N} if necessary, then applies
%   \cs{fp_(g)zero:N} to leave the \meta{fp~var} set to zero.
% \end{function}
%
% \section{Setting floating point variables}
%
% \begin{function}[updated = 2012-05-08]
%   {\fp_set:Nn, \fp_set:cn, \fp_gset:Nn, \fp_gset:cn}
%   \begin{syntax}
%     \cs{fp_set:Nn} \meta{fp~var} \Arg{floating point expression}
%   \end{syntax}
%   Sets \meta{fp~var} equal to the result of computing the
%   \meta{floating point expression}.
% \end{function}
%
% \begin{function}[updated = 2012-05-08]
%   {
%     \fp_set_eq:NN , \fp_set_eq:cN , \fp_set_eq:Nc , \fp_set_eq:cc ,
%     \fp_gset_eq:NN, \fp_gset_eq:cN, \fp_gset_eq:Nc, \fp_gset_eq:cc
%   }
%   \begin{syntax}
%     \cs{fp_set_eq:NN} \meta{fp~var_1} \meta{fp~var_2}
%   \end{syntax}
%   Sets the floating point variable \meta{fp~var_1} equal to the current
%   value of \meta{fp~var_2}.
% \end{function}
%
% \begin{function}[updated = 2012-05-08]
%   {\fp_add:Nn, \fp_add:cn, \fp_gadd:Nn, \fp_gadd:cn}
%   \begin{syntax}
%     \cs{fp_add:Nn} \meta{fp~var} \Arg{floating point expression}
%   \end{syntax}
%   Adds the result of computing the \meta{floating point expression} to
%   the \meta{fp~var}.
% \end{function}
%
% \begin{function}[updated = 2012-05-08]
%   {\fp_sub:Nn, \fp_sub:cn, \fp_gsub:Nn, \fp_gsub:cn}
%   \begin{syntax}
%     \cs{fp_sub:Nn} \meta{fp~var} \Arg{floating point expression}
%   \end{syntax}
%   Subtracts the result of computing the \meta{floating point
%     expression} from the \meta{fp~var}.
% \end{function}
%
% \section{Using floating point numbers}
%
% \begin{function}[EXP, added = 2012-05-08, updated = 2012-07-08]{\fp_eval:n}
%   \begin{syntax}
%     \cs{fp_eval:n} \Arg{floating point expression}
%   \end{syntax}
%   Evaluates the \meta{floating point expression} and expresses the
%   result as a decimal number with~$16$ significant figures and no
%   exponent.  Leading or trailing zeros may be inserted to compensate
%   for the exponent.  Non-significant trailing zeros are trimmed, and
%   integers are expressed without a decimal separator.  The values
%   $\pm\infty$ and \texttt{nan} trigger an \enquote{invalid operation}
%   exception.  This function is identical to \cs{fp_to_decimal:n}.
% \end{function}
%
% \begin{function}[EXP, added = 2012-05-08, updated = 2012-07-08]
%   {\fp_to_decimal:N, \fp_to_decimal:c, \fp_to_decimal:n}
%   \begin{syntax}
%     \cs{fp_to_decimal:N} \meta{fp~var}
%     \cs{fp_to_decimal:n} \Arg{floating point expression}
%   \end{syntax}
%   Evaluates the \meta{floating point expression} and expresses the
%   result as a decimal number with $16$ significant figures and no
%   exponent.  Leading or trailing zeros may be inserted to compensate
%   for the exponent.  Non-significant trailing zeros are trimmed, and
%   integers are expressed without a decimal separator.  The values
%   $\pm\infty$ and \texttt{nan} trigger an \enquote{invalid operation}
%   exception.
% \end{function}
%
% \begin{function}[EXP, updated = 2012-07-08]
%   {\fp_to_dim:N, \fp_to_dim:c, \fp_to_dim:n}
%   \begin{syntax}
%     \cs{fp_to_dim:N} \meta{fp~var}
%     \cs{fp_to_dim:n} \Arg{floating point expression}
%   \end{syntax}
%   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.
% \end{function}
%
% \begin{function}[EXP, updated = 2012-07-08]
%   {\fp_to_int:N, \fp_to_int:c, \fp_to_int:n}
%   \begin{syntax}
%     \cs{fp_to_int:N} \meta{fp~var}
%     \cs{fp_to_int:n} \Arg{floating point expression}
%   \end{syntax}
%   Evaluates the \meta{floating point expression}, and rounds the
%   result to the closest integer, with ties rounded to an even integer.
%   The result may be outside the range $[- 2^{31} + 1, 2^{31} - 1]$ of
%   valid \TeX{} integers, triggering \TeX{} errors if used in an
%   integer expression.  The values $\pm\infty$ and \texttt{nan} trigger
%   an \enquote{invalid operation} exception.
% \end{function}
%
% \begin{function}[EXP, added = 2012-05-08, updated = 2012-07-08]
%   {\fp_to_scientific:N, \fp_to_scientific:c, \fp_to_scientific:n}
%   \begin{syntax}
%     \cs{fp_to_scientific:N} \meta{fp~var}
%     \cs{fp_to_scientific:n} \Arg{floating point expression}
%   \end{syntax}
%   Evaluates the \meta{floating point expression} and expresses the
%   result in scientific notation with $16$ significant figures:
%   \begin{quote}
%     \meta{optional \texttt{-}}\meta{digit}\texttt{.}\meta{15 digits}\texttt{e}\meta{optional sign}\meta{exponent}
%   \end{quote}
%   The leading \meta{digit} is non-zero except in the case of $\pm 0$.
%   The values $\pm\infty$ and \texttt{nan} trigger an \enquote{invalid
%     operation} exception.
% \end{function}
%
% \begin{function}[EXP, updated = 2012-07-08]
%   {\fp_to_tl:N, \fp_to_tl:c, \fp_to_tl:n}
%   \begin{syntax}
%     \cs{fp_to_tl:N} \meta{fp~var}
%     \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
%   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.
% \end{function}
%
% \begin{function}[EXP, updated = 2012-07-08]{\fp_use:N, \fp_use:c}
%   \begin{syntax}
%     \cs{fp_use:N} \meta{fp~var}
%   \end{syntax}
%   Inserts the value of the \meta{fp~var} into the input stream as a
%   decimal number with $16$ significant figures and no exponent.
%   Leading or trailing zeros may be inserted to compensate for the
%   exponent.  Non-significant trailing zeros are trimmed.  Integers are
%   expressed without a decimal separator.  The values $\pm\infty$ and
%   \texttt{nan} trigger an \enquote{invalid operation} exception.  This
%   function is identical to \cs{fp_to_decimal:N}.
% \end{function}
%
% \section{Floating point conditionals}
%
% \begin{function}[EXP, pTF, updated = 2012-05-08]
%   {\fp_if_exist:N, \fp_if_exist:c}
%   \begin{syntax}
%     \cs{fp_if_exist_p:N} \meta{fp~var}
%     \cs{fp_if_exist:NTF} \meta{fp~var} \Arg{true code} \Arg{false code}
%   \end{syntax}
%   Tests whether the \meta{fp~var} is currently defined.  This does not
%   check that the \meta{fp~var} really is a floating point variable.
% \end{function}
%
% \begin{function}[EXP, pTF, updated = 2012-05-08]
%   {\fp_compare:nNn, \fp_compare:n}
%   \begin{syntax}
%     \cs{fp_compare_p:nNn} \Arg{fpexpr_1} \meta{relation} \Arg{fpexpr_2}
%     \cs{fp_compare:nNnTF} \Arg{fpexpr_1} \meta{relation} \Arg{fpexpr_2} \Arg{true code} \Arg{false code}
%     \cs{fp_compare_p:n} \{ \meta{fpexpr_1} \meta{relation} \meta{fpexpr_2} \}
%     \cs{fp_compare:nTF} \{ \meta{fpexpr_1} \meta{relation} \meta{fpexpr_2} \} \Arg{true code} \Arg{false code}
%   \end{syntax}
%   Compares the \meta{fpexpr_1} and the \meta{fpexpr_2}, and returns
%   \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 one of the operands is \texttt{nan}, and
%   this relations is denoted by the symbol |?|.  The \texttt{nNn}
%   functions support the \meta{relations} |<|, |=|, |>|, and |?|.  The
%   \texttt{n} functions support as a \meta{relation} any combination of
%   those four symbols, plus an optional leading |!| (which negates the
%   \meta{relation}), with the restriction that the \meta{relation} may
%   not start with |?|.  Common choices of \meta{relation} include |>=|
%   (greater or equal), |!=| (not equal), |!?| (comparable).  Note that
%   a \texttt{nan} is distinct from any value, even another
%   \texttt{nan}, hence $x=x$ is not true for a \texttt{nan}. Thus to
%   test if a value is \texttt{nan}, use
%   \begin{verbatim}
%     \fp_compare:nNnTF { <value> } != { <value> }
%       { } % <value> is nan
%       { } % <value> is not nan
%   \end{verbatim}
% \end{function}
%
% \section{Some useful constants, and scratch variables}
%
% \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_inf_fp, \c_minus_inf_fp}
%   Infinity, with either sign.  These can be input directly in a
%   floating point expression as \texttt{inf} and \texttt{-inf}.
% \end{variable}
%
% \begin{variable}[updated = 2012-05-08]{\c_e_fp}
%   The value of the base of the natural logarithm, $\mathrm{e} = \exp(1)$.
% \end{variable}
%
% \begin{variable}[updated = 2012-05-08]{\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$.
% \end{variable}
%
% \begin{variable}[added = 2012-05-08]{\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 by \texttt{deg}.
% \end{variable}
%
% \begin{variable}{\l_tmpa_fp, \l_tmpb_fp}
%   Scratch floating points for local assignment. These are never used by
%   the kernel code, and so are safe for use with any \LaTeX3-defined
%   function. However, they may be overwritten by other non-kernel
%   code and so should only be used for short-term storage.
% \end{variable}
%
% \begin{variable}{\g_tmpa_fp, \g_tmpb_fp}
%   Scratch floating points for global assignment. These are never used by
%   the kernel code, and so are safe for use with any \LaTeX3-defined
%   function. However, they may be overwritten by other non-kernel
%   code and so should only be used for short-term storage.
% \end{variable}
%
% \section{Floating point exceptions}
% \label{sec:fp-exceptions}
%^^A todo: redoc
%
% \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.
% \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
%   results in $\pm \infty$.
% \item \emph{Underflow} occurs whenever the result of an operation is
%   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 results in a \nan{}.
% \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.
% \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
% 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{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.
% \end{function}
%
% \begin{function}[added = 2012-05-28]{\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.
% \end{function}
%
% \begin{function}[EXP, added = 2012-05-28]{\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.
% \end{function}
%
% \begin{function}[added = 2012-05-28]{\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
%   \begin{itemize}
%     \item \texttt{none}: the \meta{exception} will be entirely
%       ignored, and leave no trace;
%     \item \texttt{flag}: the \meta{exception} will turn the
%       corresponding flag on when it occurs;
%     \item \texttt{error}: additionally, the \meta{exception} will halt
%       the \TeX{} run and display some information about the current
%       operation in the terminal.
%   \end{itemize}
% \end{function}
%
% \section{Floating point expressions}
%
% \begin{function}[added = 2012-05-08, updated = 2012-05-27]
%   {\fp_show:N, \fp_show:c, \fp_show:n}
%   \begin{syntax}
%     \cs{fp_show:N} \meta{fp~var}
%     \cs{fp_show:n} \Arg{floating point expression}
%   \end{syntax}
%   Evaluates the \meta{floating point expression} and displays the
%   result in the terminal.
% \end{function}
%
% \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
%
% We support four types of floating point numbers:
% \begin{itemize}
%   \item $\pm 0.d_1d_2\ldots{}d_{16} \cdot 10^{n}$, a normal floating
%     point number, with $d_i\in [0,9]$, $d_1\neq 0$, and $\lvert n\rvert
%     \leq \ExplSyntaxOn \int_use:N \c__fp_max_exponent_int$;
%   \item $\pm 0$, zero, with a given sign;
%   \item $\pm \infty$, infinity, with a given sign;
%   \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}
%     \cdot 10^{-\ExplSyntaxOn\int_use:N \c__fp_max_exponent_int}$ with
%     $d_1=0$.
% \end{itemize}
% Normal floating point numbers are stored in base $10$, with $16$
% significant figures.
%
% On input, a normal floating point number consists of:
% \begin{itemize}
%   \item \meta{sign}: a possibly empty string of |+| and |-| characters;
%   \item \meta{mantissa}: a non-empty string of digits together with zero
%     or one dot;
%   \item \meta{exponent} optionally: the character |e|, followed by a
%     possibly empty string of |+|~and~|-| tokens, and a non-empty string
%     of digits.
% \end{itemize}
% The sign of the resulting number is |+| if \meta{sign} contains an
% even number of |-|, and |-| otherwise, hence, an empty \meta{sign}
% denotes a non-negative input.  The stored mantissa is obtained from
% \meta{mantissa} by omitting the decimal separator and leading zeros,
% and rounding to $16$ significant digits, filling with trailing zeros
% if necessary.  In particular, the value stored is exact if the input
% \meta{mantissa} has at most $16$ digits.  The stored \meta{exponent}
% is obtained by combining the input \meta{exponent} ($0$ if absent)
% with a shift depending on the position of the mantissa and the number
% of leading zeros.
%
% A special case arises if the resulting \meta{exponent} is either
% too large or too small to be represented. This results either in an
% overflow (the number is then replaced by $\pm\infty$), or an
% underflow (resulting in $\pm 0$).
%
% The result is thus $\pm 0$ if and only if \meta{mantissa} contains no
% non-zero digit (\emph{i.e.}, consists only in~|0| characters, and an
% optional |.| character), or 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 the case.
%
% Special numbers are input as follows:
% \begin{itemize}
%   \item \texttt{inf} represents $+\infty$, and can be preceded by any
%     \meta{sign}.
%   \item \texttt{nan} represents a (quiet) non-number. It can be preceded
%     by any sign, but that will be ignored.
%   \item Any unrecognisable string will yield a signalling \texttt{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: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.
% \begin{itemize}
%   \item Implicit multiplication by juxtaposition (\texttt{2pi}, \emph{etc}).
%   \item Function calls (\texttt{sin}, \texttt{ln}, \emph{etc}).
%   \item Binary |**| and |^| (right associative).
%   \item Unary |+|, |-|, |!|.
%   \item Binary |*|, |/| and |%|.
%   \item Binary |+| and |-|.
%   \item Comparisons |>=|, |!=|, |<?|, \emph{etc}.
%   \item Logical \texttt{and}, denoted by |&&|.
%   \item Logical \texttt{or}, denoted by \verb*+||+.
%   \item Ternary operator |?:| (right associative).
% \end{itemize}
% The precedence of operations can be overridden using parentheses.
% In particular, those precedences imply that
% \begin{align*}
%   \mathtt{sin 2pi} & = \sin(2\pi) = 0, \\
%   \mathtt{2\char`\^2max(3,4)} & = 2^{2 \max(3,4)} = 256.
% \end{align*}
% Functions are called on the value of their argument, contrarily to
% \TeX{} macros.
%
% \subsection{Operations} \label{sec:fp-operations}
%
% 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.
%
% The exceptions listed below are mostly not implemented yet. ^^A todo:
%
% \begin{function}{?:}
%   \begin{syntax}
%     \cs{fp_eval:n} \{ \meta{operand_1} |?| \meta{operand_2} |:| \meta{operand_3} \}
%   \end{syntax}
%   The ternary operator |?:| results in \meta{operand_2} if
%   \meta{operand_1} is true, and \meta{operand_3} if it is false (equal to
%   $\pm 0$).  All three \meta{operands} are evaluated in all cases.  The
%   operator is right associative, hence
%   \begin{verbatim}
%     \fp_eval:n
%       {
%         1 + 3 > 4 ? 1 :
%         2 + 4 > 5 ? 2 :
%         3 + 5 > 6 ? 3 : 4
%       }
%   \end{verbatim}
%   first tests whether $1 + 3 > 4$; since this isn't true, the branch
%   following |:| is taken, and $2 + 4 > 5$ is compared; since this is
%   true, the branch before |:| is taken, and everything else is
%   (evaluated then) ignored.  That allows testing for various cases in
%   a concise manner, with the drawback that all computations are made
%   in all cases.
% \end{function}
%
% \begingroup \catcode`\|=12
% \begin{function}{TWO BARS} ^^A To fix
%   \begin{syntax}
%     \cs{fp_eval:n} \{ \meta{operand_1} \texttt{||} \meta{operand_2} \}
%   \end{syntax}
%   If \meta{operand_1} is true (non-zero), use that value, otherwise the
%   value of \meta{operand_2}.  Both \meta{operands} are evaluated in all
%   cases.
% \end{function}
% \endgroup
%
% \begingroup \catcode`\&=12
% \begin{function}{&&}
%   \begin{syntax}
%     \cs{fp_eval:n} \{ \meta{operand_1} \texttt{&&} \meta{operand_2} \}
%   \end{syntax}
%   If \meta{operand_1} is false (equal to $\pm 0$), use that value,
%   otherwise the value of \meta{operand_2}.  Both \meta{operands} are
%   evaluated in all cases.
% \end{function}
% \endgroup
%
% \begin{function}{\<, =, >, ?}
%   \begin{syntax}
%     \cs{fp_eval:n} \{ \meta{operand_1} \meta{comparison} \meta{operand_2} \}
%   \end{syntax}
%   The \meta{comparison} consists of a non-empty string of |<|, |=|,
%   |>|, and |?|, optionally preceeded by |!|.  It may not start with
%   |?|.  This evaluates to $+1$ if the \meta{comparison} between the
%   \meta{operand_1} and \meta{operand_2} is true, and $+0$ otherwise.
% \end{function}
%
% \begin{function}{+, -}
%   \begin{syntax}
%     \cs{fp_eval:n} \{ \meta{operand_1} |+| \meta{operand_2} \}
%     \cs{fp_eval:n} \{ \meta{operand_1} |-| \meta{operand_2} \}
%   \end{syntax}
%   Computes the sum or the difference of its two \meta{operands}.  The
%   \enquote{invalid operation} exception occurs for $\infty-\infty$.
%   \enquote{Inexact}, \enquote{underflow} and \enquote{overflow} occur
%   when appropriate.
% \end{function}
%
% \begin{function}{*, /}
%   \begin{syntax}
%     \cs{fp_eval:n} \{ \meta{operand_1} |*| \meta{operand_2} \}
%     \cs{fp_eval:n} \{ \meta{operand_1} |/| \meta{operand_2} \}
%   \end{syntax}
%   Computes the product or the ratio of its two \meta{operands}.  The
%   \enquote{invalid operation} exception occurs for $\infty/\infty$,
%   $0/0$, or $0*\infty$.  \enquote{Division by zero} occurs when
%   dividing a finite non-zero number by $\pm 0$.  The
%   \enquote{inexact}, \enquote{underflow} and \enquote{overflow}
%   exceptions occur when appropriate.
% \end{function}
%
% \begin{function}{+, -, !}
%   \begin{syntax}
%     \cs{fp_eval:n} \{ |+| \meta{operand} \}
%     \cs{fp_eval:n} \{ |-| \meta{operand} \}
%     \cs{fp_eval:n} \{ |!| \meta{operand} \}
%   \end{syntax}
%   The unary |+| does nothing, the unary |-| changes the sign of the
%   \meta{operand}, and |!| \meta{operand} evaluates to $1$ if
%   \meta{operand} is false and $0$ otherwise (this is the \texttt{not}
%   boolean function).
% \end{function}
%
% \begingroup\catcode`\^=12
% \begin{function}{**, ^}
%   \begin{syntax}
%     \cs{fp_eval:n} \{ \meta{operand_1} |**| \meta{operand_2} \}
%     \cs{fp_eval:n} \{ \meta{operand_1} |^| \meta{operand_2} \}
%   \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
%   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
%   appropriate.
% \end{function}
% \endgroup
%
% \begin{function}{abs}
%   \begin{syntax}
%     \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.
% \end{function}
%
% \begin{function}{exp}
%   \begin{syntax}
%     \cs{fp_eval:n} \{ |exp(| \meta{fpexpr} |)| \}
%   \end{syntax}
%   Computes the exponential of the \meta{fpexpr}.  The
%   \enquote{inexact}, \enquote{underflow} and \enquote{overflow}
%   exceptions occur when appropriate.
% \end{function}
%
% \begin{function}{ln}
%   \begin{syntax}
%     \cs{fp_eval:n} \{ |ln(| \meta{fpexpr} |)| \}
%   \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}
%   exceptions occur when appropriate.
% \end{function}
%
% \begin{function}{max, min}
%   \begin{syntax}
%     \cs{fp_eval:n} \{ |max(| \meta{fpexpr_1} |,| \meta{fpexpr_2} |,| \ldots{} |)| \}
%     \cs{fp_eval:n} \{ |min(| \meta{fpexpr_1} |,| \meta{fpexpr_2} |,| \ldots{} |)| \}
%   \end{syntax}
%   Evalutes each \meta{fpexpr} and computes the largest (smallest) of
%   those.  If any of the \meta{fpexpr} is a \nan{}, the result is
%   \nan{}.
% \end{function}
%
% \begin{function}{round, round0, round+, round-}
%   \begin{syntax}
%     \cs{fp_eval:n} \{ |round| \meta{option} |(| \meta{fpexpr} |)| \}
%     \cs{fp_eval:n} \{ |round| \meta{option} |(| \meta{fpexpr_1} , \meta{fpexpr_2} |)| \}
%   \end{syntax}
%   Rounds \meta{fpexpr_1} to \meta{fpexpr_2} places (this must be an
%   integer).  When \meta{fpexpr_2} is missing, it is assumed to be $0$,
%   \emph{i.e.}, \meta{fpexpr_1} is rounded to an integer.  The
%   \meta{option} controls the rounding direction:
%   \begin{itemize}
%     \item by default, the function rounds to the closest allowed number
%       (rounding ties to even);
%     \item with |0|, the function rounds towards $0$, \emph{i.e.}, truncates;
%     \item with |+|, the function rounds towards $+\infty$;
%     \item with |-|, the function rounds towards $-\infty$.
%   \end{itemize}
% \end{function}
%
% \begin{function}{sin, cos, tan, cot}
%   \begin{syntax}
%     \cs{fp_eval:n} \{ |sin(| \meta{fpexpr} |)| \}
%     \cs{fp_eval:n} \{ |cos(| \meta{fpexpr} |)| \}
%     \cs{fp_eval:n} \{ |tan(| \meta{fpexpr} |)| \}
%     \cs{fp_eval:n} \{ |cot(| \meta{fpexpr} |)| \}
%   \end{syntax}
%   Computes the sine, cosine, tangent or cotangent of the
%   \meta{fpexpr}.  The trigonometric functions are undefined for an
%   argument of $\pm\infty$, leading to the \enquote{invalid operation}
%   exception.  Additionally, evaluating tangent or cotangent at one of
%   their poles leads to a \enquote{division by zero} exception.  Other
%   exceptions occur when appropriate.
% \end{function}
%
% \begin{variable}{inf, nan}
%   The special values $+\infty$, $-\infty$, and \nan{} are represented
%   as \texttt{inf}, \texttt{-inf} and \texttt{nan} (see \cs{c_inf_fp},
%   \cs{c_minus_inf_fp} and \cs{c_nan_fp}).
% \end{variable}
%
% \begin{variable}{pi}
%   The value of $\pi$ (see \cs{c_pi_fp}).
% \end{variable}
%
% \begin{variable}{deg}
%   The value of $1^{\circ}$ in radians (see \cs{c_one_degree_fp}).
% \end{variable}
%
% \begin{variable}{em, ex, in, pt, pc, cm, mm, dd, cc, nd, nc, bp, sp}
%   \newcommand{\unit}[1]{\text{\texttt{#1}}}
%   Those units of measurement are equal to their values in \texttt{pt},
%   namely
%   \begin{align*}
%     1 \unit{in} & = 72.27 \unit{pt} \\
%     1 \unit{pt} & = 1 \unit{pt} \\
%     1 \unit{pc} & = 12 \unit{pt} \\
%     1 \unit{cm} & = \frac{1}{2.54} \unit{in} = 28.45275590551181 \unit{pt} \\
%     1 \unit{mm} & = \frac{1}{25.4} \unit{in} = 2.845275590551181 \unit{pt} \\
%     1 \unit{dd} & = 0.376065 \unit{mm} = 1.07000856496063 \unit{pt} \\
%     1 \unit{cc} & = 12 \unit{dd} = 12.84010277952756 \unit{pt} \\
%     1 \unit{nd} & = 0.375 \unit{mm} = 1.066978346456693 \unit{pt} \\
%     1 \unit{nc} & = 12 \unit{nd} = 12.80374015748031 \unit{pt} \\
%     1 \unit{bp} & = \frac{1}{72} \unit{in} = 1.00375 \unit{pt} \\
%     1 \unit{sp} & = 2^{-16} \unit{pt} = 1.52587890625e-5 \unit{pt}.
%   \end{align*}
%   The values of the (font-dependent) units \texttt{em} and \texttt{ex}
%   are gathered from \TeX{} when the surrounding floating point
%   expression is evaluated.
% \end{variable}
%
% \begin{variable}{true, false}
%   Other names for $1$ and $+0$.
% \end{variable}
%
% \begin{function}[EXP, added = 2012-05-08]{\dim_to_fp:n}
%   \begin{syntax}
%     \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}.
% \end{function}
%
% \begin{function}[EXP, added = 2012-05-14, updated = 2012-07-08]{\fp_abs:n}
%   \begin{syntax}
%     \cs{fp_abs:n} \Arg{floating point expression}
%   \end{syntax}
%   Evaluates the \meta{floating point expression} as described for
%   \cs{fp_eval:n} and leaves the absolute value of the result in
%   the input stream.
% \end{function}
%
% ^^A todo
% ^^A \section{Rounding}
% ^^A
% ^^A This explains how to go from a floating point number to a
% ^^A rounded value for various applications. Perhaps worth coding
% ^^A functionalities up to what siunitx can do on this matter.
%
% ^^A todo
% ^^A \section{Floating points}
% ^^A
% ^^A Here, there may be a discussion of what floating point numbers
% ^^A are, and a list of relevant resources (\emph{e.g.}, some of
% ^^A Kahan's articles), and previous \TeX{} packages.
%
% \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 following need to be done. I'll try to time-order the items.
% \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.
%   \item Modulo and remainder, and rounding functions |quantize|,
%     |quantize0|, |quantize+|, |quantize-|, |quantize=|, |round=|.
%     Should the modulo also be provided as (catcode 12) |%|?
%   \item \cs{fp_format:nn} \Arg{fpexpr} \Arg{format}, but what should
%     \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 $\atan(x,y) = \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 Hyperbolic functions \texttt{cosh}, \texttt{sinh}, \texttt{tanh}.
%   \item Inverse hyperbolics.
%   \item Base conversion, input such as \texttt{0xAB.CDEF}.
%   \item Random numbers (pgfmath provides |rnd|, |rand|, |random|), with
%     seed reset at every \cs{fp_set:Nn}.
%   \item Factorial (not with |!|), gamma function.
%   \item Improve coefficients of \texttt{sin}, \texttt{cos} and
%     \texttt{tan}.
%   \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}?
% \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 When rounding towards $-\infty$, |\dim_to_fp:n {0pt}| should
%     return $-0$, not $+0$.
%   \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.
% \end{itemize}
%
% \end{documentation}
%
% \begin{implementation}
%
% \section{\pkg{l3fp} implementation}
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
%    \begin{macrocode}
\ProvidesExplPackage
  {\ExplFileName}{\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription}
\__expl_package_check:
%    \end{macrocode}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex