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

\subsection{nxo\_regsub}
\label{nxo_regsub}
\index{nxo_regsub@\classname{nxo\_regsub}{}}

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

\subsubsection{API}
\begin{capi}
\label{nxo_regsub_new}
\index{nxo_regsub_new@\cfunc{nxo\_regsub\_new}{}}
\citem{\cfunc[cw\_nxn\_t]{nxo\_regsub\_new}{cw\_nxo\_t *a\_nxo, const
char  *a\_pattern, uint32\_t a\_plen, bool a\_global,
bool a\_insensitive, bool a\_multiline, bool a\_singleline,
const char *a\_template, uint32\_t a\_tlen}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a regsub \classname{nxo}.
		\item[a\_pattern: ]
			Pointer to a string that specifies a regular expression.
		\item[a\_plen: ]
			Length of \cvar{a\_pattern}.
		\item[a\_global: ]
			Substitute as many times as possible if true.
		\item[a\_insensitive: ]
			Match with case insensitivity if true.
		\item[a\_multiline: ]
			Treat input as a multi-line string if true.
		\item[a\_singleline: ]
			Treat input as a single line, so that the dot
			metacharacter matches any character, including a
			newline.
		\item[a\_template: ]
			Pointer to a string that specifies a substitution
			template.
		\item[a\_tlen: ]
			Length of \cvar{a\_template}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			\begin{description}\item[]
			\item[NXN\_ZERO: ] Success.
			\item[NXN\_regexerror: ] Regular expression error.
			\end{description}
		\end{description}
	\item[Exception(s): ]
		\begin{description}\item[]
		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
		\end{description}
	\item[Description: ]
		Constructor.
	\end{capilist}
\label{nxo_regsub_subst}
\index{nxo_regsub_subst@\cfunc{nxo\_regsub\_subst}{}}
\citem{\cfunc[void]{nxo\_regsub\_subst}{cw\_nxo\_t *a\_nxo, cw\_nxo\_t
*a\_thread, cw\_nxo\_t *a\_input, cw\_nxo\_t *r\_output, uint32\_t
*r\_count}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a regsub \classname{nxo}.
		\item[a\_thread: ]
			Pointer to a thread \classname{nxo}.
		\item[a\_input: ]
			Pointer to a string \classname{nxo}.
		\item[r\_output: ]
			Pointer to an \classname{nxo} to dup a string reference
			to.
		\item[r\_count: ]
			Pointer to a \ctype{uint32\_t}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[*r\_output: ]
			A string that was created by substituting regular
			expression matches according to a substitution template.
		\item[*r\_count: ]
			Number of substitutions made.  If 0 substitutions were
			made, \cvar{*r\_output} is a duplicate of
			\cvar{a\_input}, rather than a copy.
		\end{description}
	\item[Exception(s): ]
		\begin{description}\item[]
		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
		\end{description}
	\item[Description: ]
		Create a string by substituting according to \cvar{a\_template}
		for each substring within \oparg{input} that matches a regular
		expression.

		As a side effect, set the thread's match cache, which can be
		queried via \cfunc{nxo\_regex\_submatch}{}.
	\end{capilist}
\label{nxo_regsub_nonew_subst}
\index{nxo_regsub_nonew_subst@\cfunc{nxo\_regsub\_nonew\_subst}{}}
\citem{\cfunc[cw\_nxn\_t]{nxo\_regsub\_nonew\_subst}{cw\_nxo\_t *a\_thread,
const char *a\_pattern, uint32\_t a\_plen, bool a\_global,
bool a\_insensitive, bool a\_multiline, bool a\_singleline,
const char *a\_template, uint32\_t a\_tlen, cw\_nxo\_t *a\_input,
cw\_nxo\_t *r\_output, uint32\_t *r\_count}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_thread: ]
			Pointer to a thread \classname{nxo}.
		\item[a\_pattern: ]
			Pointer to a string that specifies a regular expression.
		\item[a\_plen: ]
			Length of \cvar{a\_pattern}.
		\item[a\_global: ]
			Substitute as many times as possible if true.
		\item[a\_insensitive: ]
			Match with case insensitivity if true.
		\item[a\_multiline: ]
			Treat input as a multi-line string if true.
		\item[a\_singleline: ]
			Treat input as a single line, so that the dot
			metacharacter matches any character, including a
			newline.
		\item[a\_template: ]
			Pointer to a string that specifies a substitution
			template.
		\item[a\_tlen: ]
			Length of \cvar{a\_template}.
		\item[a\_input: ]
			Pointer to a string \classname{nxo}.
		\item[r\_output: ]
			Pointer to an \classname{nxo} to dup a string reference
			to.
		\item[r\_count: ]
			Pointer to a \ctype{uint32\_t}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			\begin{description}\item[]
			\item[NXN\_ZERO: ] Success.
			\item[NXN\_regexerror: ] Regular expression error.
			\end{description}
		\item[*r\_output: ]
			A string that was created by substituting regular
			expression matches (specified by \cvar{a\_pattern})
			according to \cvar{a\_template}.
		\item[*r\_count: ]
			Number of substitutions made.  If 0 substitutions were
			made, \cvar{*r\_output} is a duplicate of
			\cvar{a\_input}, rather than a copy.
		\end{description}
	\item[Exception(s): ]
		\begin{description}\item[]
		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
		\end{description}
	\item[Description: ]
		Create a string by substituting according to \cvar{a\_template}
		for each substring within \oparg{input} that matches a regular
		expression.

		As a side effect, set the thread's match cache, which can be
		queried via \cfunc{nxo\_regex\_submatch}{}.

		This function combines \cfunc{nxo\_regsub\_new}{} and
		\cfunc{nxo\_regsub\_subst}{} in such a way that no Onyx regsub
		object is created, thus providing a more efficient way of doing
		a one-off subst.
	\end{capilist}
\end{capi}
