1%-*-mode:latex-*-
2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3%
4% Copyright (C) 1996-2005 Jason Evans <jasone@canonware.com>.
5% All rights reserved.
6%
7% Redistribution and use in source and binary forms, with or without
8% modification, are permitted provided that the following conditions
9% are met:
10% 1. Redistributions of source code must retain the above copyright
11%    notice(s), this list of conditions and the following disclaimer
12%    unmodified other than the allowable addition of one or more
13%    copyright notices.
14% 2. Redistributions in binary form must reproduce the above copyright
15%    notice(s), this list of conditions and the following disclaimer in
16%    the documentation and/or other materials provided with the
17%    distribution.
18%
19% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
20% EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21% IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
22% PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
23% LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
24% CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
25% SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
26% BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
27% WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
28% OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
29% EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30%
31%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
32%
33% Version: Onyx 5.1.2
34%
35% nxo_string portion of Onyx Manual.
36%
37%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
38
39\subsection{nxo\_string}
40\label{nxo_string}
41\index{nxo_string@\classname{nxo\_string}{}}
42
43The \classname{nxo\_string} class is a subclass of the \classname{nxo} class.
44Strings are not `{\bs}0'-terminated, mainly since substrings are references to
45other strings, and the termination character wouldn't be consistently useful.
46\cfunc{nxo\_string\_cstring}{} is useful for creating `{\bs}0'-terminated copies
47of strings for situations where other C functions expect terminated strings.
48
49\subsubsection{API}
50\begin{capi}
51\label{nxo_string_new}
52\index{nxo_string_new@\cfunc{nxo\_string\_new}{}}
53\citem{\cfunc[void]{nxo\_string\_new}{cw\_nxo\_t *a\_nxo, bool
54a\_locking, uint32\_t a\_len}}
55	\begin{capilist}
56	\item[Input(s): ]
57		\begin{description}\item[]
58		\item[a\_nxo: ]
59			Pointer to a string \classname{nxo}.
60		\item[a\_locking: ]
61			Implicit locking mode.
62		\item[a\_len: ]
63			Length in bytes of string to create.
64		\end{description}
65	\item[Output(s): ] None.
66	\item[Exception(s): ]
67		\begin{description}\item[]
68		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
69		\end{description}
70	\item[Description: ]
71		Constructor.
72	\end{capilist}
73\label{nxo_string_substring_new}
74\index{nxo_string_substring_new@\cfunc{nxo\_string\_substring\_new}{}}
75\citem{\cfunc[void]{nxo\_string\_substring\_new}{cw\_nxo\_t *a\_nxo, cw\_nxo\_t
76*a\_string, uint32\_t a\_offset, uint32\_t a\_len}}
77	\begin{capilist}
78	\item[Input(s): ]
79		\begin{description}\item[]
80		\item[a\_nxo: ]
81			Pointer to a string \classname{nxo}.
82		\item[a\_string: ]
83			Pointer to a string \classname{nxo} to create a
84			substring of.
85		\item[a\_offset: ]
86			Offset into \cvar{a\_string}.
87		\item[a\_len: ]
88			Length in bytes of substring to create.
89		\end{description}
90	\item[Output(s): ] None.
91	\item[Exception(s): ]
92		\begin{description}\item[]
93		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
94		\end{description}
95	\item[Description: ]
96		Substring constructor.
97	\end{capilist}
98\label{nxo_string_copy}
99\index{nxo_string_copy@\cfunc{nxo\_string\_copy}{}}
100\citem{\cfunc[void]{nxo\_string\_copy}{cw\_nxo\_t *a\_to, cw\_nxo\_t *a\_from}}
101	\begin{capilist}
102	\item[Input(s): ]
103		\begin{description}\item[]
104		\item[a\_to: ]
105			Pointer to a string \classname{nxo}.
106		\item[a\_from: ]
107			Pointer to a string \classname{nxo}.
108		\end{description}
109	\item[Output(s): ] None.
110	\item[Exception(s): ] None.
111	\item[Description: ]
112		Copy the contents of \cvar{a\_from} to \cvar{a\_to}.  The length
113		of \cvar{a\_to} must be at least that of \cvar{a\_from}.
114	\end{capilist}
115\label{nxo_string_cstring}
116\index{nxo_string_cstring@\cfunc{nxo\_string\_cstring}{}}
117\citem{\cfunc[void]{nxo\_string\_cstring}{cw\_nxo\_t *a\_to, cw\_nxo\_t
118*a\_from, cw\_nxo\_t *a\_thread}}
119	\begin{capilist}
120	\item[Input(s): ]
121		\begin{description}\item[]
122		\item[a\_to: ]
123			Pointer to an \classname{nxo}.
124		\item[a\_from: ]
125			Pointer to a string or name \classname{nxo}.
126		\item[a\_thread: ]
127			Pointer to a thread \classname{nxo}.
128		\end{description}
129	\item[Output(s): ] None.
130	\item[Exception(s): ]
131		\begin{description}\item[]
132		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
133		\end{description}
134	\item[Description: ]
135		Create a copy of \cvar{a\_from}, but append a `{\bs}0' character
136		to make it usable in calls to typical C functions that expect a
137		terminated string.
138	\end{capilist}
139\label{nxo_string_len_get}
140\index{nxo_string_len_get@\cfunc{nxo\_string\_len\_get}{}}
141\citem{\cfunc[uint32\_t]{nxo\_string\_len\_get}{const cw\_nxo\_t *a\_nxo}}
142	\begin{capilist}
143	\item[Input(s): ]
144		\begin{description}\item[]
145		\item[a\_nxo: ]
146			Pointer to a string \classname{nxo}.
147		\end{description}
148	\item[Output(s): ]
149		\begin{description}\item[]
150		\item[retval: ]
151			Length of \cvar{a\_nxo}.
152		\end{description}
153	\item[Exception(s): ] None.
154	\item[Description: ]
155		Return the length of \cvar{a\_nxo}.
156	\end{capilist}
157\label{nxo_string_el_get}
158\index{nxo_string_el_get@\cfunc{nxo\_string\_el\_get}{}}
159\citem{\cfunc[void]{nxo\_string\_el\_get}{const cw\_nxo\_t *a\_nxo, cw\_nxoi\_t
160a\_offset, char *r\_el}}
161	\begin{capilist}
162	\item[Input(s): ]
163		\begin{description}\item[]
164		\item[a\_nxo: ]
165			Pointer to a string \classname{nxo}.
166		\item[a\_offset: ]
167			Offset of character to get.
168		\item[r\_el: ]
169			Pointer to space to copy a character to.
170		\end{description}
171	\item[Output(s): ]
172		\begin{description}\item[]
173		\item[*r\_el: ]
174			A copy of the character of \cvar{a\_nxo} at offset
175			\cvar{a\_offset}.
176		\end{description}
177	\item[Exception(s): ] None.
178	\item[Description: ]
179		Get a copy of the character of \cvar{a\_nxo} at offset
180		\cvar{a\_offset}.
181	\end{capilist}
182\label{nxo_string_el_set}
183\index{nxo_string_el_set@\cfunc{nxo\_string\_el\_set}{}}
184\citem{\cfunc[void]{nxo\_string\_el\_set}{cw\_nxo\_t *a\_nxo, char
185a\_el, cw\_nxoi\_t a\_offset}}
186	\begin{capilist}
187	\item[Input(s): ]
188		\begin{description}\item[]
189		\item[a\_nxo: ]
190			Pointer to a string \classname{nxo}.
191		\item[a\_el: ]
192			A character.
193		\item[a\_offset: ]
194			Offset of character in \cvar{a\_nxo} to replace with
195			\cvar{a\_el}.
196		\end{description}
197	\item[Output(s): ] None.
198	\item[Exception(s): ] None.
199	\item[Description: ]
200		Copy \cvar{a\_el} into the element of \cvar{a\_nxo} at offset
201		\cvar{a\_offset}.
202	\end{capilist}
203\label{nxo_string_lock}
204\index{nxo_string_lock@\cfunc{nxo\_string\_lock}{}}
205\citem{\cfunc[void]{nxo\_string\_lock}{cw\_nxo\_t *a\_nxo}}
206	\begin{capilist}
207	\item[Input(s): ]
208		\begin{description}\item[]
209		\item[a\_nxo: ]
210			Pointer to a string \classname{nxo}.
211		\end{description}
212	\item[Output(s): ] None.
213	\item[Exception(s): ] None.
214	\item[Description: ]
215		If implicit locking is activated for \cvar{a\_nxo}, lock it.
216	\end{capilist}
217\label{nxo_string_unlock}
218\index{nxo_string_unlock@\cfunc{nxo\_string\_unlock}{}}
219\citem{\cfunc[void]{nxo\_string\_unlock}{cw\_nxo\_t *a\_nxo}}
220	\begin{capilist}
221	\item[Input(s): ]
222		\begin{description}\item[]
223		\item[a\_nxo: ]
224			Pointer to a string \classname{nxo}.
225		\end{description}
226	\item[Output(s): ] None.
227	\item[Exception(s): ] None.
228	\item[Description: ]
229		If implicit locking is activated for \cvar{a\_nxo}, unlock it.
230	\end{capilist}
231\label{nxo_string_get}
232\index{nxo_string_get@\cfunc{nxo\_string\_get}{}}
233\citem{\cfunc[char *]{nxo\_string\_get}{const cw\_nxo\_t *a\_nxo}}
234	\begin{capilist}
235	\item[Input(s): ]
236		\begin{description}\item[]
237		\item[a\_nxo: ]
238			Pointer to a string \classname{nxo}.
239		\end{description}
240	\item[Output(s): ]
241		\begin{description}\item[]
242		\item[retval: ]
243			Pointer to the string internal to \cvar{a\_nxo}.
244		\end{description}
245	\item[Exception(s): ] None.
246	\item[Description: ]
247		Return a pointer to the string internal to \cvar{a\_nxo}.
248	\end{capilist}
249\label{nxo_string_set}
250\index{nxo_string_set@\cfunc{nxo\_string\_set}{}}
251\citem{\cfunc[void]{nxo\_string\_set}{cw\_nxo\_t *a\_nxo, uint32\_t
252a\_offset, const char *a\_str, uint32\_t a\_len}}
253	\begin{capilist}
254	\item[Input(s): ]
255		\begin{description}\item[]
256		\item[a\_nxo: ]
257			Pointer to a string \classname{nxo}.
258		\item[a\_offset: ]
259			Offset into \cvar{a\_nxo} to replace.
260		\item[a\_str: ]
261			String to replace a range of \cvar{a\_nxo} with.
262		\item[a\_len: ]
263			Length in bytes of \cvar{a\_str}.
264		\end{description}
265	\item[Output(s): ] None.
266	\item[Exception(s): ] None.
267	\item[Description: ]
268		Replace \cvar{a\_len} bytes of \cvar{a\_nxo} at offset
269		\cvar{a\_offset} with \cvar{a\_str}.
270	\end{capilist}
271\end{capi}
272