% \iffalse
%% File: l3box.dtx Copyright (C) 2005-2011 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: l3box.dtx 2223 2011-04-09 12:57:14Z will $
          {L3 Experimental Box module}
%\iffalse
%<*driver>
%\fi
\ProvidesFile{\filename.\filenameext}
  [\filedate\space v\fileversion\space\filedescription]
%\iffalse
\documentclass[full]{l3doc}
\begin{document}
\DocInput{l3box.dtx}
\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
%
% \begin{documentation}
%
%  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_|.
%
%
%  \section{Generic functions}
%
%  \begin{function}{ \box_new:N   |
%                    \box_new:c   }
%  \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}.
%  \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_horizontal_p:N |
%                   \box_if_horizontal_p:c |
%                   \box_if_horizontal:N / (TF) |
%                   \box_if_horizontal:c / (TF) }
%  \begin{syntax}
%     "\box_if_horizontal:NTF"   <box> \Arg{true code} \Arg{false code}
%  \end{syntax}
%  Tests if <box> is an horizontal box and executes <code> accordingly.
%  \end{function}
%
%  \begin{function}{\box_if_vertical_p:N |
%                   \box_if_vertical_p:c |
%                   \box_if_vertical:N / (TF) |
%                   \box_if_vertical:c / (TF) }
%  \begin{syntax}
%     "\box_if_vertical:NTF"   <box> \Arg{true code} \Arg{false code}
%  \end{syntax}
%  Tests if <box> is a vertical box and executes <code> accordingly.
%  \end{function}
%
%  \begin{function}{%
%                   \box_if_empty_p:N |
%                   \box_if_empty_p:c |
%                   \box_if_empty:N / (TF) |
%                   \box_if_empty:c / (TF) |
%  }
%  \begin{syntax}
%     "\box_if_empty:NTF"   <box> \Arg{true code} \Arg{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 |
%                   \box_set_eq_clear:NN |
%                   \box_set_eq_clear:cN |
%                   \box_set_eq_clear:Nc |
%                   \box_set_eq_clear:cc |
%  }
%  \begin{syntax}
%     "\box_set_eq:NN"   <box1> <box2>
%  \end{syntax}
%  Sets <box1> equal to <box2>. The "_clear" versions eradicate 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 |
%                   \box_gset_eq_clear:NN |
%                   \box_gset_eq_clear:cN |
%                   \box_gset_eq_clear:Nc |
%                   \box_gset_eq_clear:cc |
%  }
%  \begin{syntax}
%     "\box_gset_eq:NN"   <box1> <box2>
%  \end{syntax}
%  Globally sets <box1> equal to <box2>. The "_clear" versions eradicate the contents
%  of <box2> afterwards.
%  \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 |\l_last_box| and removes
%  |\l_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"   \Arg{dimen} \Arg{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_set_dp:Nn |
%  \box_set_dp:cn |
%}
%  \begin{syntax}
%    \cs{box_set_dp:Nn} \meta{box} \Arg{dimension expression}
%  \end{syntax}
%  Set the depth(below the baseline) of the \meta{box} to the value of
%  the \Arg{dimension expression}. This is a local assignment.
%\end{function}
%
%\begin{function}{ 
%  \box_set_ht:Nn |
%  \box_set_ht:cn |
%}
%  \begin{syntax}
%    \cs{box_set_ht:Nn} \meta{box} \Arg{dimension expression}
%  \end{syntax}
%  Set the height(above the baseline) of the \meta{box} to the value of
%  the \Arg{dimension expression}. This is a local assignment.
%\end{function}
%
%\begin{function}{ 
%  \box_set_wd:Nn |
%  \box_set_wd:cn |
%}
%  \begin{syntax}
%    \cs{box_set_wd:Nn} \meta{box} \Arg{dimension expression}
%  \end{syntax}
%  Set the width of the \meta{box} to the value of the 
%  \Arg{dimension expression}. This is a local assignment.
%\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}{%
%                   \l_last_box |
%  }
%  \begin{syntax}
%  \end{syntax}
%  "\l_last_box" is more or less a read-only box register managed by the
%  engine. It denotes the last box on the current list if there is one,
%  otherwise it is void. You can set other
%  boxes to this box, with the result that the last box on the current list is
%  removed at the same time (so it is with variable with side-effects).
%  \end{variable}
%
%
%  \section{Horizontal mode}
%
%  \begin{function}{%
%                   \hbox:n |
%  }
%  \begin{syntax}
%     "\hbox:n" \Arg{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> \Arg{contents}
%  \end{syntax}
%  Sets <box> to be a horizontal 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> \Arg{dimen} \Arg{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 |
%                   \hbox_to_zero:n |
%  }
%  \begin{syntax}
%     "\hbox_to_wd:nn" \Arg{dimen} <contents>
%     "\hbox_to_zero:n" <contents>
%  \end{syntax}
%  Places a <box> of width <dimen> containing <contents>. "\hbox_to_zero:n"
%  is a shorthand for a width of zero.
%  \end{function}
%
%
%  \begin{function}{%
%                   \hbox_overlap_left:n |
%                   \hbox_overlap_right:n |
%  }
%  \begin{syntax}
%     "\hbox_overlap_left:n"  <contents>
%  \end{syntax}
%  Places a <box> of width zero containing <contents> in a way the it overlaps
%  with surrounding material (sticking out to the left or right).
%  \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:c |
%                   \hbox_unpack_clear:N    |
%                   \hbox_unpack_clear:c    |
%  }
%  \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}
%
%
%
%
%
%  \section{Vertical mode}
%
%  \begin{function}{%
%                   \vbox:n |
%  }
%  \begin{syntax}
%     "\vbox:n" \Arg{contents}
%  \end{syntax}
%  Places a "vbox" of natural size with baseline equal to the baseline
%  of the last object in the box, i.e., if the last object is a line of text
%  the box has the same depth as that line; otherwise the depth will be zero.
%  \end{function}
%
%  \begin{function}{%
%                   \vbox_top:n |
%  }
%  \begin{syntax}
%     "\vbox_top:n" \Arg{contents}
%  \end{syntax}
%  Same as "\vbox:n" except that the reference point will be at the baseline
%  of the first object in the box not the last.
%  \end{function}
%
%  \begin{function}{%
%                   \vbox_set:Nn |
%                   \vbox_set:cn |
%                   \vbox_gset:Nn |
%                   \vbox_gset:cn |
%  }
%  \begin{syntax}
%     "\vbox_set:Nn"   <box> \Arg{contents}
%  \end{syntax}
%  Sets <box> to be a vertical mode box containing \m{contents}. It has
%  its natural size and the reference point will be at the baseline of the
%  last object in the box. "\vbox_gset:Nn" does it globally.
%  \end{function}
%
%
%  \begin{function}{%
%                   \vbox_set_top:Nn |
%                   \vbox_set_top:cn |
%                   \vbox_gset_top:Nn |
%                   \vbox_gset_top:cn |
%  }
%  \begin{syntax}
%     "\vbox_set_top:Nn"   <box> \Arg{contents}
%  \end{syntax}
%  Sets <box> to be a vertical mode box containing \m{contents}. It has
%  its natural size  (usually a small height and a larger depth) 
%  and the reference point will be at the baseline of the
%  first object in the box. "\vbox_gset_top: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> \Arg{dimen} \Arg{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> \Arg{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_to_ht:nn |
%                   \vbox_to_zero:n    |
%  }
%  \begin{syntax}
%     "\vbox_to_ht:nn" \Arg{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:c |
%                   \vbox_unpack_clear:N    |
%                   \vbox_unpack_clear:c    |
%  }
%  \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}
%
%
% \end{documentation}
%
% \begin{implementation}
%
%
%
% \section{\pkg{l3box} implementation}
%
%
%    Announce and ensure that the required packages are loaded.
%    \begin{macrocode}
%<*package>
\ProvidesExplPackage
  {\filename}{\filedate}{\fileversion}{\filedescription}
