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

\subsection{nxo\_regex}
\label{nxo_regex}
\index{nxo_regex@\classname{nxo\_regex}{}}

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

\subsubsection{API}
\begin{capi}
\label{nxo_regex_new}
\index{nxo_regex_new@\cfunc{nxo\_regex\_new}{}}
\citem{\cfunc[cw\_nxn\_t]{nxo\_regex\_new}{cw\_nxo\_t *a\_nxo, const
char *a\_pattern, uint32\_t a\_len, bool a\_cont, bool
a\_global, bool a\_insensitive, bool a\_multiline, bool
a\_singleline}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a regex \classname{nxo}.
		\item[a\_pattern: ]
			Pointer to a string that specifies a regular expression.
		\item[a\_len: ]
			Length of \cvar{a\_pattern}.
		\item[a\_cont: ]
			Continue where last successful match ended if true.
		\item[a\_global: ]
			Continue where last match ended 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.
		\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_regex_match}
\index{nxo_regex_match@\cfunc{nxo\_regex\_match}{}}
\citem{\cfunc[void]{nxo\_regex\_match}{cw\_nxo\_t *a\_nxo, cw\_nxo\_t
*a\_thread, cw\_nxo\_t *a\_input, bool *r\_match}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a regex \classname{nxo}.
		\item[a\_thread: ]
			Pointer to a thread \classname{nxo}.
		\item[a\_input: ]
			Pointer to a string \classname{nxo}.
		\item[r\_match: ]
			Pointer to a \ctype{bool}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[*r\_match: ]
			\begin{description}\item[]
			\item[true: ] Match successful.
			\item[false: ] No match found.
			\end{description}
		\end{description}
	\item[Exception(s): ]
		\begin{description}\item[]
		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
		\end{description}
	\item[Description: ]
		Look in \cvar{a\_input} for a match to the regex pointed to by
		\cvar{a\_nxo}.  As a side effect, set the thread's match cache,
		which can be queried via \cfunc{nxo\_regex\_submatch}{}.
	\end{capilist}
\label{nxo_regex_nonew_match}
\index{nxo_regex_nonew_match@\cfunc{nxo\_regex\_nonew\_match}{}}
\citem{\cfunc[cw\_nxn\_t]{nxo\_regex\_nonew\_match}{cw\_nxo\_t *a\_thread, const
char *a\_pattern, uint32\_t a\_len, bool a\_cont, bool
a\_global, bool a\_insensitive, bool a\_multiline, bool
a\_singleline, cw\_nxo\_t *a\_input, bool *r\_match}}
	\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\_len: ]
			Length of \cvar{a\_pattern}.
		\item[a\_cont: ]
			Continue where last successful match ended if true.
		\item[a\_global: ]
			Continue where last match ended 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\_input: ]
			Pointer to a string \classname{nxo}.
		\item[r\_match: ]
			Pointer to a \ctype{bool}.
		\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\_match: ]
			\begin{description}\item[]
			\item[true: ] Match successful.
			\item[false: ] No match found.
			\end{description}
		\end{description}
	\item[Exception(s): ]
		\begin{description}\item[]
		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
		\end{description}
	\item[Description: ]
		Look in \cvar{a\_input} for a match to the regular expression
		specified by \cvar{a\_pattern}, \cvar{a\_len}, \cvar{a\_cont},
		\cvar{a\_global}, \cvar{a\_insensitive}, \cvar{a\_multiline},
		and \cvar{a\_singleline}.  As a side effect, set the thread's
		match cache, which can be queried via
		\cfunc{nxo\_regex\_submatch}{}.

		This function combines \cfunc{nxo\_regex\_new}{} and
		\cfunc{nxo\_regex\_match}{} in such a way that no Onyx regex
		object is created, thus providing a more efficient way of doing
		a one-off match.
	\end{capilist}
