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