% \iffalse
%% File: l3num.dtx Copyright (C) 2005-2009 Frank Mittelbach, LaTeX3 project
%%
%% It may be distributed and/or modified under the conditions of the
%% LaTeX Project Public License (LPPL), either version 1.3c of this
%% license or (at your option) any later version.  The latest version
%% of this license is in the file
%%
%%    http://www.latex-project.org/lppl.txt
%%
%% This file is part of the ``expl3 bundle'' (The Work in LPPL)
%% and all files in that bundle must be distributed together.
%%
%% The released version of this bundle is available from CTAN.
%%
%% -----------------------------------------------------------------------
%%
%% The development version of the bundle can be found at
%%
%%    http://www.latex-project.org/svnroot/experimental/trunk/
%%
%% for those people who are interested.
%%
%%%%%%%%%%%
%% NOTE: %%
%%%%%%%%%%%
%%
%%   Snapshots taken from the repository represent work in progress and may
%%   not work or may contain conflicting material!  We therefore ask
%%   people _not_ to put them into distributions, archives, etc. without
%%   prior consultation with the LaTeX Project Team.
%%
%% -----------------------------------------------------------------------
%
%<*driver|package>
\RequirePackage{l3names}
%</driver|package>
%\fi
\GetIdInfo$Id: l3num.dtx 1451 2009-08-08 06:33:34Z joseph $
       {L3 Experimental token numbers}
%\iffalse
%<*driver>
%\fi
\ProvidesFile{\filename.\filenameext}
  [\filedate\space v\fileversion\space\filedescription]
