Siebel eScript Language Reference > Siebel eScript Commands >

RegExp Object Methods


The Siebel ST eScript engine does not support the following static methods of the RegExp object: RegExp.$n (including '$_' and '$&'), RegExp.input, RegExp.lastMatch, RegExp.lastParen, RegExp.leftContext, and RegExp.rightContext. The Siebel T engine does support these methods.

Both the Siebel ST and T eScript engines support the following methods that are documented in this section:

Throughout this section, regexp is used to represent a RegExp object instance.

RegExp compile() Method

This method changes the pattern and attributes to use with the current instance of a RegExp object.

Syntax

regexp.compile(pattern[, attributes])

Parameter
Description

pattern

A string with a new regular expression pattern to use with this RegExp object

attributes

A string with the new attributes for this RegExp object. If included, this string must contain one or more of the following characters or be an empty string "":

i - sets the ignoreCase property to true

g - sets the global property to true

m - sets the multiline property to true

Usage

This method allows use of a RegExp instance multiple times with changes to its characteristics.

Use the compile() method with a regular expression that is created with the constructor function, not the literal notation.

Example

var regobj = new RegExp("now");
// use this RegExp object
regobj.compile("r*t");
// use it some more
regobj.compile("t.+o", "ig");
// use it some more

See also

RegExp global Property

RegExp ignoreCase Property

RegExp multiline Property

RegExp source Property

RegExp exec() Method

This method returns an array of strings that are matches of the regular expression on the target string.

Syntax

regexp.exec(str)

Parameter
Description

str

A string on which to perform a regular expression match

Returns

This method returns an array with various elements (the matched strings that are found), and their property sets. The elements returned depend on the attributes of the regular expression. The method returns null if no match is found.

Usage

Of all the RegExp and String methods, RegExp exec() is one of the most powerful because it includes all information about each match in its returned array.

When exec() is executed without the global attribute, "g", being set on the RegExp instance, and a match is found, then:

  • Element 0 of the returned array is the first text in the string that matches the primary RegExp pattern.
  • Element 1 is the text matched by the first subpattern (in parentheses) of the RegExp instance.
  • Element 2 is the text matched by the second subpattern of the RegExp instance, and so forth.

These elements and their numbers correspond to groups in regular expression patterns and replacement expressions.

The returned array includes the following properties:

  • The length property is the number of text matches in the returned array.
  • The index property is the start position of the first text that matches the primary RegExp pattern.
  • The input property is the target string that was searched.

The return values, and the index and input properties are the same as those of the returned array from the String match() Method when match() is used on a regular expression whose global attribute is not set.

When exec() is executed with the global attribute, "g", set on the RegExp instance, and a match is found, then:

  • The same results are returned as when the global attribute is not set, but the behavior is more complex, which allows further operations.

    NOTE:  Although exec() and the String match() method provide the same return arrays when the global attribute is not set on the regular expression, exec() and match() return different arrays when the global attribute is set on the regular expression.

  • Searching begins at the position in the target string specified by this.lastIndex. After a match is found, this.lastIndex is set to the position after the last character in the text matched. The property this.lastIndex is read/write and may be set at anytime, so you can loop through a string and find all matches of a pattern by setting this.lastIndex to the start position of the previous match found + 1. When no match is found, this.lastIndex is reset to 0.

If you use the T eScript engine and any matches are found, appropriate RegExp object static properties, such as RegExp.leftContext, RegExp.rightContext, RegExp.$n, and so forth are set, providing more information about the matches.

NOTE:  The ST eScript engine does not support the following static properties of the RegExp object: RegExp.$n (including '$_' and '$&'), RegExp.input, RegExp.lastMatch, RegExp.lastParen, RegExp.leftContext, RegExp.rightContext.

Examples

The following example calls exec() from a regular expression whose global attribute is not set. The output is commented.

function fn ()
{
   var myString = new String("Better internet");
   var myRE = new RegExp(/(.).(.er)/i);
   var results = myRE.exec(myString);
   var resultmsg = "";
   for(var i =0; i < results.length; i++)
   {
      resultmsg = resultmsg + "return[" + i + "] = " + results[i] + "\n";
   }
   TheApplication().RaiseErrorText(resultmsg);
}
fn ();

Output is:

return[0] = etter   \\First text containing primary pattern ...er (any three                     \\characters followed by "er")
return[1] = e        \\First text matching the first subpattern (.) (any single                     \\character) within the first text matching the primary pattern
return[2] = ter      \\First text matching the second subpattern (.er) (any single                      \\character followed by "er") within the first text matching                      \\the primary pattern

The following example calls exec() from a regular expression whose global attribute is set. The method returns all matches of the regular expression's primary pattern in a string, including matches that overlap.

function fn ()
{
   var str = "ttttot tto";
   var pat = new RegExp("t.t", "g");
   var resultmsg = "";
   while ((rtn = pat.exec(str)) != null)
   {
      resultmsg = resultmsg + "Text = " + rtn[0] + " Pos = " + rtn.index
      + " End = " + (pat.lastIndex - 1) + "\n";
      pat.lastIndex = rtn.index + 1;
   }
   TheApplication().RaiseErrorText(resultmsg)
}
fn ();

Output is:

Text = ttt Pos = 0 End = 2
Text = ttt Pos = 1 End = 3
Text = tot Pos = 3 End = 5
Text = t t Pos = 5 End = 7

See also

RegExp test() Method

String match() Method

RegExp test() Method

This method indicates whether a target string contains a regular expression pattern.

Syntax

regexp.test(str)

Parameter
Description

str

A string on which to perform a regular expression match

Returns

This method returns true if the target string contains the regular expression pattern, else it returns false.

Usage

This method is equivalent to regexp.exec(str)!=null.

If you use the T eScript engine and there is a match, then appropriate RegExp object static properties, such as RegExp.leftContext, RegExp.rightContext, RegExp.$n, and so forth are set, providing more information about the matches.

NOTE:  The ST eScript engine does not support the following static properties of the RegExp object: RegExp.$n (including '$_' and '$&'), RegExp.input, RegExp.lastMatch, RegExp.lastParen, RegExp.leftContext, RegExp.rightContext.

Although not common, test() may be used in a special way when the global attribute, "g", is set on the RegExp instance. As with RegExp exec(), when a match is found, the lastIndex property of the RegExp instance is set to the character position after the found text match. Thus, test() may be used repeatedly on a string, for instance, to determine whether a string has more than one match or to count the number of matches.

For information about using the RegExp lastIndex property repeatedly on a string, see RegExp exec() Method.

Example

var str = "one two three tio one";
var pat = /t.o/;
rtn = pat.test(str);
// Then rtn == true.

See also

RegExp exec() Method

String match() Method

Siebel eScript Language Reference