[latex3-commits] [git/LaTeX3-latex3-latex3] master: Document floating point tuples and supported operations (see #438) (a0b9bf7)
Bruno Le Floch
bruno at le-floch.fr
Sun Feb 25 21:44:25 CET 2018
Repository : https://github.com/latex3/latex3
On branch : master
Link : https://github.com/latex3/latex3/commit/a0b9bf7de373a1c87dd466e046e6c3aad87f6548
>---------------------------------------------------------------
commit a0b9bf7de373a1c87dd466e046e6c3aad87f6548
Author: Bruno Le Floch <bruno at le-floch.fr>
Date: Sun Feb 25 15:44:25 2018 -0500
Document floating point tuples and supported operations (see #438)
>---------------------------------------------------------------
a0b9bf7de373a1c87dd466e046e6c3aad87f6548
l3kernel/l3fp.dtx | 183 +++++++++++++++++++++++++++++++++---------------
l3packages/xfp/xfp.dtx | 8 ++-
2 files changed, 130 insertions(+), 61 deletions(-)
diff --git a/l3kernel/l3fp.dtx b/l3kernel/l3fp.dtx
index 1558b86..28bb8ff 100644
--- a/l3kernel/l3fp.dtx
+++ b/l3kernel/l3fp.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-%% File: l3fp.dtx Copyright (C) 2011-2017 The LaTeX3 Project
+%% File: l3fp.dtx Copyright (C) 2011-2018 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
@@ -107,13 +107,17 @@
% \item Dimensions, automatically expressed in points, \emph{e.g.},
% \texttt{pc} is~$12$.
% \item Automatic conversion (no need for \cs[no-index]{\meta{type}_use:N}) of
-% integer, dimension, and skip variables to floating points,
+% integer, dimension, and skip variables to floating point numbers,
% expressing dimensions in points and ignoring the stretch and
% shrink components of skips.
+% \item Tuples: $(x_1,\ldots{},x_n)$ that can be stored in variables,
+% added together, multiplied or divided by a floating point number,
+% and nested.
% \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
+% which is automatically replaced by its current value.
+% A \enquote{floating point} is a floating point number or a tuple thereof. See
% section~\ref{sec:l3fp:fp-floats} for a description of what a floating point is,
% section~\ref{sec:l3fp:fp-precedence} for details about how an expression is
% parsed, and section~\ref{sec:l3fp:fp-operations} to know what the various
@@ -123,7 +127,7 @@
% 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} $.
+% = \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
@@ -210,6 +214,8 @@
% \end{syntax}
% Adds the result of computing the \meta{floating point expression} to
% the \meta{fp~var}.
+% This also applies if \meta{fp~var} and \meta{floating point
+% expression} evaluate to tuples of the same size.
% \end{function}
%
% \begin{function}[updated = 2012-05-08, tested = m3fp002]
@@ -219,9 +225,11 @@
% \end{syntax}
% Subtracts the result of computing the \meta{floating point
% expression} from the \meta{fp~var}.
+% This also applies if \meta{fp~var} and \meta{floating point
+% expression} evaluate to tuples of the same size.
% \end{function}
%
-% \section{Using floating point numbers}
+% \section{Using floating points}
%
% \begin{function}[EXP, added = 2012-05-08, updated = 2012-07-08,
% tested = m3fp-convert003]{\fp_eval:n}
@@ -234,7 +242,11 @@
% for the exponent. Non-significant trailing zeros are trimmed, and
% integers are expressed without a decimal separator. The values
% $\pm\infty$ and \nan{} trigger an \enquote{invalid operation}
-% exception. This function is identical to \cs{fp_to_decimal:n}.
+% exception.
+% For a tuple, each item is converted using \cs{fp_eval:n} and they are combined as
+% |(|\meta{fp_1}\verb*|, |\meta{fp_2}\verb*|, |\ldots{}\meta{fp_n}|)|
+% if $n>1$ and |(|\meta{fp_1}|,)| or |()| for fewer items.
+% This function is identical to \cs{fp_to_decimal:n}.
% \end{function}
%
% \begin{function}[EXP, added = 2012-05-08, updated = 2012-07-08]
@@ -250,6 +262,9 @@
% integers are expressed without a decimal separator. The values
% $\pm\infty$ and~\nan{} trigger an \enquote{invalid operation}
% exception.
+% For a tuple, each item is converted using \cs{fp_to_decimal:n} and they are combined as
+% |(|\meta{fp_1}\verb*|, |\meta{fp_2}\verb*|, |\ldots{}\meta{fp_n}|)|
+% if $n>1$ and |(|\meta{fp_1}|,)| or |()| for fewer items.
% \end{function}
%
% \begin{function}[EXP, updated = 2016-03-22]
@@ -265,8 +280,8 @@
% In particular, the result may
% be outside the range $[- 2^{14} + 2^{-17}, 2^{14} - 2^{-17}]$ of
% valid \TeX{} dimensions, leading to overflow errors if used as a
-% dimension. The values $\pm\infty$ and~\nan{} trigger an
-% \enquote{invalid operation} exception.
+% dimension. Tuples, as well as the values $\pm\infty$ and~\nan{},
+% trigger an \enquote{invalid operation} exception.
% \end{function}
%
% \begin{function}[EXP, updated = 2012-07-08]
@@ -280,8 +295,8 @@
% integer.
% The result may be outside the range $[- 2^{31} + 1, 2^{31} - 1]$ of
% valid \TeX{}~integers, leading to overflow errors if used in an
-% integer expression. The values $\pm\infty$ and~\nan{} trigger
-% an \enquote{invalid operation} exception.
+% integer expression. Tuples, as well as the values $\pm\infty$
+% and~\nan{}, trigger an \enquote{invalid operation} exception.
% \end{function}
%
% \begin{function}[EXP, added = 2012-05-08, updated = 2016-03-22]
@@ -299,6 +314,9 @@
% The values $\pm\infty$ and~\nan{} trigger an \enquote{invalid
% operation} exception. Normal category codes apply: thus the |e| is
% category code~$11$ (a letter).
+% For a tuple, each item is converted using \cs{fp_to_scientific:n} and they are combined as
+% |(|\meta{fp_1}\verb*|, |\meta{fp_2}\verb*|, |\ldots{}\meta{fp_n}|)|
+% if $n>1$ and |(|\meta{fp_1}|,)| or |()| for fewer items.
% \end{function}
%
% \begin{function}[EXP, updated = 2016-03-22]
@@ -320,6 +338,9 @@
% |0|, |-0|, \texttt{inf}, \texttt{-inf}, and~\texttt{nan}
% respectively. Normal category codes apply and thus \texttt{inf} or
% \texttt{nan}, if produced, are made up of letters.
+% For a tuple, each item is converted using \cs{fp_to_tl:n} and they are combined as
+% |(|\meta{fp_1}\verb*|, |\meta{fp_2}\verb*|, |\ldots{}\meta{fp_n}|)|
+% if $n>1$ and |(|\meta{fp_1}|,)| or |()| for fewer items.
% \end{function}
%
% \begin{function}[EXP, updated = 2012-07-08]
@@ -332,8 +353,11 @@
% 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~\nan{} trigger an \enquote{invalid operation} exception. This
-% function is identical to \cs{fp_to_decimal:N}.
+% and~\nan{} trigger an \enquote{invalid operation} exception.
+% For a tuple, each item is converted using \cs{fp_to_decimal:n} and they are combined as
+% |(|\meta{fp_1}\verb*|, |\meta{fp_2}\verb*|, |\ldots{}\meta{fp_n}|)|
+% if $n>1$ and |(|\meta{fp_1}|,)| or |()| for fewer items.
+% This function is identical to \cs{fp_to_decimal:N}.
% \end{function}
%
% \section{Floating point conditionals}
@@ -355,11 +379,11 @@
% \cs{fp_compare:nNnTF} \Arg{fpexpr_1} \meta{relation} \Arg{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 or both operands is~\nan{}, and this relation
-% is denoted by the symbol~|?|. Note that a~\nan{} is distinct from
+% \texttt{true} if the \meta{relation} is obeyed. Two floating points
+% $x$ and~$y$ may obey four mutually exclusive relations:
+% $x<y$, $x=y$, $x>y$, or $x?y$ (\enquote{not ordered}). The last
+% case occurs exactly if one or both operands is~\nan{} or is a tuple,
+% unless they are equal tuples. 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
% number with the \enquote{not ordered} relation.
@@ -368,6 +392,10 @@
% { } % <value> is nan
% { } % <value> is not nan
% \end{verbatim}
+% Tuples are equal if they have the same number of items and items
+% compare equal (in particular there must be no~\nan{}).
+% At present any other comparison with tuples yields |?| (not ordered).
+% This is experimental.
% \end{function}
%
% \begin{function}[EXP, pTF, updated = 2012-12-14,
@@ -400,10 +428,10 @@
% expression} is evaluated only once. Contrarily to
% \cs{int_compare:nTF}, all \meta{floating point expressions} are
% 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 or both operands is~\nan{}, and
-% this relation is denoted by the symbol~|?|. Each \meta{relation}
+% points $x$ and~$y$ may obey four mutually exclusive
+% relations: $x<y$, $x=y$, $x>y$, or $x?y$ (\enquote{not ordered}).
+% The last case occurs exactly if one or both operands is~\nan{} or is
+% a tuple, unless they are equal tuples. Each \meta{relation}
% can be any (non-empty) combination of |<|, |=|, |>|, and~|?|, plus
% an optional leading~|!| (which negates the \meta{relation}), with
% the restriction that the \meta{relation} may not start with~|?|, as
@@ -530,7 +558,8 @@
% \cs{fp_step_function:nnnN} \Arg{initial value} \Arg{step} \Arg{final value} \meta{function}
% \end{syntax}
% This function first evaluates the \meta{initial value}, \meta{step}
-% and \meta{final value}, all of which should be floating point expressions.
+% and \meta{final value}, each of which should be a floating point
+% expression evaluating to a floating point number, not a tuple.
% The \meta{function} is then placed in front of each \meta{value}
% from the \meta{initial value} to the \meta{final value} in turn
% (using \meta{step} between each \meta{value}). The \meta{step} must
@@ -565,7 +594,8 @@
% \cs{fp_step_inline:nnnn} \Arg{initial value} \Arg{step} \Arg{final value} \Arg{code}
% \end{syntax}
% This function first evaluates the \meta{initial value}, \meta{step}
-% and \meta{final value}, all of which should be floating point expressions.
+% and \meta{final value}, all of which should be floating point
+% expressions evaluating to a floating point number, not a tuple.
% Then for each \meta{value} from the \meta{initial value} to the
% \meta{final value} in turn (using \meta{step} between each
% \meta{value}), the \meta{code} is inserted into the input stream
@@ -579,7 +609,8 @@
% ~~\Arg{initial value} \Arg{step} \Arg{final value} \meta{tl~var} \Arg{code}
% \end{syntax}
% This function first evaluates the \meta{initial value}, \meta{step}
-% and \meta{final value}, all of which should be floating point expressions.
+% and \meta{final value}, all of which should be floating point
+% expressions evaluating to a floating point number, not a tuple.
% Then for each \meta{value} from the \meta{initial value} to the
% \meta{final value} in turn (using \meta{step} between each
% \meta{value}), the \meta{code} is inserted into the input stream,
@@ -811,12 +842,13 @@
% \item Logical \texttt{and}, denoted by |&&|.
% \item Logical \texttt{or}, denoted by \verb+||+.
% \item Ternary operator |?:| (right associative).
+% \item Comma (to build tuples).
% \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.
+% \mathtt{sin 2pi} & = \sin(2)\pi != 0, \\
+% \mathtt{2\char`\^2max(3,5)} & = 2^2 \max(3,5) = 20.
% \end{align*}
% Functions are called on the value of their argument, contrarily to
% \TeX{} macros.
@@ -826,16 +858,21 @@
% We now present the various operations allowed in floating point
% expressions, from the lowest precedence to the highest. When used as
% a truth value, a floating point expression is \texttt{false} if it is
-% $\pm 0$, and \texttt{true} otherwise, including when it is \nan{}.
+% $\pm 0$, and \texttt{true} otherwise, including when it is \nan{} or a
+% tuple such as $(0,0)$. Tuples are only supported to some extent by
+% operations that work with truth values (|?:|, \verb"||", |&&|, |!|),
+% by comparisons (|!<=>?|), and by |+|, |-|, |*|, |/|. Unless otherwise
+% specified, providing a tuple as an argument of any other operation
+% yields the \enquote{invalid operation} exception and a \nan{} result.
%
% \begin{function}[tested = m3fp-logic002, module = ]{?:}
% \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
+% \meta{operand_1} is true (not $\pm 0$), and \meta{operand_3} if \meta{operand_1}
+% is false ($\pm 0$). All three \meta{operands} are evaluated in all
+% cases; they may be tuples. The operator is right associative, hence
% \begin{verbatim}
% \fp_eval:n
% {
@@ -856,9 +893,12 @@
% \begin{syntax}
% \cs{fp_eval:n} \{ \meta{operand_1} \verb"||" \meta{operand_2} \}
% \end{syntax}
-% If \meta{operand_1} is true (non-zero), use that value, otherwise the
+% If \meta{operand_1} is true (not $\pm 0$), use that value, otherwise the
% value of \meta{operand_2}. Both \meta{operands} are evaluated in all
-% cases.
+% cases; they may be tuples. In \meta{operand_1} \verb"||"
+% \meta{operand_2} \verb"||" \ldots{} \verb"||" \meta{operands_n}, the
+% first true (nonzero) \meta{operand} is used and if all are zero the
+% last one ($\pm 0$) is used.
% \end{function}
%
% \begin{function}[tested = m3fp-logic002]{&&}
@@ -867,7 +907,10 @@
% \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.
+% evaluated in all cases; they may be tuples. In \meta{operand_1}
+% |&&| \meta{operand_2} |&&| \ldots{} |&&| \meta{operands_n}, the
+% first false ($\pm 0$) \meta{operand} is used and if none is zero the
+% last one is used.
% \end{function}
%
% \begin{function}[tested = m3fp-logic001, updated = 2013-12-14]
@@ -885,7 +928,7 @@
% |>|, and~|?|, optionally preceded by~|!|, and may not start
% with~|?|. This evaluates to $+1$ if all comparisons
% \meta{operand_i} \meta{relation_i} \meta{operand_{i+1}} are true, and
-% $+0$ otherwise. All \meta{operands} are evaluated in all cases.
+% $+0$ otherwise. All \meta{operands} are evaluated (once) in all cases.
% See \cs{fp_compare:nTF} for details.
% \end{function}
%
@@ -897,6 +940,9 @@
% Computes the sum or the difference of its two \meta{operands}. The
% \enquote{invalid operation} exception occurs for $\infty-\infty$.
% \enquote{Underflow} and \enquote{overflow} occur when appropriate.
+% These operations supports the itemwise addition or subtraction of
+% two tuples, but if they have a different number of items the
+% \enquote{invalid operation} exception occurs and the result is \nan{}.
% \end{function}
%
% \begin{function}[tested = {m3fp-basics002, m3fp-basics003}]{*, /}
@@ -909,6 +955,12 @@
% $0/0$, or $0*\infty$. \enquote{Division by zero} occurs when
% dividing a finite non-zero number by $\pm 0$. \enquote{Underflow}
% and \enquote{overflow} occur when appropriate.
+% When \meta{operand_1} is a tuple and \meta{operand_2} is a floating
+% point number, each item of \meta{operand_1} is multiplied or divided
+% by \meta{operand_2}. Multiplication also supports the case where
+% \meta{operand_1} is a floating point number and \meta{operand_2} a
+% tuple. Other combinations yield an \enquote{invalid operation}
+% exception and a \nan{} result.
% \end{function}
%
% \begin{function}[tested = m3fp-basics004, label = !]{+, -, !}
@@ -918,8 +970,9 @@
% \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}
+% \meta{operand} (for a tuple, of all its components), and
+% |!| \meta{operand} evaluates to $1$ if \meta{operand} is false
+% (is $\pm 0$) and $0$ otherwise (this is the \texttt{not}
% boolean function). Those operations never raise exceptions.
% \end{function}
%
@@ -939,15 +992,16 @@
% 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.
+% If either operand is a tuple, \enquote{invalid operation} occurs.
% \end{function}
%
% \begin{function}[tested = m3fp-basics004]{abs}
% \begin{syntax}
% \cs{fp_eval:n} \{ |abs(| \meta{fpexpr} |)| \}
% \end{syntax}
-% Computes the absolute value of the \meta{fpexpr}. This function
-% does not raise any exception beyond those raised when computing its
-% operand \meta{fpexpr}. See also \cs{fp_abs:n}.
+% Computes the absolute value of the \meta{fpexpr}. If the operand is
+% a tuple, \enquote{invalid operation} occurs. This operation does
+% not raise exceptions in other cases. See also \cs{fp_abs:n}.
% \end{function}
%
% \begin{function}[tested = m3fp-expo001]{exp}
@@ -956,6 +1010,7 @@
% \end{syntax}
% Computes the exponential of the \meta{fpexpr}. \enquote{Underflow}
% and \enquote{overflow} occur when appropriate.
+% If the operand is a tuple, \enquote{invalid operation} occurs.
% \end{function}
%
% \begin{function}[tested = m3fp-expo001]{ln}
@@ -964,10 +1019,11 @@
% \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, including for $\ln(-0)$.
-% \enquote{Division by zero} occurs when evaluating $\ln(+0) =
-% -\infty$. \enquote{Underflow} and \enquote{overflow} occur when
-% appropriate.
+% operation} is raised in that case, including for $\ln(-0)$.
+% \enquote{Division by zero} occurs when evaluating
+% $\ln(+0) = -\infty$. \enquote{Underflow} and \enquote{overflow}
+% occur when appropriate. If the operand is a tuple, \enquote{invalid
+% operation} occurs.
% \end{function}
%
% \begin{function}[tested = m3fp-logic002]{max, min}
@@ -976,8 +1032,9 @@
% \cs{fp_eval:n} \{ |min(| \meta{fpexpr_1} |,| \meta{fpexpr_2} |,| \ldots{} |)| \}
% \end{syntax}
% Evaluates each \meta{fpexpr} and computes the largest (smallest) of
-% those. If any of the \meta{fpexpr} is a \nan{}, the result is
-% \nan{}. Those operations do not raise exceptions.
+% those. If any of the \meta{fpexpr} is a \nan{} or tuple, the result
+% is \nan{}. If any operand is a tuple, \enquote{invalid operation}
+% occurs; these operations do not raise exceptions in other cases.
% \end{function}
%
% \begin{function}
@@ -1018,6 +1075,7 @@
% \end{itemize}
% \enquote{Overflow} occurs if $x$~is finite and the result is
% infinite (this can only happen if $\meta{fpexpr_2}\string<-9984$).
+% If any operand is a tuple, \enquote{invalid operation} occurs.
% \end{function}
%
% \begin{function}[tested = m3fp-logic002]{sign}
@@ -1026,8 +1084,9 @@
% \end{syntax}
% Evaluates the \meta{fpexpr} and determines its sign: $+1$ for
% positive numbers and for $+\infty$, $-1$ for negative numbers and
-% for $-\infty$, $\pm 0$ for $\pm 0$, and \nan{} for \nan{}. This
-% operation does not raise exceptions.
+% for $-\infty$, $\pm 0$ for $\pm 0$, and \nan{} for \nan{}.
+% If the operand is a tuple, \enquote{invalid operation} occurs.
+% This operation does not raise exceptions in other cases.
% \end{function}
%
% \begin{function}[updated = 2013-11-17, tested = m3fp-trig001]
@@ -1051,6 +1110,7 @@
% cotangent, cosecant, or secant at one of their poles leads to a
% \enquote{division by zero} exception. \enquote{Underflow} and
% \enquote{overflow} occur when appropriate.
+% If the operand is a tuple, \enquote{invalid operation} occurs.
% \end{function}
%
% \begin{function}[added = 2013-11-02, tested = m3fp-trig003]
@@ -1074,6 +1134,7 @@
% cotangent, cosecant, or secant at one of their poles leads to a
% \enquote{division by zero} exception. \enquote{Underflow} and
% \enquote{overflow} occur when appropriate.
+% If the operand is a tuple, \enquote{invalid operation} occurs.
% \end{function}
%
% \begin{function}[added = 2013-11-02, tested = m3fp-trig002]
@@ -1093,6 +1154,7 @@
% inside the range $(-1,1)$, an \enquote{invalid operation} exception
% is raised. \enquote{Underflow} and \enquote{overflow} occur when
% appropriate.
+% If the operand is a tuple, \enquote{invalid operation} occurs.
% \end{function}
%
% \begin{function}[added = 2013-11-02, tested = m3fp-trig004]
@@ -1112,6 +1174,7 @@
% inside the range $(-1,1)$, an \enquote{invalid operation} exception
% is raised. \enquote{Underflow} and \enquote{overflow} occur when
% appropriate.
+% If the operand is a tuple, \enquote{invalid operation} occurs.
% \end{function}
%
% \begin{function}[added = 2013-11-02, tested = m3fp-trig002]
@@ -1140,7 +1203,8 @@
% need not be defined for the two-argument arctangent: when both
% expressions yield~$\pm 0$, or when both yield~$\pm\infty$, the
% resulting angle is one of $\{\pm\pi/4,\pm 3\pi/4\}$ depending on
-% signs. Only the \enquote{underflow} exception can occur.
+% signs. The \enquote{underflow} exception can occur.
+% If any operand is a tuple, \enquote{invalid operation} occurs.
% \end{function}
%
% \begin{function}[added = 2013-11-02, tested = m3fp-trig004]
@@ -1168,8 +1232,9 @@
% The ratio $\meta{fpexpr_1}/\meta{fpexpr_2}$ need not be defined for
% the two-argument arctangent: when both expressions yield~$\pm 0$, or
% when both yield~$\pm\infty$, the resulting angle is one of $\{\pm
-% 45,\pm 135\}$ depending on signs. Only the \enquote{underflow}
+% 45,\pm 135\}$ depending on signs. The \enquote{underflow}
% exception can occur.
+% If any operand is a tuple, \enquote{invalid operation} occurs.
% \end{function}
%
% \begin{function}[added = 2013-12-14, tested = m3fp-basics005]{sqrt}
@@ -1177,7 +1242,7 @@
% \cs{fp_eval:n} \{ |sqrt(| \meta{fpexpr} |)| \}
% \end{syntax}
% Computes the square root of the \meta{fpexpr}. The \enquote{invalid
-% operation} is raised when the \meta{fpexpr} is negative; no other
+% operation} is raised when the \meta{fpexpr} is negative or is a tuple; no other
% exception can occur. Special values yield $\sqrt{-0} = -0$,
% $\sqrt{+0} = +0$, $\sqrt{+\infty} = +\infty$ and
% $\sqrt{\text{\nan{}}}=\text{\nan{}}$.
@@ -1272,9 +1337,9 @@
% \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. This function does not raise any exception beyond
-% those raised when evaluating its argument. Within floating point
-% expressions, |abs()| can be used.
+% input stream. If the argument is a tuple, \enquote{invalid
+% operation} occurs, but no other case raises exceptions. Within
+% floating point expressions, |abs()| can be used.
% \end{function}
%
% \begin{function}[EXP, added = 2012-09-26, tested = m3fp-convert003]
@@ -1283,10 +1348,11 @@
% \cs{fp_max:nn} \Arg{fp expression 1} \Arg{fp expression 2}
% \end{syntax}
% Evaluates the \meta{floating point expressions} as described for
-% \cs{fp_eval:n} and leaves the resulting larger (\texttt{max}) or smaller
-% (\texttt{min}) value in the input stream. This function does not raise any
-% exception beyond those raised when evaluating its argument. Within
-% floating point expressions, |max()| and |min()| can be used.
+% \cs{fp_eval:n} and leaves the resulting larger (\texttt{max}) or
+% smaller (\texttt{min}) value in the input stream. If the argument
+% is a tuple, \enquote{invalid operation} occurs, but no other case
+% raises exceptions. Within floating point expressions, |max()| and
+% |min()| can be used.
% \end{function}
%
% \section{Disclaimer and roadmap}
@@ -1297,6 +1363,7 @@
%
% The following need to be done. I'll try to time-order the items.
% \begin{itemize}
+% \item Function to count items in a tuple (and to determine if something is a tuple).
% \item Decide what exponent range to consider.
% \item Support signalling \texttt{nan}.
% \item Modulo and remainder, and rounding functions |quantize|,
@@ -1326,7 +1393,7 @@
% \pkg{Pgfmath} also provides box-measurements (depth, height, width), but
% boxes are not possible expandably.
%
-% Bugs.
+% Bugs, and tests to add.
% \begin{itemize}
% \item Check that functions are monotonic when they should.
% \item Add exceptions to |?:|, |!<=>?|, |&&|, \verb"||", and |!|.
diff --git a/l3packages/xfp/xfp.dtx b/l3packages/xfp/xfp.dtx
index 70c5bd8..dfa2303 100644
--- a/l3packages/xfp/xfp.dtx
+++ b/l3packages/xfp/xfp.dtx
@@ -73,8 +73,8 @@
% integer expression interface for convenience.
%
% \begin{function}[EXP]{\fpeval}
-% The expandable command \cs{fpeval} takes as it's argument a floating
-% point expression and will produce a result using the normal rules of
+% The expandable command \cs{fpeval} takes as its argument a floating
+% point expression and produces a result using the normal rules of
% mathematics. As this command is expandable it can be used where \TeX{}
% requires a number and for example within a low-level \cs{edef} operation
% to give a purely numerical result.
@@ -122,9 +122,11 @@
% \item Dimensions, automatically expressed in points, \emph{e.g.},
% \texttt{pc} is~$12$.
% \item Automatic conversion (no need for \cs{number}) of
-% integer, dimension, and skip variables to floating points,
+% integer, dimension, and skip variables to floating points numbers,
% expressing dimensions in points and ignoring the stretch and
% shrink components of skips.
+% \item Tuples: $(x_1,\ldots{},x_n)$ that can be added together,
+% multiplied or divided by a floating point number, and nested.
% \end{itemize}
%
% An example of use could be the following.
More information about the latex3-commits
mailing list