%-*-mode:latex-*-
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Copyright (C) 1996-2004 Jason Evans <jasone@canonware.com>.
% All rights reserved.
% 
% Redistribution and use in source and binary forms, with or without
% modification, are permitted provided that the following conditions
% are met:
% 1. Redistributions of source code must retain the above copyright
%    notice(s), this list of conditions and the following disclaimer
%    unmodified other than the allowable addition of one or more
%    copyright notices.
% 2. Redistributions in binary form must reproduce the above copyright
%    notice(s), this list of conditions and the following disclaimer in
%    the documentation and/or other materials provided with the
%    distribution.
% 
% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
% EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
% IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
% PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
% LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
% CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
% SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
% BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
% WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
% OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
% EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Version: Onyx 5.1.1
%
% nxo_stack portion of Onyx Manual.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{nxo\_stack}
\label{nxo_stack}
\index{nxo_stack@\classname{nxo\_stack}{}}

The \classname{nxo\_stack} class is a subclass of the \classname{nxo} class.

\subsubsection{API}
\begin{capi}
\label{nxo_stack_new}
\index{nxo_stack_new@\cfunc{nxo\_stack\_new}{}}
\citem{\cfunc[void]{nxo\_stack\_new}{cw\_nxo\_t *a\_nxo, bool
a\_locking, uint32\_t a\_mincount}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a stack \classname{nxo}.
		\item[a\_locking: ]
			Implicit locking mode.
		\item[a\_mincount: ]
			Minimum size to allow the internal array to shrink to.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ]
		\begin{description}\item[]
		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
		\end{description}
	\item[Description: ]
		Constructor.
	\end{capilist}
\label{nxo_stack_copy}
\index{nxo_stack_copy@\cfunc{nxo\_stack\_copy}{}}
\citem{\cfunc[void]{nxo\_stack\_copy}{cw\_nxo\_t *a\_to, cw\_nxo\_t *a\_from}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_to: ]
			Pointer to a stack \classname{nxo}.
		\item[a\_from: ]
			Pointer to a stack \classname{nxo}.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ]
		\begin{description}\item[]
		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
		\end{description}
	\item[Description: ]
		Copy the objects in \cvar{a\_from} onto \cvar{a\_to}.
	\end{capilist}
