Oracle9i Application Server PL/SQL Web Toolkit Reference Release 1.0.2.2 Part Number A90101-01 |
|
The owa_pattern package in the PL/SQL Web Toolkit locates text patterns within strings and replaces the matched string with another string. Use regular expressions with the subprograms in this package.
Regular Expressions - this section describes the special characters, quantifiers, and flags used in forming regular expressions.
owa_pattern.amatch function - determines if a string contains the specified pattern. It lets you specify where in the string the match has to occur.
owa_pattern.change function and procedure - replaces a pattern within a string. If you call it as a function it returns the number of times the regular expression was found and replaced.
owa_pattern.getpat procedure - generates a pattern data type from a VARCHAR2 type.
owa_pattern.match function - determines if a string contains the specified pattern.
owa_pattern.pattern data type - data type to store regular expressions.
These subprograms are overloaded. That is, there are several versions of each, distinguished by the parameters they use. Specifically, there are six versions of MATCH, and four each of AMATCH and CHANGE. The subprograms use the following parameters:
Specify a regular expression by creating the string you want to match interspersed with various wildcard tokens and quantifiers.
Wildcard tokens match something other than themselves:
Any tokens except & can have their meaning extended by any of the following quantifiers. You can also apply these quantifiers to literals:
In addition to targets and regular expressions, the owa_pattern functions and procedures use flags to affect how they are interpreted.
This function specifies if a pattern occurs in a particular location in a string. There are four versions to this function:
Properties | Definitions |
---|---|
Syntax: |
owa_pattern.amatch( line in varchar2 from_loc in integer pat in varchar2 flags in varchar2 DEFAULT NULL) return integer; |
|
owa_pattern.amatch( line in varchar2 from_loc in integer pat in out pattern flags in varchar2 DEFAULT NULL) return integer; |
|
owa_pattern.amatch( line in varchar2 from_loc in integer pat in varchar2 backrefs out owa_text.vc_arr flags in varchar2 DEFAULT NULL) return integer; |
|
owa_pattern.amatch( line in varchar2 from_loc in integer pat in out pattern backrefs out owa_text.vc_arr flags in varchar2 DEFAULT NULL) return integer; |
Parameters: |
from_loc - the location (in number of characters) in line where the search is to begin. pat - the string to match. It can contain regular expressions. This can be either a VARCHAR2 or a pattern. If it is a pattern, the output value of this parameter is the pattern matched. backrefs - the text that is matched. Each token that is matched is placed in a cell in the owa_text.vc_arr data type PL/SQL table. flags - whether or not the search is case-sensitive. If the value of this parameter is "i", the search is case-insensitive. Otherwise the search is case-sensitive. |
Returns: |
The index of the character after the end of the match, counting from the beginning of line. If there was no match, the function returns |
This function or procedure searches and replaces a string or multi_line data type. If multiple overlapping strings match the regular expression, this function takes the longest match.
Properties | Definitions |
---|---|
Syntax: |
/* function */ owa_pattern.change( line in out varchar2 from_str in varchar2 to_str in varchar2 flags in varchar2 DEFAULT NULL) return integer; |
|
/* procedure */ owa_pattern.change( line in out varchar2 from_str in varchar2 to_str in varchar2 flags in varchar2 DEFAULT NULL); |
|
/* function */ owa_pattern.change( mline in out owa_text.multi_line from_str in varchar2 to_str in varchar2 flags in varchar2 DEFAULT NULL) return integer; |
|
/* procedure */ owa_pattern.change( mline in out owa_text.multi_line from_str in varchar2 to_str in varchar2 flags in varchar2 DEFAULT NULL); |
Parameters: |
line - the text to search in. The output value of this parameter is the altered string. mline - the text to search in. This is a owa_text.multi_line data type data type. The output value of this parameter is the altered string. from_str - the regular expression to replace. to_str - the substitution pattern.
flags - whether or not the search is case-sensitive, and whether or not changes are to be made globally. If " |
Returns: |
As a function, it returns the number of substitutions made. If the flag `g' is not used, this number can only be 0 or 1 and only the first match is replaced. The flag `g' specifies to replace all matches with the regular expression. |
Example: |
Example 1: owa_pattern.change('Cats in pajamas', 'C.+in', '& red ') The regular expression matches the substring `Cats in'. It then replaces this string with `& red'. The ampersand character (&) indicates `Cats in', since that's what matched the regular expression. Thus, this procedure replaces the string `Cats in pajamas' with 'Cats in red'. If you called this as a function instead of a procedure, the value it returns is 1, indicating that a single substitution has been made. Example 2: create or replace procedure test_pattern as theline VARCHAR2(256); num_found integer; begin theline := `what is the goal?'; num_found := owa_pattern.change(theline, `goal', `idea', `g'); htp.print(num_found); -- num_found is 1 htp.print(theline); -- theline is `what is the idea?' end; / show errors |
This procedure converts a VARCHAR2 string into a owa_pattern.pattern data type.
Properties | Definitions |
---|---|
Syntax: |
owa_pattern.getpat(arg in VARCHAR2, pat in out pattern); |
Parameters: |
pat - the owa_pattern.pattern data type initialized with arg. |
Returns: |
None. |
This function determines if a string contains the specified pattern. The pattern can contain regular expressions. If multiple overlapping strings can match the regular expression, this function takes the longest match.
The regular expression in this function can be either a VARCHAR2 or a owa_pattern.pattern data type. Create a owa_pattern.pattern data type from a string using the owa_pattern.getpat procedure.
Create a multi_line data type from a long string using the owa_text.stream2multi procedure. If a multi_line is used, the rlist parameter specifies a list of chunks where matches were found.
If the line is a string and not a multi_line, you can add an optional output parameter called backrefs. This parameter is a row_list that holds each string in the target that was matched by a sequence of tokens in the regular expression.
Properties | Definitions |
---|---|
Syntax: |
owa_pattern.match( line in varchar2 pat in varchar2 flags in varchar2 DEFAULT NULL) return boolean; |
|
owa_pattern.match( line in varchar2 pat in out pattern flags in varchar2 DEFAULT NULL) return boolean; |
|
owa_pattern.match( line in varchar2 pat in varchar2 backrefs out owa_text.vc_arr flags in varchar2 DEFAULT NULL) return boolean; |
|
owa_pattern.match( line in varchar2 pat in out pattern backrefs out owa_text.vc_arr flags in varchar2 DEFAULT NULL) return boolean; |
|
owa_pattern.match( mline in owa_text.multi_line pat in varchar2 rlist out owa_text.row_list flags in varchar2 DEFAULT NULL) return boolean; |
|
owa_pattern.match( mline in owa_text.multi_line pat in out pattern rlist out owa_text.row_list flags in varchar2 DEFAULT NULL) return boolean; |
Parameters: |
mline - the text to search in. This is a owa_text.multi_line data type data type. pat - the pattern to match. This is either a VARCHAR2 or a owa_pattern.pattern data type data type. It it is a pattern, the output value of this parameter is the pattern matched. backrefs - the text that is matched. Each token that is matched is placed in a cell in the owa_text.vc_arr data type PL/SQL table. This parameter is a row_list that holds each string in the target that was matched by a sequence of tokens in the regular expression. rlist - an output parameter containing a list of matches. flags - whether or not the search is case-sensitive. If the value of this parameter is "i", the search is case-insensitive. Otherwise the search is case-sensitive. |
Returns: |
TRUE if a match was found, FALSE otherwise. |
Examples: |
KAZOO is the target where it is searching for the
Therefore, this regular expression specifies that a matching target consists of boolean foundMatch; foundMatch := owa_pattern.match('KAZOO', 'zoo.*', 'i'); The following example searches for the string "goal" followed by any number of characters in sometext. If found, sometext VARCHAR2(256); pat VARCHAR2(256); sometext := 'what is the goal?' pat := 'goal.*'; if owa.pattern.match(sometext, pat) then htp.print(`Match found'); else htp.print(`Match not found'); end if; |
You can use a pattern as both an input and output parameter. Thus, you can pass the same regular expression to OWA_PATTERN function calls, and it only has to be parsed once.
Properties | Definitions |
---|---|
Syntax: |
owa_pattern.pattern - data type |
Returns: |
Not applicable. |
|
Copyright © 2001 Oracle Corporation. All Rights Reserved. |
|