ReplaceEx Method (REGEX)

The ReplaceEx method is used to replace targeted matching substrings using the stored regular expression in the associated PL/B REGEX object. This method uses the following format:

Where:

label

Optional. A Program Execution Label.

object

Required. A REGEX object previously declared.

return

Optional. A Character String Variable that returns the text with the requested replacement operation applied.

text

Required. A Character String Variable or literal that specifies the text to examine.

value

Required. A Character String Variable or literal that specifies the replacement text.

options

Optional. A decimal number or Numeric Variable that has a bit mask value described below.

start

Optional. A decimal number or Numeric Variable that is a one based start position.

occurs

Optional. A decimal number or Numeric Variable that is a occurrence selector.

flags

Optional. A Character String Variable or literal that specifies text flags.

Flags Affected: EOS, OVER, ZERO

Notes:

1. The EOS flag is set if the returned data string is larger than the DIM variable used to receive the data.

2. The OVER and ZERO Condition Flags are always cleared.

3. The {text} parameter contains the character string to be searched.

4. The search pattern used is the currently compiled pattern.

5. The {value} parameter contains the replacement text.

6. The {value} parameter may be empty to remove the first matched substring.

7. The {value} parameter replacement text supports \0, \1..\9, $0, $1..$9, ${n}, $$, \&, \\ and & .

8. The {return} value is the {text} parameter with the requested replacement operation applied.

9. A zero-length match counts as a match.

10. If no match is found, the original {text} parameter is returned unchanged.

11. If no matches are found the GetMatch method will return an empty string.

12. If a match is found the GetMatch method will return the replaced substring.

13. The {options} bit mask values found in plbmeth.inc are defined as follows:

 

Equate	Value	Description
$REGEX_OPT_NOCASE	1	Case-insensitive (ASCII A-Z only)
$REGEX_OPT_MULTILINE	8	^ and $ also match at line breaks
$REGEX_OPT_DOTALL	16	. also matches CR and LF
$REGEX_OPT_NOTEMPTY	32	Reject empty (zero-length) matches

14. The {options} given to Compile method also apply.

15. Characters before {start} parameter are copied unchanged.

16. If the {start} parameter is zero, it is treated as one.

17. If the {start} parameter is beyond the end of {text} parameter, the original {text} parameter is returned..

18. The {occurs} parameter defaults to zero and acts as follows:

 

Value	Replaces
0	all matches from the {start} parameter onward.
1	the first match from the {start} parameter onward.
n	only the nth match from the {start} parameter onward.

 

19. The {flags} parameter defaults to a empty string and acts as follows:

 

Flag	Match is
i	case-insensitive
c	case-sensitive
m	multiline anchors on
n	. also matches CR and LF
s	. also matches CR and LF

 

20. Unknown {flags} parameter characters are ignored.

Example 1:

      RegEx1.Compile Giving N Using "Alice"

      RegEx1.ReplaceEx Giving S Using "Alice Smith and Alice Jones","Bob",0,1,2

      RegEx1.Compile Giving N Using "\d\d\d"

      RegEx1.ReplaceEx Giving S Using "abc123def456","[$0]",0,1,0

      RegEx1.Compile Giving N Using "<br>"

      RegEx1.ReplaceEx Giving S Using "abc<BR>def"," ",0,1,0,"im"

See Also: Method Syntax, REGEX, Regular Expression Support