Siebel eScript Language Reference > Siebel eScript Commands > The String Object >

String Object Methods and Properties in Siebel eScript

The following conventions are used in the methods and properties in this topic:

• stringVar indicates any string variable. A specific instance of a variable should precede the period to use a property or call a method.
• The identifier String indicates a static method of the String object. It does not apply to a specific instance of the String object.

String charAt() Method

This method returns a character at a certain place in a string.

Syntax

stringVar.charAt(position)

Returns

A string of length 1 representing the character at position.

Usage

To get the first character in a string, use index 0, as follows:

var string1 = "a string";
var firstchar = string1.charAt(0);

To get the last character in a string, use:

var lastchar = string1.charAt(string1.length - 1);

If position does not fall between 0 and stringVar.length - 1, stringVar.charAt() returns an empty string.

See Also

String indexOf() Method
String lastIndexOf() Method
String length Property
String.fromCharCode() Static Method

String.fromCharCode() Static Method

This method returns a string created from the character codes that are passed to it as parameters.

Syntax

String.fromCharCode(code1, code2, ... coden)

Returns

A new string containing the characters specified by the codes.

Usage

This static method allows you to create a string by specifying the individual Unicode values of the characters in it. The identifier String is used with this static method, instead of a variable name as with instance methods because it is a property of the String constructor. The parameters passed to this method are assumed to be Unicode values. The following line:

var string1 = String.fromCharCode(0x0041,0x0042);

sets the variable string1 to "AB".

Example

The following example uses the decimal Unicode values of the characters to create the string "Siebel". For another example, see offset[] Method.

var seblStr = String.fromCharCode(83, 105, 101, 98, 101, 108);

See Also

Clib.toascii() Method

String indexOf() Method

This method returns the position of the first occurrence of a substring in a string.

stringVar.indexOf(substring [, offset])

Returns

The position of the first occurrence of a substring in a string variable.

Usage

stringVar.indexOf() searches for the entire substring in a string variable. The substring parameter may be a single character. If offset is not given, searching starts at position 0. If it is given, searching starts at the specified position.

For example:

var string = "what a string";
var firsta = string.indexOf("a")

returns the position of the first a appearing in the string, which in this example is 2. Similarly,

var magicWord = "abracadabra";
var secondA = magicWord.indexOf("a", 1);

returns 3, the index of the first a to be found in the string when starting from the second character of the string.

NOTE:  The indexOf() method is case sensitive.

See Also

String charAt() Method
Clib.strchr() Method
Clib.strpbrk() Method
String lastIndexOf() Method
String replace() Method

String lastIndexOf() Method

This method finds the position of the last occurrence of a substring in a string.

Syntax

stringVar.lastIndexOf(substring [, offset])

Returns

If offset is provided, the function returns the rightmost position, not greater than offset, at which substring begins in the string contained in the variable stringVar. If offset is not provided, the function returns the rightmost position in the entire string at which substring begins.

If substring is not found, or if offset is outside the range of valid positions in the string, then the function returns -1.

Usage

The stringVar.lastIndexOf() function is used to determine the last position within a string that a substring occurs. By setting the offset parameter, the search can be limited to a substring of leftmost characters of the string.

Substring is not required to occur entirely within the substring of the string bounded by offset. Its first character is required to occur at a position no greater than offset.

For example:

var string = "what a string";
string.lastIndexOf("a")

returns the position of the last a appearing in the string, which in this example is 5. Similarly,

var magicWord = "abracadabra";
var lastabr = magicWord.lastIndexOf("abr", 8);

returns 7, the position of the last "abr" beginning at a position no greater than 8.

See Also

String charAt() Method
Clib.strchr() Method
Clib.strpbrk() Method
String indexOf() Method
String replace() Method

String length Property

The length property stores an integer indicating the length of the string.

Syntax

stringVar.length

Usage

The length of a string can be obtained by using the length property. For example:

var string1 = "No, thank you.";
TheApplication().RaiseErrorText(string1.length);

displays the number 14, the number of characters in the string. Note that the index of the last character in the string is equivalent to stringVar.length -1, because the index begins at 0, not at 1.

Example

This code fragment returns the length of a name entered by the user (including spaces).

var userName = "Christopher J. Smith";
TheApplication().RaiseErrorText( "Your name has " +
   userName.length + " characters.");

String match() Method

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

Syntax

stringVar.match(regexp)

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

When match() is executed with the global attribute, "g", not set on the regular expression, then the return array and its properties are equivalent to those returned under the same circumstances using the RegExp exec() method. If 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 RegExp exec() method when exec() is used with a regular expression whose global attribute is not set.

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

• Element 0 of the return array is the first text in the string that matches the primary pattern of the regular expression.
• Each subsequent element of the return array is the next text in the string that matches the primary pattern of the regular expression, and that starts after the last character of the previous match. Thus matches that overlap other matches are not returned. For example, if the regular expression's primary pattern is a.. ("a" followed by any two characters) and the string is "abacadda", then the return array includes "aba" and "add", but not "aca".

  NOTE:  Although match() resembles the RegExp exec() method when the global attribute is not set on the regular expression, match() and exec() are very different when the global attribute is set on the regular expression.

