% \iffalse
%% File: l3box.dtx Copyright (C) 2005-2007 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/cgi-bin/cvsweb.cgi/
%%
%% 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: l3box.dtx 718 2007-12-16 22:59:58Z morten $
          {L3 Experimental Box module}
%\iffalse
%<*driver>
%\fi
\ProvidesFile{\filename.\filenameext}
  [\filedate\space v\fileversion\space\filedescription]
%\iffalse
\documentclass{l3doc}
\begin{document}
\DocInput{\filename.\filenameext}
\end{document}
%</driver>
% \fi
%
%
% \title{The \textsf{l3box} package\thanks{This file
%         has version number \fileversion, last
%         revised \filedate.}\\
% Boxes}
% \author{\Team}
% \date{\filedate}
% \maketitle
%
% \section{Boxes}
%
%
%  There are three kinds of box operations: horizontal mode denoted
%  with prefix |\hbox_|, vertical mode with prefix |\vbox_|, and the
%  generic operations working in both modes with prefix |\box_|.
%
%
%  \subsection{Generic functions}
%
%  \begin{function}{%
%                   \box_new:N |
%                   \box_new:c |
%                   \box_new_l:N
%  }
%  \begin{syntax}
%     "\box_new:N"   <box>
%  \end{syntax}
%  Defines <box> to be a new variable of type "box".
%  \begin{texnote}
%  "\box_new:N" is the equivalent of plain \TeX{}'s \tn{newbox}.
%  However, the internal register allocation is done differently.
%  \end{texnote}
%  \end{function}
%
%  \begin{function}{%
%                   \if_hbox:N |
%                   \if_vbox:N |
%                   \if_box_empty:N |
%  }
%  \begin{syntax}
%     "\if_hbox:N" <box> <true code>"\else:" <false code>"\fi:"
%     "\if_box_empty:N" <box> <true code>"\else:" <false code>"\fi:"
%  \end{syntax}
%  "\if_hbox:N" and "\if_vbox:N" check if <box> is an horizontal or
%  vertical box resp. "\if_box_empty:N" tests if <box> is empty (void)
%  and executes "code" according to the test outcome.
%  \begin{texnote}
%    These are the \TeX{} primitives \tn{ifhbox}, \tn{ifvbox} and
%    \tn{ifvoid}.
%  \end{texnote}
%  \end{function}
%
%  \begin{function}{%
%                   \box_if_empty_p:N |
%                   \box_if_empty_p:c |
%                   \box_if_empty:NTF |
%                   \box_if_empty:cTF |
%                   \box_if_empty:NT |
%                   \box_if_empty:cT |
%                   \box_if_empty:NF |
%                   \box_if_empty:cF |
%  }
%  \begin{syntax}
%     "\box_if_empty:NTF"   <box> "{"\m{true code}"}" "{"\m{false code}"}"
%  \end{syntax}
%  Tests if <box> is empty (void) and executes "code" according to the
%  test outcome.
%  \begin{texnote}
%  "\box_if_empty:NTF" is the \LaTeX3 function name for \tn{ifvoid}.
%  \end{texnote}
%  \end{function}
%
%
%  \begin{function}{%
%                   \box_set_eq:NN |
%                   \box_set_eq:cN |
%                   \box_set_eq:Nc |
%                   \box_set_eq:cc |
%  }
%  \begin{syntax}
%     "\box_set_eq:NN"   <box1> <box2>
%  \end{syntax}
%  Sets <box1> equal to <box2>. Note that this eradicates the contents
%  of <box2> afterwards.
%  \end{function}
%
%
%  \begin{function}{%
%                   \box_gset_eq:NN |
%                   \box_gset_eq:cN |
%                   \box_gset_eq:Nc |
%                   \box_gset_eq:cc |
%  }
%  \begin{syntax}
%     "\box_gset_eq:NN"   <box1> <box2>
%  \end{syntax}
%  Globally sets <box1> equal to <box2>.
%  \end{function}
%
%
%  \begin{function}{%
%                   \box_set_to_last:N |
%                   \box_set_to_last:c |
%                   \box_gset_to_last:N |
%                   \box_gset_to_last:c |
%  }
%  \begin{syntax}
%     "\box_set_to_last:N"   <box> 
%  \end{syntax}
%  Sets <box> equal to the previous box |\R_last_box| and removes
%  |\R_last_box| from the current list (unless in outer vertical
%  or math mode).
%  \end{function}
%
%  \begin{function}{%
%                   \box_move_right:nn |
%                   \box_move_left:nn |
%                   \box_move_up:nn |
%                   \box_move_down:nn |
%  }
%  \begin{syntax}
%     "\box_move_left:nn"   "{"<dimen>"}" "{"<box function>"}"
%  \end{syntax}
%  Moves <box function> <dimen> in the direction specified. <box
%  function> is either an operation on a box such as "\box_use:N" or a
%  ``raw'' box specification like "\vbox:n{xyz}".
%  \end{function}
%
%  \begin{function}{%
%                   \box_clear:N |
%                   \box_clear:c |
%                   \box_gclear:N |
%                   \box_gclear:c |
%  }
%  \begin{syntax}
%     "\box_clear:N"   <box>
%  \end{syntax}
%  Clears <box> by setting it to the constant "\c_void_box".
%  "\box_gclear:N" does it globally.
%  \end{function}
%
%
%  \begin{function}{%
%                   \box_use:N |
%                   \box_use:c |
%                   \box_use_clear:N |
%                   \box_use_clear:c |
%  }
%  \begin{syntax}
%     "\box_use:N"   <box> \\
%     "\box_use_clear:N" <box>
%  \end{syntax}
%  "\box_use:N" puts a copy of <box> on the current list while
%  "\box_use_clear:N" puts the box on the current list and then
%  eradicates the contents of it.
%  \begin{texnote}
%  "\box_use:N" and "\box_use_clear:N" are the \TeX{} primitives
%  \tn{copy} and \tn{box} with new (descriptive) names.
%  \end{texnote}
%  \end{function}
%
%
%  \begin{function}{%
%                   \box_ht:N |
%                   \box_ht:c |
%                   \box_dp:N |
%                   \box_dp:c |
%                   \box_wd:N |
%                   \box_wd:c |
%  }
%  \begin{syntax}
%     "\box_ht:N"   <box>
%  \end{syntax}
%  Returns the height, depth, and width of <box> for use in dimension
%  settings.
%  \begin{texnote}
%  These are the \TeX{} primitives \tn{ht}, \tn{dp} and \tn{wd}.
%  \end{texnote}
%  \end{function}
%
%  \begin{function}{%
%                   \box_show:N |
%                   \box_show:c |
%  }
%  \begin{syntax}
%     "\box_show:N"   <box>
%  \end{syntax}
%  Writes the contents of <box> to the log file.
%  \begin{texnote}
%  This is the \TeX{} primitive \tn{showbox}.
%  \end{texnote}
%  \end{function}
%
%
%  \begin{variable}{%
%                   \c_empty_box |
%                   \l_tmpa_box |
%                   \l_tmpb_box |
%  }
%  \begin{syntax}
%  \end{syntax}
%  "\c_empty_box" is the constantly empty box. The others are scratch
%  boxes.
%  \end{variable}
%
%
%  \begin{variable}{%
%                   \R_last_box |
%  }
%  \begin{syntax}
%  \end{syntax}
%  "\R_last_box" is a read-only box register. You can set other
%  boxes to this box, which will then be removed from the current
%  list.
%  \end{variable}
%
%
%  \subsection{Horizontal mode}
%
%  \begin{function}{%
%                   \hbox:n |
%  }
%  \begin{syntax}
%     "\hbox:n" "{"<contents>"}"
%  \end{syntax}
%  Places a "hbox" of natural size.
%  \end{function}
%
%  \begin{function}{%
%                   \hbox_set:Nn |
%                   \hbox_set:cn |
%                   \hbox_gset:Nn |
%                   \hbox_gset:cn |
%  }
%  \begin{syntax}
%     "\hbox_set:Nn"   <box> "{"\m{contents}"}"
%  \end{syntax}
%  Sets <box> to be a vertical mode box containing \m{contents}. It has
%  it's natural size. "\hbox_gset:Nn" does it globally.
%  \end{function}
%
%
%  \begin{function}{%
%                   \hbox_set_to_wd:Nnn |
%                   \hbox_set_to_wd:cnn |
%                   \hbox_gset_to_wd:Nnn |
%                   \hbox_gset_to_wd:cnn |
%  }
%  \begin{syntax}
%     "\hbox_set_to_wd:Nnn"   <box> "{"\m{dimen}"}" "{"\m{contents}"}"
%  \end{syntax}
%  Sets <box> to contain \m{contents} and have width <dimen>.
%  "\hbox_gset_to_wd:Nn" does it globally.
%  \end{function}
%
%
%  \begin{function}{%
%                   \hbox_to_wd:nn |
%  }
%  \begin{syntax}
%     "\hbox_to_wd:nn" "{"<dimen>"}" <contents>
%  \end{syntax}
%  Places a <box> of width <dimen> containing <contents>.
%  \end{function}
%
%
%  \begin{function}{%
%                   \hbox_set_inline_begin:N |
%                   \hbox_set_inline_begin:c |
%                   \hbox_set_inline_end:    |
%                   \hbox_gset_inline_begin:N |
%                   \hbox_gset_inline_begin:c |
%                   \hbox_gset_inline_end:   |
%  }
%  \begin{syntax}
%     "\hbox_set_inline_begin:N" <box> <contents>
%     "\hbox_set_inline_end:"
%  \end{syntax}
%  Sets <box> to contain <contents>. This type is useful for use in
%  environment definitions.
%  \end{function}
%
%
%  \begin{function}{%
%                   \hbox_unpack:N |
%                   \hbox_unpack_clear:N    |
%  }
%  \begin{syntax}
%     "\hbox_unpack:N" <box>
%  \end{syntax}
%  "\hbox_unpack:N" unpacks the contents of the <box> register and
%  "\hbox_unpack_clear:N" also clears the <box> after unpacking it.
%  \begin{texnote}
%    These are the \TeX{} primitives \tn{unhcopy} and \tn{unhbox}.
%  \end{texnote}
%  \end{function}
%
%
%
%
%
%  \subsection{Vertical mode}
%
%  \begin{function}{%
%                   \vbox_set:Nn |
%                   \vbox_set:cn |
%                   \vbox_gset:Nn |
%                   \vbox_gset:cn |
%  }
%  \begin{syntax}
%     "\vbox_set:Nn"   <box> "{"\m{contents}"}"
%  \end{syntax}
%  Sets <box> to be a vertical mode box containing \m{contents}. It has
%  it's natural size. "\vbox_gset:Nn" does it globally.
%  \end{function}
%
%
%  \begin{function}{%
%                   \vbox_set_to_ht:Nnn |
%                   \vbox_set_to_ht:cnn |
%                   \vbox_gset_to_ht:Nnn |
%                   \vbox_gset_to_ht:cnn |
%                   \vbox_gset_to_ht:ccn |
%  }
%  \begin{syntax}
%     "\vbox_set_to_ht:Nnn"   <box> "{"\m{dimen}"}" "{"\m{contents}"}"
%  \end{syntax}
%  Sets <box> to contain \m{contents} and have total height <dimen>.
%  "\vbox_gset_to_ht:Nn" does it globally.
%  \end{function}
%
%
%  \begin{function}{%
%                   \vbox_set_inline_begin:N |
%                   \vbox_set_inline_end:    |
%                   \vbox_gset_inline_begin:N |
%                   \vbox_gset_inline_end:   |
%  }
%  \begin{syntax}
%     "\vbox_set_inline_begin:N" <box> <contents>
%     "\vbox_set_inline_end:"
%  \end{syntax}
%  Sets <box> to contain \m{contents}. This type is useful for use in
%  environment definitions.
%  \end{function}
%
%  \begin{function}{%
%                   \vbox_set_split_to_ht:NNn |
%  }
%  \begin{syntax}
%     "\vbox_set_split_to_ht:NNn" <box1> <box2> "{"<dimen>"}"
%  \end{syntax}
%  Sets <box1> to contain the top <dimen> part of <box2>.
%  \begin{texnote}
%    This is the \TeX{} primitive \tn{vsplit}.
%  \end{texnote}
%  \end{function}
%
%  \begin{function}{%
%                   \vbox:n |
%  }
%  \begin{syntax}
%     "\vbox:n" "{"<contents>"}"
%  \end{syntax}
%  Places a "vbox" of natural size with baseline equal to the baseline
%  of the last line in the box.
%  \end{function}
%
%  \begin{function}{%
%                   \vbox_to_ht:nn |
%                   \vbox_to_zero:n    |
%  }
%  \begin{syntax}
%     "\vbox_to_ht:nn" "{"<dimen>"}" <contents> \\
%     "\vbox_to_zero:n" <contents>
%  \end{syntax}
%  Places a <box> of size <dimen> containing <contents>.
%  \end{function}
%
%
%  \begin{function}{%
%                   \vbox_unpack:N |
%                   \vbox_unpack_clear:N    |
%  }
%  \begin{syntax}
%     "\vbox_unpack:N" <box>
%  \end{syntax}
%  "\vbox_unpack:N" unpacks the contents of the <box> register and
%  "\vbox_unpack_clear:N" also clears the <box> after unpacking it.
%  \begin{texnote}
%    These are the \TeX{} primitives \tn{unvcopy} and \tn{unvbox}.
%  \end{texnote}
%  \end{function}
%
%
% \StopEventually{}
%
%
%
% \subsection{The Implementation}
%
%
%    Announce and ensure that the required packages are loaded.
%    \begin{macrocode}
%<package>\ProvidesExplPackage
%<package>  {\filename}{\filedate}{\fileversion}{\filedescription}
%<package&!check>\RequirePackage{l3prg,l3token}\par
%<package&check>\RequirePackage{l3chk}\par
%<*initex|package>
%    \end{macrocode}
%
%  The code in this module is very straight forward so I'm not going to
%  comment it very extensively.
%
%
%  \subsubsection{Generic boxes}
%
%  \begin{macro}{\box_new:N}
%  \begin{macro}{\box_new_l:N}
%  \begin{macro}{\box_new:c}
%  Defining a new \m{box} register.
%    \begin{macrocode}
%<*initex>
\alloc_setup_type:nnn {box} \c_zero \c_max_register_num
%    \end{macrocode}
%    Now, remember that |\box255| has a special role in \TeX, it
%    shouldn't be allocated\dots
%    \begin{macrocode}
\seq_put_right:Nn \g_box_allocation_seq {255}
\def_new:Npn \box_new:N   #1 {\alloc_reg:NnNN g {box} \tex_mathchardef:D #1}
\def_new:Npn \box_new_l:N #1 {\alloc_reg:NnNN l {box} \tex_mathchardef:D #1}
%</initex>
%    \end{macrocode}
%    When we run on top of \LaTeX, we just use its allocation
%    mechanism.
%    \begin{macrocode}
%<package>\let_new:NN \box_new:N \newbox
\def_new:Npn \box_new:c {\exp_args:Nc \box_new:N}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
%  \begin{macro}{\if_hbox:N}
%  \begin{macro}{\if_vbox:N}
%  \begin{macro}{\if_box_empty:N}
%    The primitives for testing if a \m{box} is empty/void or which
%    type of box it is.
%    \begin{macrocode}
\let_new:NN \if_hbox:N        \tex_ifhbox:D
\let_new:NN \if_vbox:N        \tex_ifvbox:D
\let_new:NN \if_box_empty:N   \tex_ifvoid:D
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
%  \begin{macro}{\box_if_empty_p:N}
%  \begin{macro}{\box_if_empty_p:c}
%  \begin{macro}{\box_if_empty:NTF}
%  \begin{macro}{\box_if_empty:cTF}
%  \begin{macro}{\box_if_empty:NT}
%  \begin{macro}{\box_if_empty:cT}
%  \begin{macro}{\box_if_empty:NF}
%  \begin{macro}{\box_if_empty:cF}
%  Testing if a \m{box} is empty/void.
%    \begin{macrocode}
\def_new:Npn \box_if_empty_p:N #1{
  \if_box_empty:N #1 \c_true \else: \c_false \fi:}
