# What does the \newbox command do?

I've searched everywhere on this website and google for a tutorial but I don't see many, which I thought it was weird.

I've found this page https://en.wikibooks.org/wiki/LaTeX/Boxes but it still doesn't explain what the newbox command does.

• Welcome! \setbox allows you to define a new box that you can set e.g. with \setbox. You can then copy it with \copy. E.g. \documentclass{article} \newbox\Rainbox \setbox\Rainbox\hbox{Rainbow} \begin{document} \copy\Rainbox \end{document. It is hard to just discuss \newbox without discussing the full concept of boxes in TeX.
– user194703
Jan 12, 2020 at 22:35
• what is then the difference between setbox and newbox? Jan 12, 2020 at 22:55
• @Rainb \newbox allocates a new box register (much like allocating a variable in other programming languages). \setbox adds stuff to that box. Jan 12, 2020 at 22:56
• \setbox tells TeX that what follows is a box. Just drop \newbox\Rainbox from the above example to see what happens.
– user194703
Jan 12, 2020 at 22:57

% latex.ltx, line 339:
\def\newbox   {\e@alloc\box
{\ifnum\allocationnumber<\@cclvi
\expandafter\chardef
\else
\expandafter\e@alloc@chardef
\fi}
{\count14}\insc@unt\float@count}


Uh, not really helpful, is it? OK, we know that \newbox should be followed by a control sequence name, let's say it's \foo. We need to look at \e@alloc:

% latex.ltx, line 386:
\def\e@alloc#1#2#3#4#5#6{%
\e@ch@ck{#3}{#4}{#5}#1%
\allocationnumber#3\relax
\global#2#6\allocationnumber
\wlog{\string#6=\string#1\the\allocationnumber}}%


Well it takes six arguments. Let's see what they are when we call \newbox\foo.

• #1 is \box
• #2 is \ifnum\allocationnumber...\fi
• #3 is \count14
• #4 is \insc@unt
• #5 is \float@count
• #6 is \foo

The last allocation number for a \box register is \count14 (this can be seen in source2e); so the first step is to increase it by one. Then

\e@ch@ck{\count14}{\ins@count}{\float@count}\box


is executed. I won't get into the details, but this chooses a new number based on already done allocations; one has to take into account that insertions and floats allocate box registers. Anyway, at the end of the process, \allocationnumber is set to the chosen integer value, (unless there is no room for a new box register, which is unlikely as there are 32768 of them; in this case an error will be raised.

In the normal case the next step is performed, that is

\global#2#6\allocationnumber


If the chosen number is less than 256, this becomes

\global\chardef\foo\allocationnumber


otherwise it becomes

\global\mathchardef\foo\allocationnumber


In either case, \foo becomes essentially equivalent to the allocated number.

When \box\foo is called, this will be the same as specifying the box register number (with the advantage we never need to know the precise number).

If you use the recommended LaTeX command, namely \newsavebox{\foo}, an initial step is performed: LaTeX checks whether \foo is not yet defined. In this case \newbox\foo is executed; otherwise an error is raised and the definition is ignored.

This is quite different from other register allocations. For instance, if you do \newlength\foo, this eventually becomes

\skipdef\foo=<number>


where the number is determined in the same way as before. This allows to use \foo in all situations where TeX expects a length or a length register name.

TeX has no \boxdef command, because box registers are rather peculiar and one can use them in a variety of ways:

\box\foo
\copy\foo
\unhbox\foo
\unvbox\foo
\unhcopy\foo
\unvcopy\foo


and so a \boxdef token would be completely useless.

The other usage is \setbox\foo<box specification> by which a box register is populated. Reading the TeXbook or TeX by Topic about this is recommended.

• @campa Thanks, fixed Jan 13, 2020 at 8:36