next up previous contents index
Next: 4.10.32 nxo_regsub Up: 4.10 Classes Previous: 4.10.30 nxo_real   Contents   Index

Subsections


4.10.31 nxo_regex

The nxo_regex class is a subclass of the nxo class.

4.10.31.1 API

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):

Input(s):
a_nxo:
Pointer to a regex nxo.
a_pattern:
Pointer to a string that specifies a regular expression.
a_len:
Length of a_pattern.
a_cont:
Continue where last successful match ended if true.
a_global:
Continue where last match ended if true.
a_insensitive:
Match with case insensitivity if true.
a_multiline:
Treat input as a multi-line string if true.
a_singleline:
Treat input as a single line, so that the dot metacharacter matches any character, including a newline.
Output(s):
retval:
NXN_ZERO:
Success.
NXN_regexerror:
Regular expression error.
Exception(s):
CW_ONYXX_OOM.
Description:
Constructor.
void nxo_regex_match(cw_nxo_t *a_nxo, cw_nxo_t *a_thread, cw_nxo_t *a_input, bool *r_match):

Input(s):
a_nxo:
Pointer to a regex nxo.
a_thread:
Pointer to a thread nxo.
a_input:
Pointer to a string nxo.
r_match:
Pointer to a bool.
Output(s):
*r_match:
true:
Match successful.
false:
No match found.
Exception(s):
CW_ONYXX_OOM.
Description:
Look in a_input for a match to the regex pointed to by a_nxo. As a side effect, set the thread's match cache, which can be queried via nxo_regex_submatch().
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):

Input(s):
a_thread:
Pointer to a thread nxo.
a_pattern:
Pointer to a string that specifies a regular expression.
a_len:
Length of a_pattern.
a_cont:
Continue where last successful match ended if true.
a_global:
Continue where last match ended if true.
a_insensitive:
Match with case insensitivity if true.
a_multiline:
Treat input as a multi-line string if true.
a_singleline:
Treat input as a single line, so that the dot metacharacter matches any character, including a newline.
a_input:
Pointer to a string nxo.
r_match:
Pointer to a bool.
Output(s):
retval:
NXN_ZERO:
Success.
NXN_regexerror:
Regular expression error.
*r_match:
true:
Match successful.
false:
No match found.
Exception(s):
CW_ONYXX_OOM.
Description:
Look in a_input for a match to the regular expression specified by a_pattern, a_len, a_cont, a_global, a_insensitive, a_multiline, and a_singleline. As a side effect, set the thread's match cache, which can be queried via nxo_regex_submatch().

This function combines nxo_regex_new() and 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.

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):

Input(s):
a_nxo:
Pointer to a regex nxo.
a_thread:
Pointer to a thread nxo.
a_limit:
Maximum number of substrings to split a_input into. 0 is treated as infinity.
a_input:
Pointer to a string nxo.
r_array:
Pointer to an nxo to dup an array of substrings to.
Output(s):
*r_array:
An array of substrings.
Exception(s):
CW_ONYXX_OOM.
Description:
Use the regex pointed to by a_nxo to find matches in 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 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.

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):

Input(s):
a_thread:
Pointer to a thread nxo.
a_pattern:
Pointer to a string that specifies a regular expression.
a_len:
Length of a_pattern.
a_insensitive:
Match with case insensitivity if true.
a_multiline:
Treat input as a multi-line string if true.
a_singleline:
Treat input as a single line, so that the dot metacharacter matches any character, including a newline.
a_limit:
Maximum number of substrings to split a_input into. 0 is treated as infinity.
a_input:
Pointer to a string nxo.
r_array:
Pointer to an nxo to dup an array of substrings to.
Output(s):
retval:
NXN_ZERO:
Success.
NXN_regexerror:
Regular expression error.
*r_array:
An array of substrings.
Exception(s):
CW_ONYXX_OOM.
Description:
Use the regex specified by a_pattern, a_len, a_insensitive, a_multiline, and a_singleline to find matches in 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 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 nxo_regex_nex() and 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.

void nxo_regex_submatch(cw_nxo_t *a_thread, uint32_t a_capture, cw_nxo_t *r_match):

Input(s):
a_thread:
Pointer to a thread nxo.
a_capture:
Index of captured subpattern to create a substring for:
0:
Get substring of input text that matched the regular expression.
>0:
Get substring of input text that matched the specified capturing subpattern.
r_match:
Pointer to an nxo to dup a substring reference to.
Output(s):
*r_match:
An nxo:
null:
Subpattern not matched.
string:
A substring of text that corresponds to the captured subpattern specified by a_capture.
Exception(s):
CW_ONYXX_OOM.
Description:
Create a substring using the calling thread's match cache that corresponds to capturing subpattern a_capture.

Each thread has a match cache that is used by various regex and 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.


next up previous contents index
Next: 4.10.32 nxo_regsub Up: 4.10 Classes Previous: 4.10.30 nxo_real   Contents   Index
Jason Evans 2005-03-16