\def_new:Npn \box_if_empty_p:c {\exp_args:Nc \box_if_empty_p:N}
\def_test_function_new:npn {box_if_empty:N}#1{\if_box_empty:N #1}
\def_new:Npn \box_if_empty:cTF {\exp_args:Nc \box_if_empty:NTF}
\def_new:Npn \box_if_empty:cT {\exp_args:Nc \box_if_empty:NT}
\def_new:Npn \box_if_empty:cF {\exp_args:Nc \box_if_empty:NF}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
%
%  \begin{macro}{\box_set_eq:NN}
%  \begin{macro}{\box_set_eq:cN}
%  \begin{macro}{\box_set_eq:Nc}
%  \begin{macro}{\box_set_eq:cc}
%  Assigning the contents of a box to be another box.
%  This clears the second box globally (that's how \TeX{} does it).
%    \begin{macrocode}
\def_new:Npn \box_set_eq:NN #1#2 {\tex_setbox:D #1 \tex_box:D #2}
\def_new:Npn \box_set_eq:cN {\exp_args:Nc \box_set_eq:NN}
\def_new:Npn \box_set_eq:Nc {\exp_args:NNc \box_set_eq:NN}
\def_new:Npn \box_set_eq:cc {\exp_args:Ncc \box_set_eq:NN}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
%  \begin{macro}{\box_gset_eq:NN}
%  \begin{macro}{\box_gset_eq:cN}
%  \begin{macro}{\box_gset_eq:Nc}
%  \begin{macro}{\box_gset_eq:cc}
%  Global version of the above.
%    \begin{macrocode}
\def_new:Npn \box_gset_eq:NN {\pref_global:D\box_set_eq:NN}
\def_new:Npn \box_gset_eq:cN {\exp_args:Nc \box_gset_eq:NN}
\def_new:Npn \box_gset_eq:Nc {\exp_args:NNc \box_gset_eq:NN}
\def_new:Npn \box_gset_eq:cc {\exp_args:Ncc \box_gset_eq:NN}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
%  \begin{macro}{\R_last_box}
%  A different name for this read-only primitive.
%    \begin{macrocode}
\let_new:NN \R_last_box \tex_lastbox:D
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\box_set_to_last:N}
%  \begin{macro}{\box_set_to_last:c}
%  \begin{macro}{\box_gset_to_last:N}
%  \begin{macro}{\box_gset_to_last:c}
%  Set a box to the previous box.
%    \begin{macrocode}
\def_new:Npn \box_set_to_last:N #1{\tex_setbox:D#1\R_last_box}
\def_new:Npn \box_set_to_last:c {\exp_args:Nc \box_set_to_last:N}
\def_new:Npn \box_gset_to_last:N {\pref_global:D \box_set_to_last:N}
\def_new:Npn \box_gset_to_last:c {\exp_args:Nc \box_gset_to_last:N}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
%  \begin{macro}{\box_move_left:nn}
%  \begin{macro}{\box_move_right:nn}
%  \begin{macro}{\box_move_up:nn}
%  \begin{macro}{\box_move_down:nn}
%  Move box material in different directions.
%    \begin{macrocode}
\def_long_new:Npn \box_move_left:nn #1#2{\tex_moveleft:D\dim_eval:n{#1}{#2}}
\def_long_new:Npn \box_move_right:nn #1#2{\tex_moveright:D\dim_eval:n{#1}{#2}}
\def_long_new:Npn \box_move_up:nn #1#2{\tex_raise:D\dim_eval:n{#1}{#2}}
\def_long_new:Npn \box_move_down:nn #1#2{\tex_lower:D\dim_eval:n{#1}{#2}}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
%  \begin{macro}{\box_clear:N}
%  \begin{macro}{\box_clear:c}
%  \begin{macro}{\box_gclear:N}
%  \begin{macro}{\box_gclear:c}
%  Clear a \m{box} register.
%    \begin{macrocode}
\def_new:Npn \box_clear:N #1{\box_set_eq:NN #1 \c_empty_box }
\def_new:Npn \box_clear:c {\exp_args:Nc \box_clear:N }
\def_new:Npn \box_gclear:N {\pref_global:D\box_clear:N}
\def_new:Npn \box_gclear:c {\exp_args:Nc \box_gclear:c }
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
%
%  \begin{macro}{\box_ht:N}
%  \begin{macro}{\box_ht:c}
%  \begin{macro}{\box_dp:N}
%  \begin{macro}{\box_dp:c}
%  \begin{macro}{\box_wd:n}
%  \begin{macro}{\box_wd:c}
%  Accessing the height, depth, and width of a \m{box} register.
%    \begin{macrocode}
\let_new:NN \box_ht:N \tex_ht:D
\def_new:Npn \box_ht:c {\exp_args:Nc \box_ht:N}
\let_new:NN \box_dp:N \tex_dp:D
\def_new:Npn \box_dp:c {\exp_args:Nc \box_dp:N}
\let_new:NN \box_wd:N \tex_wd:D
\def_new:Npn \box_wd:c {\exp_args:Nc \box_wd:N}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
%  \begin{macro}{\box_use_clear:N}
%  \begin{macro}{\box_use_clear:c}
%  \begin{macro}{\box_use:N}
%  \begin{macro}{\box_use:c}
%  Using a \m{box}. This is just \TeX{} primitives with meaningful
%  names.
%    \begin{macrocode}
\let_new:NN \box_use_clear:N \tex_box:D
\def_new:Npn \box_use_clear:c {\exp_args:Nc \box_use_clear:N}
\let_new:NN \box_use:N \tex_copy:D
\def_new:Npn \box_use:c {\exp_args:Nc \box_use:N}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
%  \begin{macro}{\box_show:N}
%  \begin{macro}{\box_show:c}
%  Show the contents of a box and write it into the log file.
%    \begin{macrocode}
\let:NN \box_show:N \tex_showbox:D
\def_new:Npn \box_show:c {\exp_args:Nc \box_show:N}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%
%  \begin{macro}{\c_empty_box}
%  \begin{macro}{\l_tmpa_box}
%  \begin{macro}{\l_tmpb_box}
%  We allocate some \m{box} registers here (and borrow a few from \LaTeX).
%    \begin{macrocode}
%<package>\let:NN \c_empty_box \voidb@x
%<package>\let_new:NN \l_tmpa_box \@tempboxa
%<initex>\box_new:N \c_empty_box
%<initex>\box_new:N \l_tmpa_box
\box_new:N \l_tmpb_box
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
%
%  \subsubsection{Vertical boxes}
%
%
%  \begin{macro}{\vbox:n}
%  Put a vertical box directly into the input stream.
%    \begin{macrocode}
\def_new:Npn \vbox:n {\tex_vbox:D \scan_stop:}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\vbox_set:Nn}
%  \begin{macro}{\vbox_set:cn}
%  \begin{macro}{\vbox_gset:Nn}
%  \begin{macro}{\vbox_gset:cn}
%  Storing material in a vertical box with a natural height.
%    \begin{macrocode}
\def_long_new:Npn \vbox_set:Nn #1#2 {\tex_setbox:D #1 \tex_vbox:D {#2}}
\def_new:Npn \vbox_set:cn {\exp_args:Nc \vbox_set:Nn}
\def_new:Npn \vbox_gset:Nn  {\pref_global:D \vbox_set:Nn}
\def_new:Npn \vbox_gset:cn {\exp_args:Nc \vbox_gset:Nn}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
%  \begin{macro}{\vbox_set_to_ht:Nnn}
%  \begin{macro}{\vbox_set_to_ht:cnn}
%  \begin{macro}{\vbox_gset_to_ht:Nnn}
%  \begin{macro}{\vbox_gset_to_ht:cnn}
%  \begin{macro}{\vbox_gset_to_ht:ccn}
%  Storing material in a vertical box with a specified height.
%    \begin{macrocode}
\def_long_new:Npn \vbox_set_to_ht:Nnn #1#2#3 {
  \tex_setbox:D #1 \tex_vbox:D to #2 {#3}}
