%-*-mode:latex-*-
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Copyright (C) 1996-2005 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.2
%
% nxo_string portion of Onyx Manual.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{nxo\_string}
\label{nxo_string}
\index{nxo_string@\classname{nxo\_string}{}}

The \classname{nxo\_string} class is a subclass of the \classname{nxo} class.
Strings are not `{\bs}0'-terminated, mainly since substrings are references to
other strings, and the termination character wouldn't be consistently useful.
\cfunc{nxo\_string\_cstring}{} is useful for creating `{\bs}0'-terminated copies
of strings for situations where other C functions expect terminated strings.

\subsubsection{API}
\begin{capi}
\label{nxo_string_new}
\index{nxo_string_new@\cfunc{nxo\_string\_new}{}}
\citem{\cfunc[void]{nxo\_string\_new}{cw\_nxo\_t *a\_nxo, bool
a\_locking, uint32\_t a\_len}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a string \classname{nxo}.
		\item[a\_locking: ]
			Implicit locking mode.
		\item[a\_len: ]
			Length in bytes of string to create.
		\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_string_substring_new}
\index{nxo_string_substring_new@\cfunc{nxo\_string\_substring\_new}{}}
\citem{\cfunc[void]{nxo\_string\_substring\_new}{cw\_nxo\_t *a\_nxo, cw\_nxo\_t
*a\_string, uint32\_t a\_offset, uint32\_t a\_len}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a string \classname{nxo}.
		\item[a\_string: ]
			Pointer to a string \classname{nxo} to create a
			substring of.
		\item[a\_offset: ]
			Offset into \cvar{a\_string}.
		\item[a\_len: ]
			Length in bytes of substring to create.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ]
		\begin{description}\item[]
		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
		\end{description}
	\item[Description: ]
		Substring constructor.
	\end{capilist}
\label{nxo_string_copy}
\index{nxo_string_copy@\cfunc{nxo\_string\_copy}{}}
\citem{\cfunc[void]{nxo\_string\_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 string \classname{nxo}.
		\item[a\_from: ]
			Pointer to a string \classname{nxo}.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ] None.
	\item[Description: ]
		Copy the contents of \cvar{a\_from} to \cvar{a\_to}.  The length
		of \cvar{a\_to} must be at least that of \cvar{a\_from}.
	\end{capilist}
\label{nxo_string_cstring}
\index{nxo_string_cstring@\cfunc{nxo\_string\_cstring}{}}
\citem{\cfunc[void]{nxo\_string\_cstring}{cw\_nxo\_t *a\_to, cw\_nxo\_t
*a\_from, cw\_nxo\_t *a\_thread}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_to: ]
			Pointer to an \classname{nxo}.
		\item[a\_from: ]
			Pointer to a string or name \classname{nxo}.
		\item[a\_thread: ]
			Pointer to a thread \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: ]
		Create a copy of \cvar{a\_from}, but append a `{\bs}0' character
		to make it usable in calls to typical C functions that expect a
		terminated string.
	\end{capilist}
\label{nxo_string_len_get}
\index{nxo_string_len_get@\cfunc{nxo\_string\_len\_get}{}}
\citem{\cfunc[uint32\_t]{nxo\_string\_len\_get}{const cw\_nxo\_t *a\_nxo}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a string \classname{nxo}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Length of \cvar{a\_nxo}.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return the length of \cvar{a\_nxo}.
	\end{capilist}
\label{nxo_string_el_get}
\index{nxo_string_el_get@\cfunc{nxo\_string\_el\_get}{}}
\citem{\cfunc[void]{nxo\_string\_el\_get}{const cw\_nxo\_t *a\_nxo, cw\_nxoi\_t
a\_offset, char *r\_el}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a string \classname{nxo}.
		\item[a\_offset: ]
			Offset of character to get.
		\item[r\_el: ]
			Pointer to space to copy a character to.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[*r\_el: ]
			A copy of the character of \cvar{a\_nxo} at offset
			\cvar{a\_offset}.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Get a copy of the character of \cvar{a\_nxo} at offset
		\cvar{a\_offset}.
	\end{capilist}
\label{nxo_string_el_set}
\index{nxo_string_el_set@\cfunc{nxo\_string\_el\_set}{}}
\citem{\cfunc[void]{nxo\_string\_el\_set}{cw\_nxo\_t *a\_nxo, char
a\_el, cw\_nxoi\_t a\_offset}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a string \classname{nxo}.
		\item[a\_el: ]
			A character.
		\item[a\_offset: ]
			Offset of character in \cvar{a\_nxo} to replace with
			\cvar{a\_el}.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ] None.
	\item[Description: ]
		Copy \cvar{a\_el} into the element of \cvar{a\_nxo} at offset
		\cvar{a\_offset}.
	\end{capilist}
\label{nxo_string_lock}
\index{nxo_string_lock@\cfunc{nxo\_string\_lock}{}}
\citem{\cfunc[void]{nxo\_string\_lock}{cw\_nxo\_t *a\_nxo}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a string \classname{nxo}.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ] None.
	\item[Description: ]
		If implicit locking is activated for \cvar{a\_nxo}, lock it.
	\end{capilist}
\label{nxo_string_unlock}
\index{nxo_string_unlock@\cfunc{nxo\_string\_unlock}{}}
\citem{\cfunc[void]{nxo\_string\_unlock}{cw\_nxo\_t *a\_nxo}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a string \classname{nxo}.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ] None.
	\item[Description: ]
		If implicit locking is activated for \cvar{a\_nxo}, unlock it.
	\end{capilist}
\label{nxo_string_get}
\index{nxo_string_get@\cfunc{nxo\_string\_get}{}}
\citem{\cfunc[char *]{nxo\_string\_get}{const cw\_nxo\_t *a\_nxo}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a string \classname{nxo}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Pointer to the string internal to \cvar{a\_nxo}.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return a pointer to the string internal to \cvar{a\_nxo}.
	\end{capilist}
\label{nxo_string_set}
\index{nxo_string_set@\cfunc{nxo\_string\_set}{}}
\citem{\cfunc[void]{nxo\_string\_set}{cw\_nxo\_t *a\_nxo, uint32\_t
a\_offset, const char *a\_str, uint32\_t a\_len}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a string \classname{nxo}.
		\item[a\_offset: ]
			Offset into \cvar{a\_nxo} to replace.
		\item[a\_str: ]
			String to replace a range of \cvar{a\_nxo} with.
		\item[a\_len: ]
			Length in bytes of \cvar{a\_str}.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ] None.
	\item[Description: ]
		Replace \cvar{a\_len} bytes of \cvar{a\_nxo} at offset
		\cvar{a\_offset} with \cvar{a\_str}.
	\end{capilist}
\end{capi}