%-*-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_dict portion of Onyx Manual.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{nxo\_dict}
\label{nxo_dict}
\index{nxo_dict@\classname{nxo\_dict}{}}

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

\subsubsection{API}
\begin{capi}
\label{nxo_dict_new}
\index{nxo_dict_new@\cfunc{nxo\_dict\_new}{}}
\citem{\cfunc[void]{nxo\_dict\_new}{cw\_nxo\_t *a\_nxo, bool a\_locking,
uint32\_t a\_dict\_size}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a dict \classname{nxo}.
		\item[a\_locking: ]
			Implicit locking mode.
		\item[a\_dict\_size: ]
			Initial number of slots.  Dictionaries dynamically grow
			and shrink as needed, but if the maximum size of
			\cvar{a\_nxo} is known, it should be specified here to
			save space.
		\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_dict_copy}
\index{nxo_dict_copy@\cfunc{nxo\_dict\_copy}{}}
\citem{\cfunc[]{nxo\_dict\_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 dict \classname{nxo}.
		\item[a\_from: ]
			Pointer to a dict \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: ]
		Do a deep copy (actual contents are copied) of \cvar{a\_from} to
		\cvar{a\_to}.
	\end{capilist}
\label{nxo_dict_def}
\index{nxo_dict_def@\cfunc{nxo\_dict\_def}{}}
\citem{\cfunc[void]{nxo\_dict\_def}{cw\_nxo\_t *a\_nxo, cw\_nxo\_t *a\_key,
cw\_nxo\_t *a\_val}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a dict \classname{nxo}.
		\item[a\_key: ]
			Pointer to an \classname{nxo}.
		\item[a\_val: ]
			Pointer to an \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: ]
		Define \cvar{a\_key} with value \cvar{a\_val} in \cvar{a\_nxo}.
	\end{capilist}
\label{nxo_dict_undef}
\index{nxo_dict_undef@\cfunc{nxo\_dict\_undef}{}}
\citem{\cfunc[void]{nxo\_dict\_undef}{cw\_nxo\_t *a\_nxo, cw\_nxo\_t *a\_key}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a dict \classname{nxo}.
		\item[a\_key: ]
			Pointer to an \classname{nxo}.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ] None.
	\item[Description: ]
		Undefine \cvar{a\_key} in \cvar{a\_nxo}, if defined.
	\end{capilist}
\label{nxo_dict_lookup}
\index{nxo_dict_lookup@\cfunc{nxo\_dict\_lookup}{}}
\citem{\cfunc[bool]{nxo\_dict\_lookup}{const cw\_nxo\_t *a\_nxo, const
cw\_nxo\_t *a\_key, cw\_nxo\_t *r\_nxo}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a dict \classname{nxo}.
		\item[a\_key: ]
			Pointer to an \classname{nxo}.
		\item[r\_nxo: ]
			Pointer to an \classname{nxo}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			\begin{description}\item[]
			\item[false: ]
				Success.
			\item[true: ]
				\cvar{a\_key} not found.
			\end{description}
		\item[r\_nxo: ]
			If \cvar{retval} is false, value associated with
			\cvar{a\_key} in \cvar{a\_nxo}, otherwise unmodified.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Find \cvar{a\_key} in \cvar{a\_nxo} and dup its associated value
		to \cvar{r\_nxo}.
	\end{capilist}
\label{nxo_dict_count}
\index{nxo_dict_count@\cfunc{nxo\_dict\_count}{}}
\citem{\cfunc[uint32\_t]{nxo\_dict\_count}{const cw\_nxo\_t *a\_nxo}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a dict \classname{nxo}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			The number of key/value pairs in \cvar{a\_nxo}.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return the number of key/value pairs in \cvar{a\_nxo}.
	\end{capilist}
\label{nxo_dict_iterate}
\index{nxo_dict_iterate@\cfunc{nxo\_dict\_iterate}{}}
\citem{\cfunc[void]{nxo\_dict\_iterate}{cw\_nxo\_t *a\_nxo, cw\_nxo\_t *r\_nxo}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a dict \classname{nxo}.
		\item[r\_nxo: ]
			Pointer to an \classname{nxo}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
			\begin{description}\item[]
			\item[false: ]
				Success.
			\item[true: ]
				\cvar{a\_nxo} is empty.
			\end{description}
		\item[r\_nxo: ]
			If \cvar{retval} is false, A key in \cvar{a\_nxo},
			otherwise unmodified.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Iteratively get a key in \cvar{a\_nxo}.  Each successive call to
		this function will get the next key, and wrap back around to the
		first key when all keys have been returned.
	\end{capilist}
\end{capi}