%\iffalse
\documentclass[full]{l3doc}
\begin{document}
\DocInput{l3num.dtx}
\end{document}
%</driver>
% \fi
%
%
% \title{The \textsf{l3num} package\thanks{This file
%         has version number \fileversion, last
%         revised \filedate.}\\
% Integers in macros}
% \author{\Team}
% \date{\filedate}
% \maketitle
%
% \begin{documentation}
%
% Instead of using counter registers for manipulation of
% integer values it is sometimes useful to keep such values in
% macros. For this \LaTeX3 offers the  type ``num''.
%
% One reason is the limited number of registers inside
% \TeX{}. However, when using \eTeX{} this is no longer an issue. It
% remains to be seen if there are other compelling reasons to keep
% this module.
%
% It turns out there might be as with a \meta{num} data type, the
% allocation module can do its bookkeeping without the aid of
% \meta{int} registers.
%
% \section{Functions}
%
% \begin{function}{%
%                  \num_new:N |
%                  \num_new:c |
% }
% \begin{syntax}
%    "\num_new:N"   <num>
% \end{syntax}
% Defines <num> to be a new variable of type "num" (initialized to
% zero). There is no way to
% define constant counters with these functions.
% \end{function}
%
% \begin{function}{%
%                  \num_incr:N |
%                  \num_incr:c |
%                  \num_gincr:N |
%                  \num_gincr:c
% }
% \begin{syntax}
%   "\num_incr:N"   <num>
% \end{syntax}
% Increments <num> by one. For global variables the global versions
% should be used.
% \end{function}
%
% \begin{function}{%
%                  \num_decr:N |
%                  \num_decr:c |
%                  \num_gdecr:N |
%                  \num_gdecr:c |
% }
% \begin{syntax}
%   "\num_decr:N"   <num>
% \end{syntax}
% Decrements <num> by one. For global variables the global versions
% should be used.
% \end{function}
%
% \begin{function}{%
%                  \num_zero:N |
%                  \num_zero:c |
%                  \num_gzero:N |
%                  \num_gzero:c |
% }
% \begin{syntax}
%   "\num_zero:N"   <num>
% \end{syntax}
% Resets <num> to zero. For global variables the global versions
% should be used.
% \end{function}
%
% \begin{function}{%
%                  \num_set:Nn |
%                  \num_set:cn |
%                  \num_gset:Nn |
%                  \num_gset:cn |
% }
% \begin{syntax}
%   "\num_set:Nn"   <num> \Arg{integer}
% \end{syntax}
% These functions will set the <num> register to the <integer> value.
% \end{function}
%
% \begin{function}{%
%                  \num_set_eq:NN |
%                  \num_set_eq:cN |
%                  \num_set_eq:Nc |
%                  \num_set_eq:cc |
% }
% \begin{syntax}
%   "\num_gset_eq:NN"   <num1> <num2>
% \end{syntax}
% These functions will set the <num1> register equal to <num2>.
% \end{function}
%
% \begin{function}{%
%                  \num_gset_eq:NN |
%                  \num_gset_eq:cN |
%                  \num_gset_eq:Nc |
%                  \num_gset_eq:cc |
% }
% \begin{syntax}
%   "\num_gset_eq:NN"   <num1> <num2>
% \end{syntax}
% These functions will globally set the <num1> register equal to <num2>.
% \end{function}
%
% \begin{function}{%
%                  \num_add:Nn |
%                  \num_add:cn |
%                  \num_gadd:Nn |
%                  \num_gadd:cn |
% }
% \begin{syntax}
%   "\num_add:Nn"   <num> \Arg{integer}
% \end{syntax}
% These functions will add to the <num> register the value <integer>.  If
% the second argument is a <num> register too, the surrounding braces
% can be left out.
%
% \end{function}
%
%
% \begin{function}{%
%                  \num_use:N |
%                  \num_use:c |
% }
% \begin{syntax}
%   "\num_use:N"   <num>
% \end{syntax}
% This function returns the integer value kept in <num> in a way
% suitable for further processing.
% \begin{texnote}
%   Since these <num>s are implemented as macros, the function
%   "\num_use:N" is effectively a noop and mainly there for
%   consistency with similar functions in other modules.
% \end{texnote}
% \end{function}
%
% \begin{function}{ \num_show:N |
%                   \num_show:c }
% \begin{syntax}
%   "\num_show:N" <num>
% \end{syntax}
% This function pauses the compilation and displays the integer value kept 
% in <num> on the console output.
% \end{function}
%
%
%
% \begin{function}{%
%                  \num_elt_count:n |
%                  \num_elt_count_prop:Nn |
% }
% \begin{syntax}
%   "\num_elt_count:n"   \Arg{balanced text} 
%   "\num_elt_count_prop:Nn" <prop> \Arg{balanced text} 
% \end{syntax}
% Discards their arguments and puts a "+1" in the input stream. Used
% to count elements in a token list. 
% \end{function}
%
% \section{Formatting a counter value}
%
% See the \textsf{l3int} module for ways of doing this.
%
% \section{Variable and constants}
%
% \begin{variable}{ \c_max_register_num }
% Maximum number of registers; possibly engine-specific.
% \end{variable}
%
% \begin{variable}{%
%                  \l_tmpa_num |
%                  \l_tmpb_num |
%                  \l_tmpc_num |
%                  \g_tmpa_num |
%                  \g_tmpb_num |
% }
% Scratch register for immediate use. They are not used by conditionals
% or predicate functions.
% \end{variable}
%
% \section{Primitive functions}
%
%
% \begin{function}{%
%                  \if_num:w |
% }
% \begin{syntax}
%   "\if_num:w" <number1> <rel> <number2> <true> "\else:" <false> "\fi:"
% \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}
% \end{function}
%
% \begin{function}{%
%                  \if_case:w |
%                  \or: |
% }
% \begin{syntax}
%   "\if_case:w" <number> <case0> "\or:" <case1> "\or:" "..." "\else:"
%   <default> "\fi:"
% \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}
% \end{function}
% 
%^^A Keep the documenation-checking happy
%\ExplSyntaxOn
%\seq_gput_right:Nx \g_doc_macros_seq { \token_to_str:N \or: } 
%\ExplSyntaxOff
%
% \end{documentation}
%
% \begin{implementation}
%
% \section{\pkg{l3num} implementation}
%
%
%    We start by ensuring that the required packages are loaded.
%    \begin{macrocode}
%<*package>
\ProvidesExplPackage
  {\filename}{\filedate}{\fileversion}{\filedescription}
