Siebel eScript Language Reference > Siebel eScript Commands > String Objects >
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)
|
|
position |
An integer indicating the position in the string of the character to be returned, where the position of the first character in the string is 0. |
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)
|
|
code1, code2, ... coden |
Integers representing Unicode character codes |
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])
|
|
substring |
One or more characters to be searched |
offset |
The position in the string at which to start searching, where 0 represents the first character |
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])
|
|
substring |
One or more characters to search for |
offset |
The rightmost position in the string at which to start searching. If offset is not provided, the entire string is searched. |
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)
|
|
regexp |
A regular expression, provided as a literal or as a variable |
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:
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 search () Method
This method searches a specified string for a specified regular expression pattern. Syntax
stringVar.search(regexp)
|
|
regexp |
A regular expression, provided as a literal or as a variable |
Returns
The index of the regular expression (regexp ) inside the specified string. If the regular expression is not found, this method returns -1. Usage
This method can be executed in server script and browser script. Example
function Test(sValue) { //Validate for 5 digit numbers var sCheck = /^\d{5}$/; //regular expression defining a 5 digit number if(sValue.search(sCheck)==0) { return("Valid"); } else { return("Invalid"); } }
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])
|
|
delimiter |
The character at which the value stored in stringVar is to be split |
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)
|
|
pattern |
Regular expression pattern to find or match in string. |
replexp |
Replacement expression which may be a string, a string with regular expression elements, or a function |
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.
|
|
$1, $2 ... $9 |
The text matched by regular expression patterns inside of parentheses. For example, $1 puts the text matched in the first parenthesized group in a regular expression pattern. |
$+ |
The text matched by the last regular expression pattern inside of the last parentheses, that is, the last group. |
$& |
The text matched by a regular expression pattern. |
$` |
The text to the left of the text matched by a regular expression pattern. |
$' |
The text to the right of the text matched by a regular expression pattern. |
\$ |
The dollar sign character. |
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])
|
|
start |
An integer specifying the location of the beginning of the substring to be returned |
end |
An integer one greater than the location of the last character of the substring to be returned |
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
|