Examples

The following example calls match() against 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 = myString.match(myRE);
   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 match() against a regular expression whose global attribute is set. The method returns matches of the regular expression's primary pattern that do not overlap.

function fn ()
{
   var str = "ttttot tto";
   var pat = new RegExp("t.t", "g");
   var rtn = str.match(pat);
   var resultmsg = "";
   for(var i =0; i < rtn.length; i++)
   {
      resultmsg = resultmsg + "match [" + i + "] = " + rtn[i] + "\n";
   TheApplication().RaiseErrorText(resultmsg);
   }
}
fn ();

Output is:

match [0] = ttt
match [1] = tot

The output does not include the "ttt" instance that starts at position 1 or "t t" because these instances start within other strings that are returned.

See also

RegExp exec() Method

String split() Method

This method splits a string into an array of strings based on the delimiters in the parameter substring.

Syntax

stringVar.split([delimiter])

Returns

An array of strings, creating by splitting stringVar into substrings, each of which begins at an instance of the delimiter character.

Usage

This method splits a string into an array of substrings such that each substring begins at an instance of delimiter. The delimiter is not included in any of the strings. If delimiter is omitted or is an empty string (""), the method returns an array of one element, which contains the original string.

This method is the inverse of arrayVar.join().

Example

The following example splits a typical Siebel command line into its elements by creating a separate array element at each space character. The string has to be modified with escape characters to be comprehensible to Siebel eScript. Also, the cmdLine variable must appear on a single line, which space does not permit in this volume.

function Button3_Click ()
{
   var msgText = "The following items appear in the array:\n\n";
   var cmdLine = "C:\\Siebel\\bin\\siebel.exe /c
\'c:\\siebel\\bin\\siebel.cfg\' /u SADMIN /p SADMIN /d Sample"
   var cmdArray = cmdLine.split(" ");
   for (var i = 0; i < cmdArray.length; i++)
      msgText = msgText + cmdArray[i] + "\n";
   TheApplication().RaiseErrorText(msgText);
}

Running this code produces the following result.

The following items appear in the array:
C:\Siebel\bin\siebel.exe
/c
'C:\siebel\bin\siebel.cfg'
/u
SADMIN
/p
SADMIN
/d
Sample

See Also

Array join() Method

String replace() Method

This method searches a string using the regular expression pattern defined by pattern. If a match is found, it is replaced by the substring defined by replexp.

Syntax

stringVar.replace(pattern, replexp)

Returns

The original string with replacements according to pattern and replexp.

Usage

The string is searched using the regular expression pattern defined by pattern. If a match is found, it is replaced by the substring defined by replexp. The parameter replexp may be:

• A simple string
• A string containing special regular expression replacement elements
• A function that returns a value that may be converted into a string

If you are using the T eScript engine and any replacements are made, appropriate RegExp object static properties such as RegExp.leftContext, RegExp.rightContext, and RegExp.$n are set. These properties provide more information about the replacements.

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.

The following table shows the special characters that may occur in a replacement expression.

Example

var rtn;
var str = "one two three two one";
var pat = /(two)/g;

// rtn == "one zzz three zzz one"
rtn = str.replace(pat, "zzz");

// rtn == "one twozzz three twozzz one";
rtn = str.replace(pat, "$1zzz");

// rtn == "one 5 three 5 one"
rtn = str.replace(pat, five());

// rtn == "one twotwo three twotwo one";
rtn = str.replace(pat, "$&$&");

function five() {
   return 5;

}

substring() Method

This method retrieves a section of a string.

Syntax

stringVar.substring(start[, end])

Returns

A new string, of length end - start, containing the characters that appeared in the positions from start to end - 1 of stringVar.

Usage

This method returns a portion of stringVar, comprising the characters in stringVar at the positions start through end - 1. The character at the end position is not included in the returned string. If the end parameter is not used, stringVar.substring() returns the characters from start to the end of stringVar.

Example

For an example, see String indexOf() Method.

See Also

String charAt() Method
String indexOf() Method
String lastIndexOf() Method

toLowerCase() Method

This method returns a copy of a string with the letters changed to lowercase.

Syntax

stringVar.toLowerCase()

Returns

A copy of stringVar in lowercase characters.

Usage

This method returns a copy of stringVar with uppercase letters replaced by their lowercase equivalents.

Example

The following code fragment assigns the value "e. e. cummings" to the variable poet:

var poet = "E. E. Cummings";
poet = poet.toLowerCase();

See Also

toUpperCase() Method

toUpperCase() Method

This method returns a copy of a string with the letters changed to uppercase.

Syntax

stringVar.toUpperCase()

Returns

A copy of stringVar in uppercase characters.

Usage

This method returns a copy of stringVar, with lowercase letters replaced by their uppercase equivalents.

Example

The following fragment accepts a filename as input and displays it in uppercase:

   var filename = "c:\\temp\\trace.txt";;
   TheApplication().RaiseErrorText("The filename in uppercase is " +filename.toUpperCase());

See Also

toLowerCase() Method