\package_check_loaded_expl:
%</package>
%<*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}
%
% Functions that support \LaTeX's user accessible counters should be
% added here, too. But first the internal counters.
%
% \begin{macro}{\num_incr:N}
% \begin{macro}{\num_decr:N}
% \begin{macro}{\num_gincr:N}
% \begin{macro}{\num_gdecr:N}
%    Incrementing and decrementing of integer registers is done with
%    the following functions.
%    \begin{macrocode}
\cs_set_nopar:Npn \num_incr:N #1{\num_add:Nn#1 1}
\cs_set_nopar:Npn \num_decr:N #1{\num_add:Nn#1 \c_minus_one}
\cs_set_nopar:Npn \num_gincr:N #1{\num_gadd:Nn#1 1}
\cs_set_nopar:Npn \num_gdecr:N #1{\num_gadd:Nn#1 \c_minus_one}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\num_incr:c}
% \begin{macro}{\num_decr:c}
% \begin{macro}{\num_gincr:c}
% \begin{macro}{\num_gdecr:c}
%    We also need \ldots
%    \begin{macrocode}
\cs_generate_variant:Nn \num_incr:N {c}
\cs_generate_variant:Nn \num_decr:N {c}
\cs_generate_variant:Nn \num_gincr:N {c}
\cs_generate_variant:Nn \num_gdecr:N {c}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\num_zero:N}
% \begin{macro}{\num_zero:c}
% \begin{macro}{\num_gzero:N}
% \begin{macro}{\num_gzero:c}
%    We also need \ldots
%    \begin{macrocode}
\cs_new_nopar:Npn \num_zero:N #1 {\num_set:Nn #1 0}
\cs_new_nopar:Npn \num_gzero:N #1 {\num_gset:Nn #1 0}
%    \end{macrocode}
%    
%    \begin{macrocode}
\cs_generate_variant:Nn \num_zero:N {c}
\cs_generate_variant:Nn \num_gzero:N {c}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
%
%
% \begin{macro}{\num_new:N}
% \begin{macro}{\num_new:c}
%    Allocate a new \m{num} variable and initialize it with zero.
%    \begin{macrocode}
\cs_new_nopar:Npn \num_new:N #1{\tl_new:Nn #1{0}}
\cs_generate_variant:Nn \num_new:N {c}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\num_set:Nn}
% \begin{macro}{\num_set:cn}
% \begin{macro}{\num_gset:Nn}
% \begin{macro}{\num_gset:cn}
% Assigning values to \m{num} registers.
%    \begin{macrocode}
\cs_new_nopar:Npn \num_set:Nn #1#2{
  \tl_set:No #1{ \tex_number:D \intexpr_eval:n {#2} }
}
\cs_generate_variant:Nn\num_set:Nn {c}
%    \end{macrocode}
%    
%    \begin{macrocode}
\cs_new_nopar:Npn \num_gset:Nn {\pref_global:D \num_set:Nn}
\cs_generate_variant:Nn\num_gset:Nn {c}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\num_set_eq:NN}
% \begin{macro}{\num_set_eq:cN}
% \begin{macro}{\num_set_eq:Nc}
% \begin{macro}{\num_set_eq:cc}
% Setting \m{num} registers equal to each other.
%    \begin{macrocode}
\cs_new_eq:NN \num_set_eq:NN \tl_set_eq:NN
\cs_generate_variant:Nn\num_set_eq:NN {c,Nc,cc}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\num_gset_eq:NN}
% \begin{macro}{\num_gset_eq:cN}
% \begin{macro}{\num_gset_eq:Nc}
% \begin{macro}{\num_gset_eq:cc}
% Setting \m{num} registers equal to each other.
%    \begin{macrocode}
\cs_new_eq:NN \num_gset_eq:NN \tl_gset_eq:NN
\cs_generate_variant:Nn\num_gset_eq:NN {c,Nc,cc}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\num_add:Nn}
% \begin{macro}{\num_add:cn}
% \begin{macro}{\num_gadd:Nn}
% \begin{macro}{\num_gadd:cn}
% Adding is easily done as the second argument goes through
% |\intexpr_eval:n|.
%    \begin{macrocode}
\cs_new_nopar:Npn \num_add:Nn #1#2 {\num_set:Nn #1{#1+#2}}
\cs_generate_variant:Nn\num_add:Nn {c}
%    \end{macrocode}
%
%    \begin{macrocode}
\cs_new_nopar:Npn \num_gadd:Nn {\pref_global:D \num_add:Nn}
\cs_generate_variant:Nn\num_gadd:Nn {c}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
%
% \begin{macro}{\num_use:N}
% \begin{macro}{\num_use:c}
%    Here is how num macros are accessed:
%    \begin{macrocode}
\cs_new_eq:NN\num_use:N \use:n
\cs_new_eq:NN\num_use:c \use:c
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\num_show:N}
% \begin{macro}{\num_show:c}
%    Here is how num macros are diagnosed:
%    \begin{macrocode}
\cs_new_eq:NN\num_show:N \cs_show:N
\cs_new_eq:NN\num_show:c \cs_show:c
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%
%
% \begin{macro}{\num_elt_count:n}
% \begin{macro}{\num_elt_count_prop:Nn}
% Helper function for counting elements in a list.
%    \begin{macrocode}
\cs_new:Npn \num_elt_count:n #1 { + 1 }
\cs_new:Npn \num_elt_count_prop:Nn #1#2 { + 1 }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\l_tmpa_num}
% \begin{macro}{\l_tmpb_num}
% \begin{macro}{\l_tmpc_num}
% \begin{macro}{\g_tmpa_num}
% \begin{macro}{\g_tmpb_num}
%    We provide an number local and two global \m{num}s, maybe we
%    need more or less.
%    \begin{macrocode}
\num_new:N \l_tmpa_num
\num_new:N \l_tmpb_num
\num_new:N \l_tmpc_num
\num_new:N \g_tmpa_num
\num_new:N \g_tmpb_num
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
%  \begin{macro}{\c_max_register_num}
%    \begin{macrocode}
\tex_mathchardef:D \c_max_register_num = 32767 \scan_stop:
%    \end{macrocode}
%  \end{macro}
%
%    \begin{macrocode}
%</initex|package>
%    \end{macrocode}
%
% \end{implementation}
% \PrintIndex
%
% \endinput