diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/expl3/l3intexpr.dtx')
| -rw-r--r-- | Master/texmf-dist/source/latex/expl3/l3intexpr.dtx | 435 |
1 files changed, 223 insertions, 212 deletions
diff --git a/Master/texmf-dist/source/latex/expl3/l3intexpr.dtx b/Master/texmf-dist/source/latex/expl3/l3intexpr.dtx index 25c95f8356a..4c43e63e6db 100644 --- a/Master/texmf-dist/source/latex/expl3/l3intexpr.dtx +++ b/Master/texmf-dist/source/latex/expl3/l3intexpr.dtx @@ -61,255 +61,247 @@ % \maketitle % % \begin{documentation} +% +% Calculation and comparison of integer values can be carried out +% using literal numbers, \texttt{int} registers, constants and +% integers stored in token list variables. The standard operators +% \texttt{+}, \texttt{-}, \texttt{/} and \texttt{*} and +% parentheses can be used within such expressions to carry +% arithmetic operations. This module carries out these functions +% on \emph{integer expressions} (`\texttt{int expr}'). % -% This module sets up evaluation of integer expressions and allows -% mixing |int| and |num| registers. -% -% An integer expression is one that contains integers in the form of -% numbers, registers containg numbers, i.e., |int| and |num| registers -% plus constants like |\c_one|, standard operators "+", "-", "/" and -% "*" and parentheses to group sub-expressions. -% -% \section{Functions} +%\section{Calculating and comparing integers} % -% \begin{function}{% -% \intexpr_eval:n / (EXP) -% } +% \begin{function}{\intexpr_eval:n / (EXP)} % \begin{syntax} -% "\intexpr_eval:n" \Arg{int~expr} +% "\intexpr_eval:n" \Arg{int~expr} % \end{syntax} -% The result of this expansion is a properly terminated <number>, -% i.e., one that can be used with "\if_case:w" and others. For example, -% \begin{quote} -% |\intexpr_eval:n{ 5 + 4*3 - (3+4*5) }| -% \end{quote} -% evaluates to $-6$. The result is returned after two expansions so -% if you find that you need to pass on the result to another function -% using the expansion engine, the recommendation is to use an "f" type -% expansion if in an expandable context or "x" otherwise. +% Evaluates an <integer expression>, expanding to a properly +% terminated <number> that can be used in any situation that +% demands one, or which can be typeset. For example, +%\begin{verbatim} +% \intexpr_eval:n{ 5 + 4*3 - (3+4*5) } +%\end{verbatim} +% evaluates to \(-6\). Two expansions are necessary to convert the +% <expression> into the <number> it represents. Full expansion to +% the <number> can be carried out using an \texttt{f} expansion +% in an expandable context or a \texttt{x} expansion in other +% cases. % \end{function} % -% -% \begin{function}{% -% \intexpr_compare_p:n / (EXP) | -% \intexpr_compare:n / (TF)(EXP) -% } +%\begin{function}{ +% \intexpr_compare_p:n / (EXP) | +% \intexpr_compare:n / (TF) (EXP) +%} % \begin{syntax} -% "\intexpr_compare_p:n" \Arg{<int~expr1> <rel> <int~expr2>} +% "\intexpr_compare_p:n" \Arg{<int~expr1> <rel> <int~expr2>} +% "\intexpr_compare:nTF" \Arg{<int~expr1> <rel> <int~expr2>} +% ~~~~<true code> <false code> % \end{syntax} -% Compares <int~expr1> with <int~expr2> using C-like relational -% operators, i.e. +% Evaluates <integer expression 1> and <integer expression 2> as +% described for \cs{intexpr_eval:n}, and then carries out a +% comparison of the resulting integers using C-like operators: % \begin{center} -% \begin{tabular}{ll@{\hspace{2cm}}ll} -% Less than & "<" & Less than or equal & "<=" \\ -% Greater than & "<" & Greater than or equal & ">=" \\ -% Equal & "==" or "=" & Not equal & "!=" -% \end{tabular} +% \begin{tabular}{ll@{\hspace{2cm}}ll} +% Less than & "<" & Less than or equal & "<=" \\ +% Greater than & "<" & Greater than or equal & ">=" \\ +% Equal & "==" or "=" & Not equal & "!=" +% \end{tabular} % \end{center} -% Both integer expressions are evaluated fully in the process. Note -% the syntax, which allows natural input in the style of +% Based on the result of the comparison either the <true code> +% or <false code> is executed. Both integer expressions are evaluated +% fully in the process. Note the syntax, which allows natural input in +% the style of % \begin{quote} % |\intexpr_compare_p:n {5+3 != \l_tmpb_int}| % \end{quote} -% "=" is added for the sake of \TeX\ users accustomed to using a -% single equal sign. +% \texttt{=} is available as comparator (in addition to those +% familiar to C users) as standard \TeX\ practice is to compare +% values using a single \texttt{=}. % \end{function} % % -% \begin{function}{% -% \intexpr_compare_p:nNn / (EXP) | -% \intexpr_compare:nNn / (TF)(EXP) -% } -% \begin{syntax} -% "\intexpr_compare_p:nNn" \Arg{int~expr1}<rel>\Arg{int~expr2} -% \end{syntax} -% Compares <int~expr1> with <int~expr2> using one of the relations -% "=", ">" or "<". This is faster than the variant above but at the -% cost of requiring a little more typing and not supporting the -% extended set of relational operators. Note that if both expressions -% are normal integer variables as in -% \begin{quote} -% "\intexpr_compare:nNnTF \l_temp_int < \c_zero {negative}{non-negative}" -% \end{quote} -% you can safely omit the braces. -% \end{function} -% -% -% \begin{function}{% -% \intexpr_max:nn / (EXP)| -% \intexpr_min:nn / (EXP)| -% } -% \begin{syntax} -% "\intexpr_max:nn" \Arg{int~expr1} \Arg{int~expr2} -% \end{syntax} -% Return the largest or smallest of two integer expressions. -% \end{function} -% -% \begin{function}{% -% \intexpr_abs:n / (EXP)| -% } -% \begin{syntax} -% "\intexpr_abs:n" \Arg{int~expr} -% \end{syntax} -% Return the numerical value of an integer expression. -% \end{function} -% -% \begin{function}{% -% \intexpr_if_odd:n / (EXP)(TF) | -% \intexpr_if_odd_p:n / (EXP) | -% \intexpr_if_even:n / (EXP)(TF) | -% \intexpr_if_even_p:n / (EXP) | -% } -% \begin{syntax} -% "\intexpr_if_odd:nTF" \Arg{int~expr} \Arg{true} \Arg{false} -% \end{syntax} -% These functions test if an integer expression is even or odd. -% \end{function} -% -% -% -% -% -% -% \begin{function}{% -% \intexpr_div_truncate:nn / (EXP) | -% \intexpr_div_round:nn / (EXP) | -% \intexpr_mod:nn / (EXP) | -% } -% \begin{syntax} -% "\intexpr_div_truncate:n" \Arg{int~expr} \Arg{int~expr} \\ -% "\intexpr_mod:nn" \Arg{int~expr} \Arg{int~expr} -% \end{syntax} -% If -% you want the result of a division to be truncated use -% "\intexpr_div_truncate:nn". "\intexpr_div_round:nn" is added for -% completeness. "\intexpr_mod:nn" returns the remainder of a division. -% \end{function} -% -% -% -% -% -% -% -% -% -% -% -% \section{Primitive functions} -% -% -% \begin{function}{% -% \intexpr_value:w | -% } -% \begin{syntax} -% "\intexpr_value:w" <integer> \\ -% "\intexpr_value:w" <tokens> <optional space> -% \end{syntax} -% Expands <tokens> until an <integer> is formed. One space may be -% gobbled in the process. -% \begin{texnote} -% This is the \TeX{} primitive \tn{number}. -% \end{texnote} -% \end{function} -% -% \begin{function}{% -% \intexpr_eval:w | -% \intexpr_eval_end: | -% } +%\begin{function}{ +% \intexpr_compare_p:nNn / (EXP) | +% \intexpr_compare:nNn / (TF)(EXP) +%} % \begin{syntax} -% "\intexpr_eval:w" <int expr> "\intexpr_eval_end:" +% "\intexpr_compare_p:nNn" \Arg{int~expr1} <rel> \Arg{int~expr2} % \end{syntax} -% Evaluates <int expr>. The evaluation stops when an -% unexpandable token of catcode other than 12 is reached or -% "\intexpr_end:" is read. The latter is gobbled by the scanner -% mechanism. -% \begin{texnote} -% This is the \eTeX{} primitive \tn{numexpr}. -% \end{texnote} -% \end{function} -% -% \begin{function}{% -% \if_intexpr_compare:w | -% } +% Evaluates <integer expression 1> and <integer expression 2> as +% described for \cs{intexpr_eval:n}, then compares the two +% results using one of the relations \texttt{=}, "<" or +% ">". These functions are faster than the \texttt{n} +% variants described above but do not support an extended set +% of relational operators. +%\end{function} +% +% +%\begin{function}{ +% \intexpr_max:nn / (EXP)| +% \intexpr_min:nn / (EXP) +%} % \begin{syntax} -% "\if_intexpr_compare:w" <number1> <rel> <number2> <true> "\else:" <false> "\fi:" +% "\intexpr_max:nn" \Arg{int~expr1} \Arg{int~expr2} % \end{syntax} -% Compare two numbers. It is recommended to use "\intexpr_eval:n" to -% correctly evaluate and terminate these numbers. <rel> is one of -% "<", "=" or ">" with catcode 12. -% \begin{texnote} -% This is the \TeX{} primitive \tn{ifnum}. -% \end{texnote} +% Evaluates <integer expression 1> and <integer expression 2> as +% described for \cs{intexpr_eval:n}, expanding to the larger or +% smaller of the two resulting <numbers> (for \texttt{max} and +% \texttt{min}, respectively). % \end{function} % -% \begin{function}{% -% \if_intexpr_odd:w | -% } +%\begin{function}{\intexpr_abs:n / (EXP)} % \begin{syntax} -% "\if_intexpr_odd:w" <number> <true> "\else:" <false> "\fi:" +% "\intexpr_abs:n" \Arg{int~expr} % \end{syntax} -% Execute <true> if <number> is odd, <false> otherwise. -% \begin{texnote} -% This is the \TeX{} primitive \tn{ifodd}. -% \end{texnote} +% Evaluates <integer expression> as described for \cs{intexpr_eval:n} +% and expands to the absolute value of the resulting <number>. % \end{function} % -% \begin{function}{% -% \if_intexpr_case:w | -% \or: | -% } +%\begin{function}{ +% \intexpr_if_odd:n / (EXP)(TF) | +% \intexpr_if_odd_p:n / (EXP) | +% \intexpr_if_even:n / (EXP)(TF) | +% \intexpr_if_even_p:n / (EXP) | +%} % \begin{syntax} -% "\if_intexpr_case:w" <number> <case0> "\or:" <case1> "\or:" "..." "\else:" -% <default> "\fi:" +% "\intexpr_if_odd:nTF" \Arg{int~expr} \Arg{true} \Arg{false} % \end{syntax} -% Chooses case <number>. If you wish to use negative numbers as well, -% you can offset them with "\intexpr_eval:n". -% \begin{texnote} -% These are the \TeX{} primitives \tn{ifcase} and \tn{or}. -% \end{texnote} +% Evaluates <integer expression> as described for \cs{intexpr_eval:n} +% and execute <true code> or <false code> depending on whether +% the resulting <number> is odd or even. % \end{function} % -%^^A Keep the documenation-checking happy -%\ExplSyntaxOn -%\seq_gput_right:Nx \g_doc_macros_seq { \token_to_str:N \or: } -%\ExplSyntaxOff -% -% \begin{function}{% -% \intexpr_while_do:nn | -% \intexpr_until_do:nn | -% \intexpr_do_while:nn | -% \intexpr_do_until:nn | -% } +%\begin{function}{ +% \intexpr_div_truncate:nn / (EXP) | +% \intexpr_div_round:nn / (EXP) | +% \intexpr_mod:nn / (EXP) | +%} +% \begin{syntax} +% "\intexpr_div_truncate:nn" \Arg{int~expr1} \Arg{int~expr2} +% "\intexpr_mod:nn" \Arg{int~expr1} \Arg{int~expr2} +% \end{syntax} +% Evaluates <integer expression 1> and <integer expression 2> as +% described for \cs{intexpr_eval:n}, expanding to the appropriate +% result of division of the resulting <numbers>. The +% \texttt{truncate} function expands to the integer part of the +% division with the decimal simply discarded, whereas +% \texttt{round} will use the decimal part to round the integer +% up if appropriate. The \texttt{mod} function expands to the integer +% remainder of the division. +%\end{function} +% +% \section{Primitive (internal) functions} +% +%\begin{function}{ +% \if_num:w / (EXP) | +% \if_inexpr_compare:w / (EXP) +%} +% \begin{syntax} +% "\if_num:w" <number1> <rel> <number2> <true> "\else:" <false> "\fi:" +% \end{syntax} +% Compare two integers using <rel>, which must be one of +% \texttt{=}, "<" or ">" with category code \(12\). +% The \cs{else:} branch is optional. +% \begin{texnote} +% These are both names for the \TeX\ primitive \cs{ifnum}. +% \end{texnote} +%\end{function} +% +%\begin{function}{ +% \if_intexpr_case:w / (EXP) | +% \if_case:w / (EXP) | +% \or: / (EXP) +%} +% \begin{syntax} +% "\if_case:w" <number> <case0> "\or:" <case1> "\or:" "..." "\else:" +% <default> "\fi:" +% \end{syntax} +% Selects a case to execute based on the value of <number>. The first +% case (<case0>) is executed if <number> is \(0\), the second +% (<case1>) if the <number> is \(1\), \emph{etc}. The +% <number> may be a literal, a constant or an integer +% expression (\emph{e.g}.~using \cs{intexpr_eval:n}). +% \begin{texnote} +% These are the \TeX\ primitives \cs{ifcase} (with two +% different names depending on context) and \cs{or}. +% \end{texnote} +%\end{function} +% +%\begin{function}{\intexpr_value:w / (EXP)} +% \begin{syntax} +% "\intexpr_value:w" <integer> +% "\intexpr_value:w" <tokens> <optional space> +% \end{syntax} +% Expands <tokens> until an <integer> is formed. One space may be +% gobbled in the process. +% \begin{texnote} +% This is the \TeX\ primitive \tn{number}. +% \end{texnote} +%\end{function} +% +%\begin{function}{ +% \intexpr_eval:w / (EXP) | +% \intexpr_eval_end: +%} +% \begin{syntax} +% "\intexpr_eval:w" <int expr> "\intexpr_eval_end:" +% \end{syntax} +% Evaluates <integer expression> as described for \cs{intexpr_eval:n}. +% The evalution stops when an unexpandable token with category code +% other than \(12\) is read or when \cs{intexpr_eval_end:} is +% reached. The latter is gobbled by the scanner mechanism: +% \cs{intexpr_eval_end:} itself is unexpandable but used correctly +% the entire construct is expandable. +% \begin{texnote} +% This is the \eTeX\ primitive \cs{numexpr}. +% \end{texnote} +%\end{function} +% +%\begin{function}{\if_intexpr_odd:w / (EXP)} +% \begin{syntax} +% "\if_intexpr_odd:w" <tokens> <true> "\else:" <false> "\fi:" +% "\if_intexpr_odd:w" <number> <true> "\else:" <false> "\fi:" +% \end{syntax} +% Expands <tokens> until a non-numeric tokens is found, and +% tests whether the resulting <number> is odd. If so, <true code> +% is executed. The \cs{else:} branch is optional. +% \begin{texnote} +% This is the \TeX\ primitive \cs{ifodd}. +% \end{texnote} +%\end{function} +% +%\begin{function}{ +% \intexpr_while_do:nn / (EXP) | +% \intexpr_until_do:nn / (EXP) | +% \intexpr_do_while:nn / (EXP) | +% \intexpr_do_until:nn / (EXP) +%} % \begin{syntax} -% "\intexpr_while_do:nn" \Arg{<int~expr1> <rel> <int~expr2>} \Arg{code} +% "\intexpr_while_do:nn" \Arg{<int~expr1> <rel> <int~expr2>} \Arg{code} % \end{syntax} -% "\intexpr_while_do:nn" tests the integer expressions against each -% other using a C-like <rel> as in "\intexpr_compare_p:n" and if true -% performs the <code> until the test fails. "\intexpr_do_while:nn" is -% similar but executes the <code> first and then performs the check, -% thus ensuring that the body is executed at least once. The `until' -% versions are similar but continue the loop as long as the test is -% false. They could be omitted as it is just a matter of switching the -% arguments in the test. +% In the case of the \texttt{while_do} version, the integer +% comparison is evaluated as described for \cs{intexpr_compare_p:n}, +% and if \texttt{true} execute the <code>. The test and code then +% alternate until the result is <false>. The \texttt{do_while} +% alternative first executes the <code> and then evaluates the integer +% comparison. In the \texttt{until} cases, the <code> is executed +% if the test is \texttt{false}: the loop is ended when the relation +% is \texttt{true}. % \end{function} % -% \begin{function}{% -% \intexpr_while_do:nNnn | -% \intexpr_until_do:nNnn | -% \intexpr_do_while:nNnn | -% \intexpr_do_until:nNnn | -% } +%\begin{function}{ +% \intexpr_while_do:nNnn / (EXP) | +% \intexpr_until_do:nNnn / (EXP) | +% \intexpr_do_while:nNnn / (EXP) | +% \intexpr_do_until:nNnn / (EXP) +%} % \begin{syntax} % "\intexpr_while_do:nNnn" <int expr> <rel> <int~expr> \Arg{code} % \end{syntax} -% Exactly as above but instead using the syntax of -% "\intexpr_compare_p:nNn". -% \end{function} -% -% -% -% +% These behave in the same manner as the preceding loops but use the +% relation logic described for \cs{intexpr_compare_p:nNn}. +%\end{function} % % \end{documentation} % @@ -328,6 +320,17 @@ %<*initex|package> % \end{macrocode} % +% \begin{macro}{\if_num:w} +% \begin{macro}{\if_case:w} +% Here are the remaining primitives for number comparisons and +% expressions. +% \begin{macrocode} +\cs_new_eq:NN \if_num:w \tex_ifnum:D +\cs_new_eq:NN \if_case:w \tex_ifcase:D +% \end{macrocode} +% \end{macro} +% \end{macro} +% % \begin{macro}{\intexpr_value:w} % \begin{macro}{\intexpr_eval:n,\intexpr_eval:w,\intexpr_eval_end:} % \begin{macro}{\if_intexpr_compare:w} @@ -634,6 +637,14 @@ % \end{macro} % \end{macro} % \end{macro} +% +%\begin{macro}{\c_max_register_int} +% This is here as this particular integer is needed both in package +% mode and to bootstrap \pkg{l3alloc} +% \begin{macrocode} +\tex_mathchardef:D \c_max_register_int = 32767 \scan_stop: +% \end{macrocode} +% \end{macro} % % \begin{macrocode} %</initex|package> |