\label{nxo_regex_split}
\index{nxo_regex_split@\cfunc{nxo\_regex\_split}{}}
\citem{\cfunc[void]{nxo\_regex\_split}{cw\_nxo\_t *a\_nxo, cw\_nxo\_t
*a\_thread, uint32\_t a\_limit, cw\_nxo\_t *a\_input, cw\_nxo\_t *r\_array}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to a regex \classname{nxo}.
		\item[a\_thread: ]
			Pointer to a thread \classname{nxo}.
		\item[a\_limit: ]
			Maximum number of substrings to split \cvar{a\_input}
			into.  0 is treated as infinity.
		\item[a\_input: ]
			Pointer to a string \classname{nxo}.
		\item[r\_array: ]
			Pointer to an \classname{nxo} to dup an array of
			substrings to.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[*r\_array: ] An array of substrings.
		\end{description}
	\item[Exception(s): ]
		\begin{description}\item[]
		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
		\end{description}
	\item[Description: ]
		Use the regex pointed to by \cvar{a\_nxo} to find matches in
		\cvar{a\_input} and create an array of substrings that contain
		the data between those matches.

		If there are capturing subpatterns in the regular expression,
		also create substrings for those capturing subpatterns and
		insert them into the substring array.

		As a special case, if the regular expression matches the empty
		string, split a single character.  This avoids an infinite
		loop.

		As a side effect, set the thread's match cache, which can be
		queried via \cfunc{nxo\_regex\_submatch}{}.  Keep in mind that
		this function can match multiple times in a single invocation,
		so only the last match is available in this way.
	\end{capilist}
\label{nxo_regex_nonew_split}
\index{nxo_regex_nonew_split@\cfunc{nxo\_regex\_nonew\_split}{}}
\citem{\cfunc[cw\_nxn\_t]{nxo\_regex\_nonew\_split}{cw\_nxo\_t *a\_thread, const
char *a\_pattern, uint32\_t a\_len, bool a\_insensitive,
bool a\_multiline, bool a\_singleline, uint32\_t a\_limit,
cw\_nxo\_t *a\_input, cw\_nxo\_t *r\_array}}
	\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\_len: ]
			Length of \cvar{a\_pattern}.
		\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\_limit: ]
			Maximum number of substrings to split \cvar{a\_input}
			into.  0 is treated as infinity.
		\item[a\_input: ]
			Pointer to a string \classname{nxo}.
		\item[r\_array: ]
			Pointer to an \classname{nxo} to dup an array of
			substrings to.
		\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\_array: ] An array of substrings.
		\end{description}
	\item[Exception(s): ]
		\begin{description}\item[]
		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
		\end{description}
	\item[Description: ]
		Use the regex specified by \cvar{a\_pattern}, \cvar{a\_len},
		\cvar{a\_insensitive}, \cvar{a\_multiline}, and
		\cvar{a\_singleline} to find matches in \cvar{a\_input} and
		create an array of substrings that contain the data between
		those matches.

		If there are capturing subpatterns in the regular expression,
		also create substrings for those capturing subpatterns and
		insert them into the substring array.

		As a special case, if the regular expression matches the empty
		string, split a single character.  This avoids an infinite
		loop.

		As a side effect, set the thread's match cache, which can be
		queried via \cfunc{nxo\_regex\_submatch}{}.  Keep in mind that
		this function can match multiple times in a single invocation,
		so only the last match is available in this way.

		This function combines \cfunc{nxo\_regex\_nex}{} and
		\cfunc{nxo\_regex\_split}{} in such a way that no Onyx regex
		object is created, thus providing a more efficient way of doing
		a one-off split.
	\end{capilist}
\label{nxo_regex_submatch}
\index{nxo_regex_submatch@\cfunc{nxo\_regex\_submatch}{}}
\citem{\cfunc[void]{nxo\_regex\_submatch}{cw\_nxo\_t  *a\_thread, uint32\_t
a\_capture, cw\_nxo\_t *r\_match}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_thread: ]
			Pointer to a thread \classname{nxo}.
		\item[a\_capture: ]
			Index of captured subpattern to create a substring for:
			\begin{description}\item[]
			\item[0: ]
				Get substring of input text that matched the
				regular expression.
			\item[{\gt}0: ]
				Get substring of input text that matched the
				specified capturing subpattern.
			\end{description}
		\item[r\_match: ]
			Pointer to an \classname{nxo} to dup a substring
			reference to.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[*r\_match: ]
			An \classname{nxo}:
			\begin{description}\item[]
			\item[null: ] Subpattern not matched.
			\item[string: ]
				A substring of text that corresponds to
				the captured subpattern specified by
				\cvar{a\_capture}.
			\end{description}
		\end{description}
	\item[Exception(s): ]
		\begin{description}\item[]
		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
		\end{description}
	\item[Description: ]
		Create a substring using the calling thread's match cache that
		corresponds to capturing subpattern \cvar{a\_capture}.

		Each thread has a match cache that is used by various
		\classname{regex} and \classname{regsub} functions.  That cache
		stores a reference to the string that was most recently matched
		against, as well as offsets and lengths of the match and
		capturing subpatterns.  Since creating substrings puts pressure
		on the garbage collector, substring creation is done lazily
		(i.e. when this function is called).  Normally, a program has
		little need to ask for the same substring twice, so the created
		substrings are not cached.  That means that if this function is
		called twice in succession with the same arguments, two
		different (but equivalent) substrings will be returned.
	\end{capilist}
\end{capi}
