Exec
Prev Chapter 11. Regular Expression Methods from RegexSupport.g Next

Exec

Exec — applies a regular expression match to a subject string.

Synopsis

Regex.Exec(extra, subject, length, startoffset, options, substrings)

Arguments

extra

An instance of pcre_extra returned from Regex.Study, or nil.

subject

The subject string on which to apply the pattern. This may be either a string or a buffer. If the subject is a buffer it may contain NUL characters.

length

The length of the subject, in bytes. If length is -1, the length of the subject string is computed automatically .

startoffset

A byte offset into the subject specifying at which point to start.

options

Option flags - a bitwise OR of zero or more of these flags:

PCRE_ANCHORED
PCRE_NEWLINE_CR
PCRE_NEWLINE_LF
PCRE_NEWLINE_CRLF
PCRE_NEWLINE_ANYCRLF
PCRE_NEWLINE_ANY
PCRE_NOTBOL
PCRE_NOTEOL
PCRE_NOTEMPTY
PCRE_NOTEMPTY_ATSTART
PCRE_NO_START_OPTIMIZE
PCRE_NO_UTF8_CHECK
PCRE_PARTIAL_SOFT
PCRE_PARTIAL_HARD
substrings

An array into which the match substrings are copied. The substrings array cannot be nil. The match substrings will be written into the substrings array starting at position 0. If the array is not large enough to hold all of the substrings it will be automatically expanded.

Each element of the substrings array is itself an array of 3 elements:

[0] - the zero-based starting character of the match
[1] - the character position immediately after the match
[2] - the string that matched.

This will be returned as a buffer if the subject is a buffer, otherwise it will be a string.

The first element in the substrings array always contains the complete matching string within the subject. Each element after the first corresponds to a positional substring specified within the pattern.

Returns

On success, an array of match specifications as described in the substrings parameter (above). On failure, an error list with three elements:

  • car(errlist) = a numeric return code from the failing function

  • cadr(errlist) = a character position in the pattern where the error occurred, or 0.

  • caddr(errlist) = an error message, as a human-readable string

See Also

Match

Prev Up Next
Config Home pcrs_job.Exec