OWA_PATTERN Package

The OWA_PATTERN package enables you to do sophisticated string manipulation using regular expressions. OWA_PATTERN provides the following three operations:

MATCH. This determines whether a regular expression exists in a string. This is a function that returns TRUE or FALSE.
AMATCH. This is a more sophisticated variation on MATCH that lets you specify where in the string the match has to occur. This is a function that returns as an integer the end of the location in the string where the regular expression was found. If the regular expression is not found, it returns 0.
CHANGE. This lets you replace the portion of the string that matched the regular expression with a new string. CHANGE can be either a procedure or a function. If a function, it returns the number of times the regular expression was found and replaced.

There are also operations that these operations use, but that you can also use directly. These are explained shortly.

The OWA_PATTERN operations all use the following three parameters:

line. This is the target to be examined for a match. Despite the name, it can be more than one line of text or can be a PL/SQL table(see PL/SQL Tables) of type multi_line
pat. This is the regular expression the functions attempts to locate in line. This regular expression uses the special tokens explained shortly. Note: in CHANGE, this is called from_str.
flags. These are arguments that control how the search is to be performed.

Some of the operations take additional parameters as well.

Regular Expressions

You specify a regular expression by creating the string you want to match interspersed with various wildcard tokens and quantifiers. The wildcard tokens all match something other than themselves, and the quantifiers modify the meaning of tokens or of literals by specifying such things as how often each is to be applied.

Tokens

The wildcard tokens that are supported are as follows:

^ Matches newline or the beginning of the target.

$ Matches newline or the end of the target.

\n Matches newline.

. Matches any character except newline.

\t Matches tab.

\d Matches digits [0-9]

\D Matches non-digits [not 0-9]

\w Matches word characters (alphanumeric) [0-9, a-z, A-Z or _]

\W Matches non-word characters [not 0-9, a-z, A-Z or _]

\s Matches whitespace characters [blank, tab, or newline]

\S Matches non-whitespace characters [not blank, tab, or newline]

\b Matches "word" boundaries (between \w and \W)

\x<HEX> Matches the value in the current character set of the two hexidecimal digits.

\<OCT> Matches the value in the current character set of the two or three octal digits.

\ Followed by any character not covered by another case matches that character.

& Applies only to CHANGE. This causes the string that matched the regular expression to be included in the string that replaces it. This differs from the other tokens in that it specifies how a target is changed rather than how it is matched. This is explained further under CHANGE.

Quantifiers

Any of the above tokens except & can have its meaning extended by any of the following quantifiers. You can also apply these quantifiers to literals.

? 0 or 1 occurrence(s)

* 0 or more occurrences

+ 1 or more occurrence(s)

{n} Exactly n occurrences

(n,} At least n occurrences

{n,m} At least n, but not more than m, occurrences

Flags

In addition to targets and regular expressions, the OWA_PATTERN functions and procedures can use flags to affect how they are interpreted. The recognized flags are as follows:

i This indicates a case-insensitive search.

g This applies only to CHANGE. It indicates a global replace. That is to say, all portions of the target that match the regular expression are replaced.

Datatypes

The following special datatype is used by OWA_PATTERN.

pattern

A PL/SQL table (see PL/SQL Tables) of 4 byte VARCHAR2 strings, indexed by BINARY INTEGER. This is an alternative way to store your regular expression than in simple VARCHAR2 strings. The advantages of this is that you can use a pattern as both an input and output parameter. Thus, you can pass the same regular expression to several subsequent OWA_PATTERN function calls, and it only has to be parsed once.

Note: The following datatypes are used by OWA_PATTERN, but are part of the OWA_TEXT package. For information on these, see the section on OWA_TEXT: owa_text.vc_array, owa_text.multi_line, owa_text.int_array, owa_text.row_list.