\package_check_loaded_expl:
%</package>
%<*initex|package>
%    \end{macrocode}
%
%  The code in this module is very straight forward so I'm not going to
%  comment it very extensively.
%
%
%  \subsection{Generic boxes}
%
%  \begin{macro}{\box_new:N,\box_new:c}
%  Defining a new \m{box} register.
% \testfile{m3box001.lvt}
%    \begin{macrocode}
%<*initex>
\alloc_new:nnnN {box} \c_zero \c_max_register_int \tex_mathchardef:D
%    \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}
%</initex>
%    \end{macrocode}
%    When we run on top of \LaTeX, we just use its allocation
%    mechanism.
%    \begin{macrocode}
%<*package>
\cs_new_protected:Npn \box_new:N #1 {
  \chk_if_free_cs:N #1
  \newbox #1
}
%</package>
%    \end{macrocode}
%
%    \begin{macrocode}
\cs_generate_variant:Nn \box_new:N {c}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\if_hbox:N,\if_vbox:N,\if_box_empty:N}
%  \testfile*
%    The primitives for testing if a \m{box} is empty/void or which
%    type of box it is.
%    \begin{macrocode}
\cs_new_eq:NN \if_hbox:N        \tex_ifhbox:D
\cs_new_eq:NN \if_vbox:N        \tex_ifvbox:D
\cs_new_eq:NN \if_box_empty:N   \tex_ifvoid:D
%    \end{macrocode}
%  \end{macro}
%
%
% \begin{macro}{\box_if_horizontal_p:N,\box_if_horizontal_p:c}
% \testfile*
% \begin{macro}{\box_if_vertical_p:N,\box_if_vertical_p:c}
% \testfile*
% \begin{macro}[TF]{\box_if_horizontal:N,\box_if_horizontal:c}
% \testfile*
% \begin{macro}[TF]{\box_if_vertical:N,\box_if_vertical:c}
% \testfile*
%    \begin{macrocode}
\prg_new_conditional:Nnn \box_if_horizontal:N {p,TF,T,F} {
  \tex_ifhbox:D #1 \prg_return_true: \else: \prg_return_false: \fi:
}
\prg_new_conditional:Nnn \box_if_vertical:N {p,TF,T,F} {
  \tex_ifvbox:D #1 \prg_return_true: \else: \prg_return_false: \fi:
}
\cs_generate_variant:Nn \box_if_horizontal_p:N {c}
\cs_generate_variant:Nn \box_if_horizontal:NTF {c}
\cs_generate_variant:Nn \box_if_horizontal:NT  {c}
\cs_generate_variant:Nn \box_if_horizontal:NF  {c}
\cs_generate_variant:Nn \box_if_vertical_p:N {c}
\cs_generate_variant:Nn \box_if_vertical:NTF {c}
\cs_generate_variant:Nn \box_if_vertical:NT  {c}
\cs_generate_variant:Nn \box_if_vertical:NF  {c}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\box_if_empty_p:N,\box_if_empty_p:c}
% \testfile*
% \begin{macro}[TF]{\box_if_empty:N,\box_if_empty:c}
% \testfile*
% Testing if a \m{box} is empty/void.
%    \begin{macrocode}
\prg_new_conditional:Nnn \box_if_empty:N {p,TF,T,F} {
  \tex_ifvoid:D #1 \prg_return_true: \else: \prg_return_false: \fi:
}
\cs_generate_variant:Nn \box_if_empty_p:N {c}
\cs_generate_variant:Nn \box_if_empty:NTF {c}
\cs_generate_variant:Nn \box_if_empty:NT  {c}
\cs_generate_variant:Nn \box_if_empty:NF  {c}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%
%
%  \begin{macro}{\box_set_eq:NN,\box_set_eq:cN,
%                \box_set_eq:Nc,\box_set_eq:cc}
% \testfile*
%  Assigning the contents of a box to be another box.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \box_set_eq:NN #1#2 {\tex_setbox:D #1 \tex_copy:D #2}
\cs_generate_variant:Nn \box_set_eq:NN {cN,Nc,cc}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\box_set_eq_clear:NN,\box_set_eq_clear:cN,
%                \box_set_eq_clear:Nc,\box_set_eq_clear:cc}
% \testfile*
%  Assigning the contents of a box to be another box.
%  This clears the second box globally (that's how \TeX{} does it).
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \box_set_eq_clear:NN #1#2 {\tex_setbox:D #1 \tex_box:D #2}
\cs_generate_variant:Nn \box_set_eq_clear:NN {cN,Nc,cc}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\box_gset_eq:NN,\box_gset_eq:cN,
%                \box_gset_eq:Nc,\box_gset_eq:cc,
%                \box_gset_eq_clear:NN,\box_gset_eq_clear:cN,
%                \box_gset_eq_clear:Nc,\box_gset_eq_clear:cc}
% \testfile*
%  Global version of the above.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \box_gset_eq:NN {\pref_global:D\box_set_eq:NN}
\cs_generate_variant:Nn \box_gset_eq:NN {cN,Nc,cc}
\cs_new_protected_nopar:Npn \box_gset_eq_clear:NN {\pref_global:D\box_set_eq_clear:NN}
\cs_generate_variant:Nn \box_gset_eq_clear:NN {cN,Nc,cc}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{variable}{\l_last_box}
%  A different name for this read-only primitive.
%    \begin{macrocode}
\cs_new_eq:NN \l_last_box \tex_lastbox:D
%    \end{macrocode}
%  \end{variable}
%
% \begin{macro}{\box_set_to_last:N, \box_gset_to_last:N,
%               \box_set_to_last:c, \box_gset_to_last:c}
% \testfile*
%  Set a box to the previous box.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \box_set_to_last:N #1{\tex_setbox:D#1\l_last_box}
\cs_generate_variant:Nn \box_set_to_last:N {c}
\cs_new_protected_nopar:Npn \box_gset_to_last:N {\pref_global:D \box_set_to_last:N}
\cs_generate_variant:Nn \box_gset_to_last:N {c}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\box_move_left:nn,\box_move_right:nn,
%                \box_move_up:nn,\box_move_down:nn}
% \testfile*
%  Move box material in different directions.
%    \begin{macrocode}
\cs_new:Npn \box_move_left:nn #1#2{\tex_moveleft:D\dim_eval:n{#1} #2}
\cs_new:Npn \box_move_right:nn #1#2{\tex_moveright:D\dim_eval:n{#1} #2}
\cs_new:Npn \box_move_up:nn #1#2{\tex_raise:D\dim_eval:n{#1} #2}
\cs_new:Npn \box_move_down:nn #1#2{\tex_lower:D\dim_eval:n{#1} #2}
%    \end{macrocode}
%  \end{macro}
%
% \begin{macro}{\box_clear:N,\box_clear:c,
%               \box_gclear:N,\box_gclear:c}
% \testfile*
%  Clear a \m{box} register.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \box_clear:N #1{\box_set_eq_clear:NN #1 \c_empty_box }
\cs_generate_variant:Nn \box_clear:N {c}
\cs_new_protected_nopar:Npn \box_gclear:N {\pref_global:D\box_clear:N}
\cs_generate_variant:Nn \box_gclear:N {c}
%    \end{macrocode}
%  \end{macro}
%
%
% \begin{macro}{\box_ht:N,\box_ht:c,
%               \box_dp:N,\box_dp:c,
%               \box_wd:N,\box_wd:c}
% \testfile*
%  Accessing the height, depth, and width of a \m{box} register.
%    \begin{macrocode}
\cs_new_eq:NN \box_ht:N \tex_ht:D
\cs_new_eq:NN \box_dp:N \tex_dp:D
\cs_new_eq:NN \box_wd:N \tex_wd:D
\cs_generate_variant:Nn \box_ht:N {c}
\cs_generate_variant:Nn \box_dp:N {c}
\cs_generate_variant:Nn \box_wd:N {c}
%    \end{macrocode}
%  \end{macro}
%
% \begin{macro}{\box_set_ht:Nn,
%               \box_set_ht:cn,
%               \box_set_dp:Nn,
%               \box_set_dp:cn,
%               \box_set_wd:Nn,
%               \box_set_wd:cn}
% Measuring is easy: all primitive work. These primitives are not 
% expandable, so the derived functions are not either.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \box_set_dp:Nn #1#2 {
  \box_dp:N #1 \etex_dimexpr:D #2 \scan_stop:
}
\cs_new_protected_nopar:Npn \box_set_ht:Nn #1#2 {
  \box_ht:N #1 \etex_dimexpr:D #2 \scan_stop:
}
\cs_new_protected_nopar:Npn \box_set_wd:Nn #1#2 {
  \box_wd:N #1 \etex_dimexpr:D #2 \scan_stop:
}
\cs_generate_variant:Nn \box_set_ht:Nn { c }
\cs_generate_variant:Nn \box_set_dp:Nn { c }
\cs_generate_variant:Nn \box_set_wd:Nn { c }
%    \end{macrocode}
%\end{macro}
%
%  \begin{macro}{\box_use_clear:N,\box_use_clear:c,
%                \box_use:N,\box_use:c}
%  \testfile{m3box001.lvt}
%  Using a \m{box}. These are just \TeX{} primitives with meaningful
%  names.
%    \begin{macrocode}
\cs_new_eq:NN \box_use_clear:N \tex_box:D
\cs_generate_variant:Nn \box_use_clear:N {c}
\cs_new_eq:NN \box_use:N \tex_copy:D
\cs_generate_variant:Nn \box_use:N {c}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\box_show:N,\box_show:c}
%  \testfile*
%  Show the contents of a box and write it into the log file.
%    \begin{macrocode}
\cs_set_eq:NN \box_show:N \tex_showbox:D
\cs_generate_variant:Nn \box_show:N {c}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{variable}{\c_empty_box,\l_tmpa_box,\l_tmpb_box}
%  We allocate some \m{box} registers here (and borrow a few from \LaTeX).
%    \begin{macrocode}
%<package>\cs_set_eq:NN \c_empty_box \voidb@x
%<package>\cs_new_eq: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{variable}
%
%
%  \subsection{Vertical boxes}
%
%
%  \begin{macro}{\vbox:n,
%                \vbox_top:n}
%  \testfile{m3box003.lvt}
%  Put a vertical box directly into the input stream.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \vbox:n {\tex_vbox:D \scan_stop:}
\cs_new_protected_nopar:Npn \vbox_top:n {\tex_vtop:D \scan_stop:}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\vbox_set:Nn,\vbox_set:cn,
%                \vbox_gset:Nn,\vbox_gset:cn}
%  \testfile*
%  Storing material in a vertical box with a natural height.
%    \begin{macrocode}
\cs_new_protected:Npn \vbox_set:Nn #1#2 {\tex_setbox:D #1 \tex_vbox:D {#2}}
\cs_generate_variant:Nn \vbox_set:Nn {cn}
\cs_new_protected_nopar:Npn \vbox_gset:Nn  {\pref_global:D \vbox_set:Nn}
\cs_generate_variant:Nn \vbox_gset:Nn {cn}
%    \end{macrocode}
%  \end{macro}
%
%
%  \begin{macro}{\vbox_set_top:Nn,\vbox_set_top:cn,
%                \vbox_gset_top:Nn,\vbox_gset_top:cn}
%  \testfile*
%    Storing material in a vertical box with a natural height and reference
%    point at the baseline of the first object in the box.
%    \begin{macrocode}
\cs_new_protected:Npn \vbox_set_top:Nn #1#2 {\tex_setbox:D #1 \tex_vtop:D {#2}}
\cs_generate_variant:Nn \vbox_set_top:Nn {cn}
\cs_new_protected_nopar:Npn \vbox_gset_top:Nn  {\pref_global:D \vbox_set_top:Nn}
\cs_generate_variant:Nn \vbox_gset_top:Nn {cn}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\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}
%  \testfile*
%  Storing material in a vertical box with a specified height.
%    \begin{macrocode}
\cs_new_protected:Npn \vbox_set_to_ht:Nnn #1#2#3 {
  \tex_setbox:D #1 \tex_vbox:D to #2 {#3}
}
\cs_generate_variant:Nn \vbox_set_to_ht:Nnn {cnn}
\cs_new_protected_nopar:Npn \vbox_gset_to_ht:Nnn { \pref_global:D \vbox_set_to_ht:Nnn }
\cs_generate_variant:Nn \vbox_gset_to_ht:Nnn {cnn,ccn}
%    \end{macrocode}
%  \end{macro}
%
%
%  \begin{macro}{\vbox_set_inline_begin:N,
%                \vbox_set_inline_end:,
%                \vbox_gset_inline_begin:N,
%                \vbox_gset_inline_end:}
%  \testfile*
%  Storing material in a vertical box. This type is useful in
%  environment definitions.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \vbox_set_inline_begin:N  #1 {
  \tex_setbox:D #1 \tex_vbox:D \c_group_begin_token }
