ECMAScript String type.

More...

Inherits :

• Object

This is the script counterpart to the QString type used in the C++ SDK.

A string is a sequence of zero or more Unicode characters. All string indexes are zero-based, which means the index for the last character in the string sText is always sText.length - 1.

Example:

Strings creation and concatenation

var str1 = "foo";
var str2 = new String( "foo" );
var str3 = str1 + " " + str2;
var str4 = String( "%1%2" ).arg( "foo" ).arg( "bar" );

See Also:

• DzStringHelper

---

Number : length

The length of the string.

---

String : fromCharCode( Number charCode1, … )

Parameter(s):

• charCode1 - The first character of the string.

Return Value:

• A string comprised of the characters represented by the Unicode character codes in the argument(s).

Example:

print( String.fromCharCode( 72, 69, 76, 76, 79 ) ); //HELLO

---

String()

Default constructor.

---

String( String text )

Parameter(s):

• text - The initial value of the string.

---

String : charAt( Number pos )

Parameter(s):

• pos - The index position to retrieve the character from.

Return Value:

• The character in the string at pos . If pos is out of bounds, undefined is returned.

---

Number : charCodeAt( Number pos )

Parameter(s):

• pos - The index position of the character to retrieve the code for.

Return Value:

• The character code of the character at pos . If pos is out of bounds, undefined is returned.

---

String : concat( String string1, … )

Parameter(s):

• string1 - The first string to concatenate.

Return Value:

• This string with the given string(s) concatenated. Essentially, this + string1 + … + stringN.

---

Number : indexOf( String pattern, Number startPos=0 )

Parameter(s):

• pattern - The pattern to search the string for.
• startPos - The [zero-based] index to begin the search at.

Return Value:

• The [zero-based] index at the beginning of the first occurrence of pattern in the string, starting at position startPos. If startPos is not specified, the function starts at the beginning of the string. If the pattern is not found in the string, -1 is returned.

---

Number : indexOf( RegExp pattern, Number startPos=0 )

Parameter(s):

• pattern - The pattern to search the string for.
• startPos - The [zero-based] index to begin the search at.

Return Value:

• The index of pattern in the string, starting at position startPos. If startPos is not specified, the function starts at the beginning of the string. If the pattern is not found in the string, -1 is returned.

---

Number : lastIndexOf( RegExp pattern, Number startPos=length-1 )

Parameter(s):

• pattern - The pattern to search the string for.
• startPos - The [zero-based] index to begin the search at.

Return Value:

• The index of pattern in the string, starting at position startPos. If startPos is not specified, the function starts at the end of the string. If the pattern is not found in the string, -1 is returned.

---

Number : lastIndexOf( String pattern, Number startPos=length-1 )

Parameter(s):

• pattern - The pattern to search the string for.
• startPos - The [zero-based] index to begin the search at.

Return Value:

• The index of pattern in the string, starting at position startPos. If startPos is not specified, the function starts at the end of the string. If the pattern is not found in the string, -1 is returned.

---

Number : localeCompare( String that )

Performs a locale-sensitive comparison of the given string with this string.

Parameter(s):

• that - The string to compare this string to.

Return Value:

• A numeric value that will be negative, zero or positive depending on whether this comes before that, or that comes before this, zero is returned if the strings match.

---

Array : match( RegExp pattern )

Parameter(s):

• pattern - The pattern to search the string for.

Return Value:

• The matched pattern in the string. If the pattern is not found in the string, undefined is returned.

---

String : replace( String pattern, Function callbackfn )

Parameter(s):

• pattern - The pattern to search the string for.
• callbackfn - A function to call for the first occurrence of a matched substring. The function arguments are: the substring that matched, followed by the offset within the string where the match occurred, followed by the string being evaluated.

Return Value:

• A new string wherein the result of calling callbackfn for the first occurrence of a matched substring has bee replaced with the corresponding return value.

---

String : replace( RegExp pattern, String newValue )

Parameter(s):

• pattern - The pattern to search the string for.
• newValue - The new string to replace matches with.

Return Value:

• A new string wherein pattern has been replaced with newValue.

---

String : replace( RegExp pattern, Function callbackfn )

Parameter(s):

• pattern - The pattern to search the string for.
• callbackfn - A function to call for each matched substring. The number of arguments passed to the function varies depending on the number of captures. The arguments are ordered as: the substring that matched, followed by each capture in the match result, followed by the offset within the string where the match occurred, followed by the string being evaluated.

Return Value:

• A new string wherein the result of calling callbackfn for each matched substring has been replaced with the corresponding return value.

---

String : replace( String pattern, String newValue )

Parameter(s):

• pattern - The pattern to search the string for.
• newValue - The new string to replace matches with.

Return Value:

• A new string wherein the first occurrence of pattern has been replaced with newValue.

