[latex3-commits] [git/LaTeX3-latex3-latex3] master: Document some quirks of \int_eval:n [ci skip] (bf3c69e)
Bruno Le Floch
bruno at le-floch.fr
Sat Mar 2 13:57:23 CET 2019
Repository : https://github.com/latex3/latex3
On branch : master
Link : https://github.com/latex3/latex3/commit/bf3c69eea0055d974c0ad0e60ae6052283cf313a
>---------------------------------------------------------------
commit bf3c69eea0055d974c0ad0e60ae6052283cf313a
Author: Bruno Le Floch <bruno at le-floch.fr>
Date: Sat Mar 2 13:36:20 2019 +0100
Document some quirks of \int_eval:n [ci skip]
One should probably do the same for \dim_eval:n etc in l3skip, but I'm not
sure I know all the subtleties.
>---------------------------------------------------------------
bf3c69eea0055d974c0ad0e60ae6052283cf313a
l3kernel/l3int.dtx | 61 ++++++++++++++++++++++++++++++++++++++--------------
1 file changed, 45 insertions(+), 16 deletions(-)
diff --git a/l3kernel/l3int.dtx b/l3kernel/l3int.dtx
index 952f57f..6bab01f 100644
--- a/l3kernel/l3int.dtx
+++ b/l3kernel/l3int.dtx
@@ -63,10 +63,30 @@
% \begin{syntax}
% \cs{int_eval:n} \Arg{integer expression}
% \end{syntax}
-% Evaluates the \meta{integer expression}, expanding any
-% integer and token list variables within the \meta{expression}
-% to their content (without requiring \cs{int_use:N}/\cs{tl_use:N})
-% and applying the standard mathematical rules. For example both
+% Evaluates the \meta{integer expression} and leaves the result in the
+% input stream as an integer denotation: for positive results an
+% explicit sequence of decimal digits not starting with~\texttt{0},
+% for negative results \texttt{-}~followed by such a sequence, and
+% \texttt{0}~for zero. The \meta{integer expression} should consist,
+% after expansion, of \texttt{+}, \texttt{-}, \texttt{*}, \texttt{/},
+% \texttt{(}, \texttt{)} and of course integer operands. The result
+% is calculated by applying standard mathematical rules with the
+% following peculiarities:
+% \begin{itemize}
+% \item \texttt{/} denotes division rounded to the closest integer with
+% ties rounded away from zero;
+% \item there is an error and the overall expression evaluates to zero
+% whenever the absolute value of any intermediate result exceeds
+% $2^{31}-1$, except in the case of scaling operations
+% $a$\texttt{*}$b$\texttt{/}$c$, for which $a$\texttt{*}$b$ may be
+% arbitrarily large;
+% \item parentheses may not appear after unary \texttt{+} or
+% \texttt{-}, namely placing \texttt{+(} or \texttt{-(} at the start
+% of an expression or after \texttt{+}, \texttt{-}, \texttt{*},
+% \texttt{/} or~\texttt{(} leads to an error.
+% \end{itemize}
+% Each integer operand can be either an integer variable (with no need
+% for \cs{int_use:N}) or an integer denotation. For example both
% \begin{verbatim}
% \int_eval:n { 5 + 4 * 3 - ( 3 + 4 * 5 ) }
% \end{verbatim}
@@ -76,21 +96,27 @@
% \tl_set:Nn \l_my_tl { 5 }
% \int_new:N \l_my_int
% \int_set:Nn \l_my_int { 4 }
-% \int_eval:n { \l_my_tl + \l_my_int * 3 - ( 3 + 4 * 5 ) }
+% \int_eval:n { \l_my_tl + \l_my_int * 3 - ( 3 + 4 * 5 ) }
% \end{verbatim}
-% both evaluate to \( -6 \). The \Arg{integer expression} may
-% contain the operators \texttt{+}, \texttt{-}, \texttt{*} and
-% \texttt{/}, along with parenthesis \texttt{(} and \texttt{)}.
-% Any functions within the expressions should expand to an
-% \meta{integer denotation}: a sequence of a sign and digits matching
-% the regex |\-?[0-9]+|).
-% After expansion \cs{int_eval:n} yields an \meta{integer denotation}
-% which is left in the input stream.
+% evaluate to $-6$ because \cs[no-index]{l_my_tl} expands to the
+% integer denotation~|5|. As the \meta{integer expression} is fully
+% expanded from left to right during evaluation, fully expandable and
+% restricted-expandable functions can both be used, and \cs{exp_not:n}
+% and its variants have no effect while \cs{exp_not:N} may incorrectly
+% interrupt the expression.
% \begin{texnote}
% Exactly two expansions are needed to evaluate \cs{int_eval:n}.
% The result is \emph{not} an \meta{internal integer}, and therefore
% requires suitable termination if used in a \TeX{}-style integer
% assignment.
+%
+% As all \TeX{} integers, integer operands can also be dimension or
+% skip variables, converted to integers in~\texttt{sp}, or octal
+% numbers given as \texttt{'} followed by digits other than
+% \texttt{8} and \texttt{9}, or hexadecimal numbers given as
+% \texttt{"} followed by digits or upper case letters from
+% \texttt{A} to~\texttt{F}, or the character code of some character
+% or one-character control sequence, given as \texttt{`}\meta{char}.
% \end{texnote}
% \end{function}
%
@@ -100,9 +126,12 @@
% \end{syntax}
% Evaluates the \meta{integer expression} as described for
% \cs{int_eval:n}. The end of the expression is the first token
-% encountered that cannot form part of such an expression.
-% If that token is \cs{scan_stop:} it is removed, otherwise not.
-% Spaces do \emph{not} terminate the expression.
+% encountered that cannot form part of such an expression. If that
+% token is \cs{scan_stop:} it is removed, otherwise not. Spaces do
+% \emph{not} terminate the expression. However, spaces terminate
+% explict integers, and this may terminate the expression: for
+% instance, \cs{int_eval:w} \verb*|1 + 1 9| expands to \texttt{29}
+% since the digit~\texttt{9} is not part of the expression.
% \end{function}
%
% \begin{function}[EXP, updated = 2012-09-26]{\int_abs:n}
More information about the latex3-commits
mailing list