\cs_new_eq:NN \vbox_set_inline_end: \c_group_end_token
\cs_new_protected_nopar:Npn \vbox_gset_inline_begin:N {
  \pref_global:D \vbox_set_inline_begin:N }
\cs_new_eq:NN \vbox_gset_inline_end: \c_group_end_token
%    \end{macrocode}
%  \end{macro}
%
%
%  \begin{macro}{\vbox_to_ht:nn,\vbox_to_zero:n}
%  \testfile*
%  Put a vertical box directly into the input stream.
%    \begin{macrocode}
\cs_new_protected:Npn \vbox_to_ht:nn #1#2{\tex_vbox:D to \dim_eval:n{#1}{#2}}
\cs_new_protected:Npn \vbox_to_zero:n #1 {\tex_vbox:D to \c_zero_dim {#1}}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\vbox_set_split_to_ht:NNn}
%  \testfile*
%  Splitting a vertical box in two.
%    \begin{macrocode}
\cs_new_protected_nopar: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,\vbox_unpack:c,
%                \vbox_unpack_clear:N,\vbox_unpack_clear:c}
%  \testfile*
%  Unpacking a box and if requested also clear it.
%    \begin{macrocode}
\cs_new_eq:NN \vbox_unpack:N \tex_unvcopy:D
\cs_generate_variant:Nn \vbox_unpack:N {c}
\cs_new_eq:NN \vbox_unpack_clear:N \tex_unvbox:D
\cs_generate_variant:Nn \vbox_unpack_clear:N {c}
%    \end{macrocode}
%  \end{macro}
%
%
%
%
%
%
%  \subsection{Horizontal boxes}
%
%
%  \begin{macro}{\hbox:n}
%  Put a horizontal box directly into the input stream.
%  \testfile{m3box002.lvt}
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \hbox:n {\tex_hbox:D \scan_stop:}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\hbox_set:Nn,\hbox_set:cn,
%                \hbox_gset:Nn,\hbox_gset:cn}
%  \testfile*
%  Assigning the contents of a box to be another box.
%  This clears the second box globally (that's how \TeX{} does it).
%    \begin{macrocode}
\cs_new_protected:Npn \hbox_set:Nn #1#2 {\tex_setbox:D #1 \tex_hbox:D {#2}}
\cs_generate_variant:Nn \hbox_set:Nn {cn}
\cs_new_protected_nopar:Npn \hbox_gset:Nn  {\pref_global:D \hbox_set:Nn}
\cs_generate_variant:Nn \hbox_gset:Nn {cn}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\hbox_set_to_wd:Nnn,\hbox_set_to_wd:cnn,
%                \hbox_gset_to_wd:Nnn,\hbox_gset_to_wd:cnn}
%  \testfile*
%  Storing material in a horizontal box with a specified width.
%    \begin{macrocode}
\cs_new_protected:Npn \hbox_set_to_wd:Nnn #1#2#3 {
  \tex_setbox:D #1 \tex_hbox:D to \dim_eval:n{#2} {#3}
}
\cs_generate_variant:Nn \hbox_set_to_wd:Nnn {cnn}
\cs_new_protected_nopar:Npn \hbox_gset_to_wd:Nnn {\pref_global:D \hbox_set_to_wd:Nnn }
\cs_generate_variant:Nn \hbox_gset_to_wd:Nnn {cnn}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\hbox_set_inline_begin:N,\hbox_set_inline_begin:c,
%                \hbox_gset_inline_begin:N,\hbox_gset_inline_begin:c,
%                \hbox_set_inline_end:,
%                \hbox_gset_inline_end:}
%  \testfile*
%  Storing material in a horizontal box. This type is useful in
%  environment definitions.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \hbox_set_inline_begin:N  #1 {
  \tex_setbox:D #1 \tex_hbox:D \c_group_begin_token 
}
\cs_generate_variant:Nn \hbox_set_inline_begin:N {c}
\cs_new_eq:NN \hbox_set_inline_end: \c_group_end_token
\cs_new_protected_nopar:Npn \hbox_gset_inline_begin:N {
  \pref_global:D \hbox_set_inline_begin:N 
}
\cs_generate_variant:Nn \hbox_gset_inline_begin:N {c}
\cs_new_eq:NN \hbox_gset_inline_end: \c_group_end_token
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\hbox_to_wd:nn,\hbox_to_zero:n}
%  \testfile*
%  Put a horizontal box directly into the input stream.
%    \begin{macrocode}
\cs_new_protected:Npn \hbox_to_wd:nn #1#2 {\tex_hbox:D to #1 {#2}}
\cs_new_protected:Npn \hbox_to_zero:n #1 {\tex_hbox:D to \c_zero_skip {#1}}
%    \end{macrocode}
%  \end{macro}
%
%
%  \begin{macro}{\hbox_overlap_left:n,\hbox_overlap_right:n}
%    Put a zero-sized box with the contents pushed against one side (which
%    makes it stick out on the other) directly into the input stream.
%    \begin{macrocode}
\cs_new_protected:Npn \hbox_overlap_left:n  #1 {\hbox_to_zero:n {\tex_hss:D #1}}
\cs_new_protected:Npn \hbox_overlap_right:n #1 {\hbox_to_zero:n {#1 \tex_hss:D}}
%    \end{macrocode}
%  \end{macro}
%
%
%  \begin{macro}{\hbox_unpack:N,\hbox_unpack:c,
%                \hbox_unpack_clear:N,\hbox_unpack_clear:c}
%  \testfile*
%  Unpacking a box and if requested also clear it.
%    \begin{macrocode}
\cs_new_eq:NN \hbox_unpack:N \tex_unhcopy:D
\cs_generate_variant:Nn \hbox_unpack:N {c}
\cs_new_eq:NN \hbox_unpack_clear:N \tex_unhbox:D
\cs_generate_variant:Nn \hbox_unpack_clear:N {c}
%    \end{macrocode}
%  \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>
%    \end{macrocode}
% 
%
% \end{implementation}
% \PrintIndex
%
% \endinput