---

Number : search( String pattern )

Parameter(s):

• pattern - The pattern to search the string for.

Return Value:

• The index of the first occurrence of pattern in the string, starting at the beginning of the string. If the pattern is not found in the string, -1 is returned.

---

Number : search( RegExp pattern )

Parameter(s):

• pattern - The pattern to search the string for.

Return Value:

• The index of the first occurrence of pattern in the string, starting at the beginning of the string. If the pattern is not found in the string, -1 is returned.

---

String : slice( Number start, Number end )

Creates a substring from this string, starting with the character at index start, and going to, but not including the character at index end.

Parameter(s):

• start - The index of the first character in the string to include in the substring. If negative, it will be treated as this.length + start.
• end - The index of the character at the end of the substring, this character will not be included in the substring. If undefined, the substring will include all characters from start to the end of this string. If negative, it will be treated as this.length + end.

Return Value:

• The substring that was created.

---

Array : split( RegExp separator, Number limit )

Splits this string into an array of substrings at each occurrence of separator.

Parameter(s):

• separator - A regular expression containing the separator that will be searched for. If an empty expression is given, the result will contain one entry for each character in this string. If undefined is given the result will contain one entry containing the whole string.
• limit - If the resulting array contains more entries than limit, it will be truncated to contain limit entries.

Return Value:

• An array of substrings.

---

Array : split( String separator )

Splits this string into an array of substrings at each occurrence of separator.

Parameter(s):

• separator - A string containing the separator that will be searched for. If an empty string is given, the result will contain one entry for each character in this string. If undefined is given the result will contain one entry containing the whole string.

Return Value:

• An array of substrings.

---

Array : split( String pattern )

Parameter(s):

• pattern - The pattern to search the string for.

Return Value:

• An array of strings made up of this string split on each occurrence of pattern.

---

Array : split( RegExp pattern )

Parameter(s):

• pattern - The pattern to search the string for.

Return Value:

• An array of strings made up of this string split on each occurrence of pattern.

---

Array : split( String separator, Number limit )

Splits this string into an array of substrings at each occurrence of separator.

Parameter(s):

• separator - A string containing the separator that will be searched for. If an empty string is given, the result will contain one entry for each character in this string. If undefined is given the result will contain one entry containing the whole string.
• limit - If the resulting array contains more entries than limit, it will be truncated to contain limit entries.

Return Value:

• An array of substrings.

---

String : substring( Number start, Number end=length )

Parameter(s):

• start - The index of the first character to copy to the substring.
• end - An optional ending index; the end of the string if not specified.

Return Value:

• The substring of the string starting at start, up to but not including end.

See Also:

• mid()

---

String : toLocaleLowerCase()

Provides a locale-aware version of toLowerCase().

Return Value:

• This string converted to lower case in a locale-specific manner.

---

String : toLocaleUpperCase()

Provides a locale-aware version of toUpperCase().

Return Value:

• This string converted to upper case in a locale-specific manner.

---

String : toLowerCase()

Return Value:

• The string, with all characters converted to lower case.

See Also:

• lower()

---

String : toString()

Return Value:

• This string object.

---

String : toUpperCase()

Return Value:

• The string, with all characters converted to upper case.

See Also:

• upper()

---

String : trim()

Return Value:

• The string, with leading and trailing white space removed.

---

String : valueOf()

Return Value:

• This string object.

---

String : arg( String value, Number fieldWidth=0 )

Parameter(s):

• value - The text to represent as a string.
• fieldWidth - Specifies the minimum amount of space that value is padded to. A positive fieldWidth will produce right aligned text, a negative fieldWidth will produce left aligned text.

Return Value:

• The modified string, replacing the lowest occurrence of %1, %2,… with value.

---

String : arg( Number value, Number fieldWidth=0 )

Parameter(s):

• value - The Number to represent as a string.
• fieldWidth - Specifies the minimum amount of space that value is padded to. A positive fieldWidth will produce right aligned text, a negative fieldWidth will produce left aligned text.

Return Value:

• The modified string, replacing the lowest occurrence of %1, %2,… with value.

---

String : argDec( Number value, Number fieldWidth=0, Number format='g', Number precision )

Specialized for cases where value is a decimal.

Parameter(s):

• value - The Number to represent as a string.
• fieldWidth - Specifies the minimum amount of space that value is padded to. A positive fieldWidth will produce right aligned text, a negative fieldWidth will produce left aligned text.
• format - The format to use:
  • 'e' : format as [-]9.9e[+|-]999
  • 'E' : format as [-]9.9E[+|-]999
  • 'f' : format as [-]9.9
  • 'g' : use 'e' or 'f' format, whichever is more concise
  • 'G' : use 'E' or 'f' format, whichever is more concise
