expl3 1881 (30mar10)

git-svn-id: svn://tug.org/texlive/trunk@17631 c570f23f-e606-0410-a88d-b1316a301751

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>