summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3int.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3int.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3int.dtx142
1 files changed, 53 insertions, 89 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3int.dtx b/Master/texmf-dist/source/latex/l3kernel/l3int.dtx
index 947a91fa8ab..577a66a44fc 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3int.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3int.dtx
@@ -43,7 +43,7 @@
% }^^A
% }
%
-% \date{Released 2019-02-15}
+% \date{Released 2019-03-05}
%
% \maketitle
%
@@ -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
+% |"| 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}
@@ -698,9 +727,13 @@
% \cs{int_to_roman:n} \Arg{integer expression}
% \end{syntax}
% Places the value of the \meta{integer expression} in the input
-% stream as Roman numerals, either lower case (\cs{int_to_roman:n})
-% or upper case (\cs{int_to_Roman:n}). The Roman numerals are letters
-% with category code $11$ (letter).
+% stream as Roman numerals, either lower case (\cs{int_to_roman:n}) or
+% upper case (\cs{int_to_Roman:n}). If the value is negative or zero,
+% the output is empty. The Roman numerals are letters with category
+% code $11$ (letter). The letters used are |mdclxvi|, repeated as
+% needed: the notation with bars (such as $\bar{\mbox{v}}$ for $5000$)
+% is \emph{not} used. For instance \cs{int_to_roman:n} |{| 8249 |}|
+% expands to |mmmmmmmmccxlix|.
% \end{function}
%
% \section{Converting from other formats to integers}
@@ -2557,75 +2590,6 @@
% \end{variable}
% \end{variable}
%
-% \subsection{Deprecated}
-%
-% \begin{variable}[deprecated = 2019-12-31]
-% {
-% \c_zero, \c_one, \c_two, \c_three, \c_four, \c_five, \c_six,
-% \c_seven, \c_eight, \c_nine, \c_ten, \c_eleven, \c_twelve,
-% \c_thirteen, \c_fourteen, \c_fifteen, \c_sixteen, \c_thirty_two,
-% \c_one_hundred, \c_two_hundred_fifty_five,
-% \c_two_hundred_fifty_six, \c_one_thousand, \c_ten_thousand,
-% }
-% \begin{macro}{\@@_deprecated_constants:nn}
-% Constants that are now deprecated. By default define them with
-% \cs{int_const:Nn}. To deprecate them call for instance
-% \cs{__kernel_deprecation_error:Nnn} \cs{c_zero} |{0}|
-% |{2019-12-31}|. To redefine them (locally), use
-% \cs{@@_constdef:Nw}, with an \cs{exp_not:N} construction because the
-% constants themselves are outer at that point.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_deprecated_constants:nn #1#2
- {
- #1 \c_zero { 0 } #2
- #1 \c_one { 1 } #2
- #1 \c_two { 2 } #2
- #1 \c_three { 3 } #2
- #1 \c_four { 4 } #2
- #1 \c_five { 5 } #2
- #1 \c_six { 6 } #2
- #1 \c_seven { 7 } #2
- #1 \c_eight { 8 } #2
- #1 \c_nine { 9 } #2
- #1 \c_ten { 10 } #2
- #1 \c_eleven { 11 } #2
- #1 \c_twelve { 12 } #2
- #1 \c_thirteen { 13 } #2
- #1 \c_fourteen { 14 } #2
- #1 \c_fifteen { 15 } #2
- #1 \c_sixteen { 16 } #2
- #1 \c_thirty_two { 32 } #2
- #1 \c_one_hundred { 100 } #2
- #1 \c_two_hundred_fifty_five { 255 } #2
- #1 \c_two_hundred_fifty_six { 256 } #2
- #1 \c_one_thousand { 1000 } #2
- #1 \c_ten_thousand { 10000 } #2
- }
-\@@_deprecated_constants:nn { \int_const:Nn } { }
-\__kernel_deprecation_code:nn
- {
- \@@_deprecated_constants:nn
- { \__kernel_deprecation_error:Nnn } { { 2019-12-31 } }
- }
- {
- \@@_deprecated_constants:nn
- {
- \exp_after:wN \use:nnn
- \exp_after:wN \@@_constdef:Nw \exp_not:N
- }
- { \exp_stop_f: }
- }
-% \end{macrocode}
-% \end{macro}
-% \end{variable}
-%
-% \begin{macro}[deprecated = 2019-12-31]{\@@_value:w}
-% Made public.
-% \begin{macrocode}
-\cs_new_eq:NN \@@_value:w \int_value:w
-% \end{macrocode}
-% \end{macro}
-%
% \begin{macrocode}
%</initex|package>
% \end{macrocode}