• precision - With 'e', 'E' and 'f', this is the numbers of digits after the decimal point. With 'g' and 'G', this is the maximum number of significant digits.

Return Value:

• The modified string, replacing the lowest occurrence of %1, %2,… with value.

Example:

var fValue = Math.PI;
var sValue = String( "%1" ).argDec( fValue, 0, 'f', 5 );
 
MessageBox.information( String( "Variable : sValue\nType : %1\nValue : %2" )
	.arg( typeof sValue ).arg( sValue ), "String.argDec(...)", "&OK" );

---

String : argInt( Number value, Number fieldWidth=0, Number base=10 )

Specialized for cases where value is an integer.

Parameter(s):

• value - The Number to represent as a string.
• fieldWidth - Specifies the minimum amount of space that value is padded to. A positive fieldWidth will produce right aligned text, a negative fieldWidth will produce left aligned text.
• base - The base, which must be between 2 and 36.

Return Value:

• The modified string, replacing the lowest occurrence of %1, %2,… with value.

Example:

var nValue = 32;
var sValue = String( "%1" ).argInt( nValue, 0, 10 );
 
MessageBox.information( String( "Variable : sValue\nType : %1\nValue : %2" )
	.arg( typeof sValue ).arg( sValue ), "String.argInt(...)", "&OK" );

---

Boolean : endsWith( String pattern )

Parameter(s):

• pattern - The pattern to search the string for.

Return Value:

• true if the string ends with pattern, otherwise false.

---

Boolean : endsWith( RegExp pattern )

Parameter(s):

• pattern - The pattern to search the string for.

Return Value:

• true if the string ends with pattern, otherwise false.

---

Number : find( RegExp pattern, Number startPos=0 )

Parameter(s):

• pattern - The pattern to search the string for.
• startPos - The [zero-based] index to begin the search at.

Return Value:

• The index of the first occurrence of pattern in the string, starting at position startPos. If startPos is not specified, the function starts at the beginning of the string. If the pattern is not found in the string, -1 is returned.

---

Number : find( String pattern, Number startPos=0 )

Parameter(s):

• pattern - The pattern to search the string for.
• startPos - The [zero-based] index to begin the search at.

Return Value:

• The index of the first occurrence of pattern in the string, starting at position startPos. If startPos is not specified, the function starts at the beginning of the string. If the pattern is not found in the string, -1 is returned.

---

Number : findRev( RegExp pattern, Number startPos=length-1 )

Parameter(s):

• pattern - The pattern to search the string for.
• startPos - The [zero-based] index to begin the search at.

Return Value:

• The index of the first occurrence of pattern in the string, starting at position startPos. If startPos is not specified, the function starts at the end of the string. If the pattern is not found in the string, -1 is returned.

---

Number : findRev( String pattern, Number startPos=length-1 )

Parameter(s):

• pattern - The pattern to search the string for.
• startPos - The [zero-based] index to begin the search at.

Return Value:

• The index of the first occurrence of pattern in the string, starting at position startPos. If startPos is not specified, the function starts at the end of the string. If the pattern is not found in the string, -1 is returned.

---

Boolean : isEmpty()

Return Value:

• true if the string is empty (has a length of 0), otherwise false.

---

String : left( Number num )

Parameter(s):

• num - The number of characters to copy from the beginning of the string.

Return Value:

• The substring of this string containing the num leftmost characters.

---

String : lower()

Return Value:

• The string, with all characters converted to lower case.

See Also:

• toLowerCase()

---

String : mid( Number startIndex, Number num )

Parameter(s):

• startIndex - The index of the first character to copy from the string.
• num - The number of characters to copy from the string.

Return Value:

• The substring of this string starting at startIndex including num characters.

See Also:

• substring()

---

String : right( Number num )

Parameter(s):

• num - The number of characters to copy from the end of the string.

Return Value:

• The substring of this string containing the num rightmost characters.

---

Number : searchRev( RegExp pattern )

Parameter(s):

• pattern - The pattern to search the string for.

Return Value:

• The index of the first occurrence of pattern in the string, starting at the end of the string. If the pattern is not found in the string, -1 is returned.

---

Number : searchRev( String pattern )

Parameter(s):

• pattern - The pattern to search the string for.

Return Value:

• The index of the first occurrence of pattern in the string, starting at the end of the string. If the pattern is not found in the string, -1 is returned.

---

Boolean : startsWith( RegExp pattern )

Parameter(s):

• pattern - The pattern to search the string for.

Return Value:

• true if the string starts with pattern, otherwise false.

---

Boolean : startsWith( String pattern )

Parameter(s):

• pattern - The pattern to search the string for.

Return Value:

• true if the string starts with pattern, otherwise false.

---

String : upper()

Return Value:

• The string, with all characters converted to upper case.

See Also:

• toUpperCase()