% \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> \documentclass[full]{l3doc} \usepackage{amsmath} \providecommand\nan{\texttt{NaN}} \begin{document} \DocInput{\jobname.dtx} \end{document} % % \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$ \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: % $xy$, 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 { } != { } % { } % is nan % { } % 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 |>=|, |!=|, | 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} % % \end{macrocode} % % \end{implementation} % % \PrintIndex