[latex3-commits] [git/LaTeX3-latex3-latex3] main: Move documentation of integer expressions outside that of \int_eval:n (1bbc727f7)
Bruno Le Floch
blflatex at gmail.com
Mon Nov 15 13:32:45 CET 2021
Repository : https://github.com/latex3/latex3
On branch : main
Link : https://github.com/latex3/latex3/commit/1bbc727f7bf57a6ea61da7882fd0c68b6d059706
>---------------------------------------------------------------
commit 1bbc727f7bf57a6ea61da7882fd0c68b6d059706
Author: Bruno Le Floch <blflatex at gmail.com>
Date: Mon Nov 15 13:32:45 2021 +0100
Move documentation of integer expressions outside that of \int_eval:n
>---------------------------------------------------------------
1bbc727f7bf57a6ea61da7882fd0c68b6d059706
l3kernel/l3int.dtx | 112 ++++++++++++++++++++++++++++-------------------------
1 file changed, 59 insertions(+), 53 deletions(-)
diff --git a/l3kernel/l3int.dtx b/l3kernel/l3int.dtx
index 77e0dfad0..3a71f6741 100644
--- a/l3kernel/l3int.dtx
+++ b/l3kernel/l3int.dtx
@@ -59,6 +59,62 @@
%
% \section{Integer expressions}
%
+% Throughout this module, (almost) all \texttt{n}-type argument allow
+% for an \meta{intexpr} argument with the following syntax. 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_show:n { 5 + 4 * 3 - ( 3 + 4 * 5 ) }
+% \end{verbatim}
+% and
+% \begin{verbatim}
+% \tl_new:N \l_my_tl
+% \tl_set:Nn \l_my_tl { 5 }
+% \int_new:N \l_my_int
+% \int_set:Nn \l_my_int { 4 }
+% \int_show:n { \l_my_tl + \l_my_int * 3 - ( 3 + 4 * 5 ) }
+% \end{verbatim}
+% show the same result $-6$ because \cs[no-index]{l_my_tl} expands to
+% the integer denotation~|5| while the integer variable \cs{l_my_int}
+% takes the value~$4$. 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
+% should be terminated by a space if used in \cs{int_value:w} or in
+% a \TeX{}-style integer assignment.
+%
+% As all \TeX{} integers, integer operands can also be:
+% \tn{value}\Arg{\LaTeXe{} counter}; dimension or skip variables,
+% converted to integers in~\texttt{sp}; the character code of some
+% character given as \texttt{`}\meta{char} or
+% \texttt{`\textbackslash}\meta{char}; octal numbers given as
+% \texttt{'} followed by digits from \texttt{0} to \texttt{7}; or
+% hexadecimal numbers given as |"| followed by digits and upper case
+% letters from \texttt{A} to~\texttt{F}.
+% \end{texnote}
+%
% \begin{function}[EXP]{\int_eval:n}
% \begin{syntax}
% \cs{int_eval:n} \Arg{integer expression}
@@ -67,58 +123,7 @@
% 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}
-% and
-% \begin{verbatim}
-% \tl_new:N \l_my_tl
-% \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 ) }
-% \end{verbatim}
-% 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
-% should be terminated by a space if used in \cs{int_value:w} or in
-% a \TeX{}-style integer assignment.
-%
-% As all \TeX{} integers, integer operands can also be:
-% \tn{value}\Arg{\LaTeXe{} counter}; dimension or skip variables,
-% converted to integers in~\texttt{sp}; the character code of some
-% character given as \texttt{`}\meta{char} or
-% \texttt{`\textbackslash}\meta{char}; octal numbers given as
-% \texttt{'} followed by digits from \texttt{0} to \texttt{7}; or
-% hexadecimal numbers given as |"| followed by digits and upper case
-% letters from \texttt{A} to~\texttt{F}.
-% \end{texnote}
+% \texttt{0}~for zero.
% \end{function}
%
% \begin{function}[EXP, added = 2018-03-30]{\int_eval:w}
@@ -131,7 +136,8 @@
% 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}
+% instance, \cs{int_eval:w} \verb*|1 + 1 9| (with explicit space
+% tokens inserted using |~| in a code setting) expands to \texttt{29}
% since the digit~\texttt{9} is not part of the expression.
% \end{function}
%
More information about the latex3-commits
mailing list.