\label{nxo_stack_count}
\index{nxo_stack_count@\cfunc{nxo\_stack\_count}{}}
\citem{\cfunc[uint32\_t]{nxo\_stack\_count}{cw\_nxo\_t *a\_nxo}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a stack \classname{nxo}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Number of objects on \cvar{a\_nxo}.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return the number of objects on \cvar{a\_nxo}.
	\end{capilist}
\label{nxo_stack_push}
\index{nxo_stack_push@\cfunc{nxo\_stack\_push}{}}
\citem{\cfunc[cw\_nxo\_t *]{nxo\_stack\_push}{cw\_nxo\_t *a\_nxo}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a stack \classname{nxo}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Pointer to a no \classname{nxo} that has been pushed
			onto \cvar{a\_nxo}.
		\end{description}
	\item[Exception(s): ]
		\begin{description}\item[]
		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
		\end{description}
	\item[Description: ]
		Push a no \classname{nxo} onto \cvar{a\_nxo} and return a
		pointer to it.
	\end{capilist}
\label{nxo_stack_bpush}
\index{nxo_stack_bpush@\cfunc{nxo\_stack\_bpush}{}}
\citem{\cfunc[cw\_nxo\_t *]{nxo\_stack\_bpush}{cw\_nxo\_t *a\_nxo}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a stack \classname{nxo}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Pointer to a no \classname{nxo} that has been pushed
			onto the bottom of \cvar{a\_nxo}.
		\end{description}
	\item[Exception(s): ]
		\begin{description}\item[]
		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
		\end{description}
	\item[Description: ]
		Push a no \classname{nxo} onto the bottom of \cvar{a\_nxo} and
		return a pointer to it.
	\end{capilist}
\label{nxo_stack_pop}
\index{nxo_stack_pop@\cfunc{nxo\_stack\_pop}{}}
\citem{\cfunc[bool]{nxo\_stack\_pop}{cw\_nxo\_t *a\_nxo}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a stack \classname{nxo}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			\begin{description}\item[]
			\item[false: ]
				Success.
			\item[true: ]
				Stack underflow.
			\end{description}
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Pop an object off of \cvar{a\_nxo}.
	\end{capilist}
\label{nxo_stack_bpop}
\index{nxo_stack_bpop@\cfunc{nxo\_stack\_bpop}{}}
\citem{\cfunc[bool]{nxo\_stack\_bpop}{cw\_nxo\_t *a\_nxo}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a stack \classname{nxo}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			\begin{description}\item[]
			\item[false: ]
				Success.
			\item[true: ]
				Stack underflow.
			\end{description}
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Pop an object off the bottom of \cvar{a\_nxo}.
	\end{capilist}
\label{nxo_stack_npop}
\index{nxo_stack_npop@\cfunc{nxo\_stack\_npop}{}}
\citem{\cfunc[bool]{nxo\_stack\_npop}{cw\_nxo\_t *a\_nxo, uint32\_t
a\_count}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a stack \classname{nxo}.
		\item[a\_count: ]
			Number of objects to pop off of \cvar{a\_nxo}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			\begin{description}\item[]
			\item[false: ]
				Success.
			\item[true: ]
				Stack underflow.
			\end{description}
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Pop \cvar{a\_count} objects off of \cvar{a\_nxo}.
	\end{capilist}
\label{nxo_stack_nbpop}
\index{nxo_stack_nbpop@\cfunc{nxo\_stack\_nbpop}{}}
\citem{\cfunc[bool]{nxo\_stack\_nbpop}{cw\_nxo\_t *a\_nxo, uint32\_t
a\_count}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a stack \classname{nxo}.
		\item[a\_count: ]
			Number of objects to pop off the bottom of
			\cvar{a\_nxo}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			\begin{description}\item[]
			\item[false: ]
				Success.
			\item[true: ]
				Stack underflow.
			\end{description}
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Pop \cvar{a\_count} objects off the bottom of \cvar{a\_nxo}.
	\end{capilist}
\label{nxo_stack_get}
\index{nxo_stack_get@\cfunc{nxo\_stack\_get}{}}
\citem{\cfunc[cw\_nxo\_t *]{nxo\_stack\_get}{const cw\_nxo\_t *a\_nxo}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a stack \classname{nxo}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			\begin{description}\item[]
			\item[non-NULL: ]
				Pointer to the top \classname{nxo} on
				\cvar{a\_nxo}.
			\item[NULL: ]
				Stack underflow.
			\end{description}
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return a pointer to the top \cvar{nxo} on \cvar{a\_nxo}.
	\end{capilist}
\label{nxo_stack_bget}
\index{nxo_stack_bget@\cfunc{nxo\_stack\_bget}{}}
\citem{\cfunc[cw\_nxo\_t *]{nxo\_stack\_bget}{const cw\_nxo\_t *a\_nxo}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a stack \classname{nxo}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			\begin{description}\item[]
			\item[non-NULL: ]
				Pointer to the bottom \classname{nxo} on
				\cvar{a\_nxo}.
			\item[NULL: ]
				Stack underflow.
			\end{description}
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return a pointer to the bottom \cvar{nxo} on \cvar{a\_nxo}.
	\end{capilist}
\label{nxo_stack_nget}
\index{nxo_stack_nget@\cfunc{nxo\_stack\_nget}{}}
\citem{\cfunc[cw\_nxo\_t *]{nxo\_stack\_nget}{const cw\_nxo\_t *a\_nxo,
uint32\_t a\_index}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a stack \classname{nxo}.
		\item[a\_index: ]
			Index of object in \cvar{a\_nxo} to return a pointer to.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			\begin{description}\item[]
			\item[non-NULL: ]
				Pointer to the \cvar{nxo} on \cvar{a\_nxo} at
				index \cvar{a\_index}.
			\item[NULL: ]
				Stack underflow.
			\end{description}
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return a pointer to the \cvar{nxo} on \cvar{a\_nxo} at index
		\cvar{a\_index}.
	\end{capilist}
\label{nxo_stack_nbget}
\index{nxo_stack_nbget@\cfunc{nxo\_stack\_nbget}{}}
\citem{\cfunc[cw\_nxo\_t *]{nxo\_stack\_nbget}{const cw\_nxo\_t *a\_nxo,
uint32\_t a\_index}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a stack \classname{nxo}.
		\item[a\_index: ]
			Index, counting from the bottom, of object in
			\cvar{a\_nxo} to return a pointer to.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			\begin{description}\item[]
			\item[non-NULL: ]
				Pointer to the \cvar{nxo} on \cvar{a\_nxo} at
				index \cvar{a\_index}, counting from the bottom.
			\item[NULL: ]
				Stack underflow.
			\end{description}
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return a pointer to the \cvar{nxo} on \cvar{a\_nxo} at index
		\cvar{a\_index}, counting from the bottom.
	\end{capilist}
\label{nxo_stack_exch}
\index{nxo_stack_exch@\cfunc{nxo\_stack\_exch}{}}
\citem{\cfunc[bool]{nxo\_stack\_exch}{cw\_nxo\_t *a\_nxo}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a stack \classname{nxo}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			\begin{description}\item[]
			\item[false: ]
				Success.
			\item[true: ]
				Stack underflow.
			\end{description}
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Exchange the top two objects on \cvar{a\_nxo}.
	\end{capilist}
\label{nxo_stack_rot}
\index{nxo_stack_rot@\cfunc{nxo\_stack\_rot}{}}
\citem{\cfunc[void]{nxo\_stack\_rot}{cw\_nxo\_t *a\_nxo, int32\_t
a\_amount}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a stack \classname{nxo}.
		\item[a\_amount: ]
			Amount to rotate upward.  A negative value rotates
			downward.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ] None.
	\item[Description: ]
		Rotate \cvar{a\_nxo} up by \cvar{a\_amount}.
	\end{capilist}
\label{nxo_stack_roll}
\index{nxo_stack_roll@\cfunc{nxo\_stack\_roll}{}}
\citem{\cfunc[bool]{nxo\_stack\_roll}{cw\_nxo\_t *a\_nxo, uint32\_t
a\_count, int32\_t a\_amount}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a stack \classname{nxo}.
		\item[a\_count: ]
			Number of objects in roll region.
		\item[a\_amount: ]
			Amount to roll upward.  A negative value rolls downward.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			\begin{description}\item[]
			\item[false: ]
				Success.
			\item[true: ]
				Stack underflow.
			\end{description}
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Roll the top \cvar{a\_count} objects on \cvar{a\_nxo} up by
		\cvar{a\_amount}.
	\end{capilist}
\end{capi}
