summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3kernel/l3int.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/l3kernel/l3int.dtx')
-rw-r--r--macros/latex/contrib/l3kernel/l3int.dtx114
1 files changed, 61 insertions, 53 deletions
diff --git a/macros/latex/contrib/l3kernel/l3int.dtx b/macros/latex/contrib/l3kernel/l3int.dtx
index 749de68557..fedb4617f9 100644
--- a/macros/latex/contrib/l3kernel/l3int.dtx
+++ b/macros/latex/contrib/l3kernel/l3int.dtx
@@ -43,7 +43,7 @@
% }^^A
% }
%
-% \date{Released 2021-11-12}
+% \date{Released 2021-11-22}
%
% \maketitle
%
@@ -59,6 +59,63 @@
%
% \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 (but the operands $a$, $b$, $c$ are still
+% constrained to an absolute value at most $2^{31}-1$);
+% \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,57 +124,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
-% 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
-% |"| 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}
+% \texttt{0}~for zero.
% \end{function}
%
% \begin{function}[EXP, added = 2018-03-30]{\int_eval:w}
@@ -130,7 +137,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}
%