\def_new:Npn \vbox_set_to_ht:cnn{\exp_args:Nc \vbox_set_to_ht:Nnn }
\def_new:Npn \vbox_gset_to_ht:Nnn {\pref_global:D \vbox_set_to_ht:Nnn }
\def_new:Npn \vbox_gset_to_ht:cnn{\exp_args:Nc \vbox_gset_to_ht:Nnn }
\def_new:Npn \vbox_gset_to_ht:ccn {\exp_args:Ncc \vbox_gset_to_ht:Nnn}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
%
%  \begin{macro}{\vbox_set_inline_begin:N}
%  \begin{macro}{\vbox_set_inline_end:}
%  \begin{macro}{\vbox_gset_inline_begin:N}
%  \begin{macro}{\vbox_set_inline_end:}
%  Storing material in a vertical box. This type is useful in
%  environment definitions.
%    \begin{macrocode}
\def_new:Npn \vbox_set_inline_begin:N  #1 {
  \tex_setbox:D #1 \tex_vbox:D \c_group_begin_token }
\let_new:NN \vbox_set_inline_end: \c_group_end_token
\def_new:Npn \vbox_gset_inline_begin:N {
  \pref_global:D \vbox_set_inline_begin:N }
\let_new:NN \vbox_gset_inline_end: \c_group_end_token
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
%
%  \begin{macro}{\vbox_to_ht:nn}
%  \begin{macro}{\vbox_to_zero:n}
%  Put a vertical box directly into the input stream.
%    \begin{macrocode}
\def_long_new:Npn \vbox_to_ht:nn #1#2{\tex_vbox:D to \dim_eval:n{#1}{#2}}
\def_long_new:Npn \vbox_to_zero:n #1 {\tex_vbox:D to \c_zero_dim {#1}}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%
%  \begin{macro}{\vbox_set_split_to_ht:NNn}
%  Splitting a vertical box in two.
%    \begin{macrocode}
\def_new:Npn \vbox_set_split_to_ht:NNn #1#2#3{
  \tex_setbox:D #1 \tex_vsplit:D #2 to #3
}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\vbox_unpack:N}
%  \begin{macro}{\vbox_unpack:c}
%  \begin{macro}{\vbox_unpack_clear:N}
%  \begin{macro}{\vbox_unpack_clear:c}
%  Unpacking a box and if requested also clear it.
%    \begin{macrocode}
\let_new:NN \vbox_unpack:N \tex_unvcopy:D
\def_new:Npn \vbox_unpack:c {\exp_args:Nc \vbox_unpack:N}
\let_new:NN \vbox_unpack_clear:N \tex_unvbox:D
\def_new:Npn \vbox_unpack_clear:c {\exp_args:Nc \vbox_unpack_clear:N}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
%
%
%
%
%
%  \subsubsection{Horizontal boxes}
%
%
%  \begin{macro}{\hbox:n}
%  Put a horizontal box directly into the input stream.
%    \begin{macrocode}
\def_new:Npn \hbox:n {\tex_hbox:D \scan_stop:}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\hbox_set:Nn}
%  \begin{macro}{\hbox_set:cn}
%  \begin{macro}{\hbox_gset:Nn}
%  \begin{macro}{\hbox_gset:cn}
%  Assigning the contents of a box to be another box.
%  This clears the second box globally (that's how \TeX{} does it).
%    \begin{macrocode}
\def_long_new:Npn \hbox_set:Nn #1#2 {\tex_setbox:D #1 \tex_hbox:D {#2}}
\def_new:Npn \hbox_set:cn {\exp_args:Nc \hbox_set:Nn}
\def_new:Npn \hbox_gset:Nn  {\pref_global:D \hbox_set:Nn}
\def_new:Npn \hbox_gset:cn {\exp_args:Nc \hbox_gset:Nn}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
%  \begin{macro}{\hbox_set_to_wd:Nnn}
%  \begin{macro}{\hbox_set_to_wd:cnn}
%  \begin{macro}{\hbox_gset_to_wd:Nnn}
%  \begin{macro}{\hbox_gset_to_wd:cnn}
%  Storing material in a horizontal box with a specified width.
%    \begin{macrocode}
\def_long_new:Npn \hbox_set_to_wd:Nnn #1#2#3 {
  \tex_setbox:D #1 \tex_hbox:D to \dim_eval:n{#2} {#3}}
\def_new:Npn \hbox_set_to_wd:cnn{\exp_args:Nc \hbox_set_to_wd:Nnn }
\def_new:Npn \hbox_gset_to_wd:Nnn {\pref_global:D \hbox_set_to_wd:Nnn }
\def_new:Npn \hbox_gset_to_wd:cnn{\exp_args:Nc \hbox_gset_to_wd:Nnn }
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
%
%  \begin{macro}{\hbox_set_inline_begin:N}
%  \begin{macro}{\hbox_set_inline_begin:c}
%  \begin{macro}{\hbox_set_inline_end:}
%  \begin{macro}{\hbox_gset_inline_begin:N}
%  \begin{macro}{\hbox_gset_inline_begin:c}
%  \begin{macro}{\hbox_set_inline_end:}
%  Storing material in a horizontal box. This type is useful in
%  environment definitions.
%    \begin{macrocode}
\def_new:Npn \hbox_set_inline_begin:N  #1 {
  \tex_setbox:D #1 \tex_hbox:D \c_group_begin_token }
\def:Npn \hbox_set_inline_begin:c {\exp_args:Nc
  \hbox_set_inline_begin:N}
\let_new:NN \hbox_set_inline_end: \c_group_end_token
\def_new:Npn \hbox_gset_inline_begin:N {
  \pref_global:D \hbox_set_inline_begin:N }
\def:Npn \hbox_gset_inline_begin:c {\exp_args:Nc
  \hbox_gset_inline_begin:N } 
\let_new:NN \hbox_gset_inline_end: \c_group_end_token
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
%  \begin{macro}{\hbox_to_wd:nn}
%  \begin{macro}{\hbox_to_zero:n}
%  Put a horizontal box directly into the input stream.
%    \begin{macrocode}
\def_long_new:Npn \hbox_to_wd:nn #1#2 {\tex_hbox:D to #1 {#2}}
\def_long_new:Npn \hbox_to_zero:n #1 {\tex_hbox:D to \c_zero_skip {#1}}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%
%  \begin{macro}{\hbox_unpack:N}
%  \begin{macro}{\hbox_unpack:c}
%  \begin{macro}{\hbox_unpack_clear:N}
%  \begin{macro}{\hbox_unpack_clear:c}
%  Unpacking a box and if requested also clear it.
%    \begin{macrocode}
\let_new:NN \hbox_unpack:N \tex_unhcopy:D
\def_new:Npn \hbox_unpack:c {\exp_args:Nc \hbox_unpack:N}
\let_new:NN \hbox_unpack_clear:N \tex_unhbox:D
\def_new:Npn \hbox_unpack_clear:c {\exp_args:Nc \hbox_unpack_clear:N}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
%
%
%^^A xo-or.sty:1528: \setbox\z@\vsplit\c_twohundred_fifty_five to\l_tmpa_dim
%^^A xo-or.dtx:222:  \global\setbox\removed@guard@box\lastbox}
%
%^^A it probably should be  \vbox_set:nn not  \vbox_set:Nn  as we can
%^^A have a number as the first arg ... do do we argue that this is not
%^^A supported on this level?
%^^A MH comment:
%^^A I don't think we should ever see people using numbers directly.
%^^A If they do it's \vbox_set:Nn \c_zero {...} anyway, not two-digit
%^^A numbers.
%
%    \begin{macrocode}
%</initex|package>
%<*showmemory>
\showMemUsage
%</showmemory>
%    \end{macrocode}
%
% \endinput
%
% $Log$
% Revision 1.10  2006/03/20 18:26:34  braams
% Updated the copyright notice (2006) and demoted all implementation
% sections to subsections and so on to clean up the toc for source3.tex
%
% Revision 1.9  2006/01/19 22:30:30  morten
% Added functions for accessing \tex_lastbox:D and moving box material
% in the four directions.
%
% Revision 1.8  2005/12/27 16:04:12  morten
% Changed RCS information retrieval
%
% Revision 1.7  2005/10/27 23:11:12  morten
% Moved \if_hbox:N, \if_vbox:N and _if_box_empty:N here
%
% Revision 1.6  2005/04/25 16:15:17  morten
% Fixed \bgroup/\egroup and made it run under initex
%
% Revision 1.5  2005/04/06 22:35:33  braams
% Now we have register allocation fitted
%
% Revision 1.4  2005/03/26 21:08:12  morten
% Fix \c_zero -> \c_zero_skip
%
% Revision 1.3  2005/03/16 22:36:46  braams
% Added the tweaks necessary to be able to load with initex
%
% Revision 1.2  2005/03/11 21:31:07  braams
% Fixed the use of RCS information; added \StopEventually
%