[latex3-commits] [git/LaTeX3-latex3-latex3] master: Document some quirks of \int_eval:n [ci skip] (bf3c69e)

[Bruno Le Floch]

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}