String

Moduleejs
Definitionfinal class String
InheritanceString inherit Object
StabilityEvolving.

Each String object represents a single immutable linear sequence of characters.

Strings have operators for: comparison, concatenation, copying, searching, conversion, matching, replacement, and, subsetting.


Properties

QualifiersPropertyTypeDescription
public get isAlphaBooleanIs there is at least one character in the string and all characters are alphabetic. Uses latin-1 for comparisions.
public get isDigitBooleanIs there is at least one character in the string and all characters are digits.
public get isLowerBooleanIs there is at least one character in the string and there are no upper case characters.
public get isSpaceBooleanIs there is at least one character in the string and all characters are white space.
public get isUpperBooleanIf there is at least one character in the string and there are no lower case characters.

String Methods

QualifiersMethod
public %(arg: Object): String
 Format arguments as a string.
public -(str: String): String
 String subtraction.
public caseCompare(compare: String): Number
 Do a case sensitive comparison between this string and another.
public charAt(index: Number): String
 Return the character at a given position in the string.
public charCodeAt(index: Number = 0): Number
 Get a character code.
public concat(args: Array): String
 Concatenate strings and returns a new string.
public contains(pattern: Object): Boolean
 Check if a string contains a pattern.
public endsWith(test: String): Boolean
 Determine if this string ends with a given string.
public format(args: Array): String
 Format arguments as a string.
public static fromCharCode(codes: Array): String
 Create a string from the character code arguments.
iterator override get(): Iterator
 Get an iterator for this array to be used by "for (v in string)".
iterator override getValues(): Iterator
 Get an iterator for this array to be used by "for each (v in string)".
public indexOf(pattern: String, startIndex: Number = 0): Number
 Search for an item using strict equality "===".
public lastIndexOf(pattern: String, location: Number = -1): Number
 Search right to left for a substring starting at a given index.
public match(pattern: RegExp): Array
 Match the a regular expression pattern against a string.
public parseJSON(filter: Function = null): Object
 Parse the current string object as a JSON string object.
public printable(): String
 Create a new string with all nonprintable characters replaced with unicode hexadecimal equivalents (e.g.
public quote(): String
 Wrap a string in double quotes.
public remove(start: Number, end: Number = -1): String
 Remove characters from a string.
public replace(pattern: Object, replacement: String): String
 Search and replace.
public reverse(): String
 Reverse a string.
public search(pattern: Object): Number
 Search for a pattern.
public slice(start: Number, end: Number = -1 , step: Number = 1): String
 Extract a substring.
public split(delimiter: Object, limit: Number = -1): Array
 Split a string into an array of substrings.
public startsWith(test: String): Boolean
 Tests if this string starts with the string specified in the argument.
String(str: Array)
 String constructor.
public substring(startIndex: Number, end: Number = -1): String
 Extract a substring.
public times(times: Number): String
 Replication.
public toCamel(): String
 Copy the string into a new string and lower case the first character if there is one.
public override toJSON(): String
 Convert the string to an equivalent JSON encoding.
public tokenize(format: String): Array
 Scan the input and tokenize according to a string format specifier.
public toLower(): String
 Convert the string to lower case.
public toPascal(): String
 Copy the string into a new string and capitalize the first character if there is one.
public override toString(): String
 This function converts an object to a string representation.
public toUpper(): String
 Convert the string to upper case.
public trim(str: String = null): String
 Returns a trimmed copy of the string.

Method Detail

public %(arg: Object): String

Format arguments as a string.

Description
Use the string as a format specifier.
Parameters
arg: Object The argument to format. Pass an array if multiple arguments are required.
Returns
Formatted string.
Specified
ejscript-1.1
Example
"%5.3f" % num
>
"Arg1 %d, arg2 %d" % [1, 2]

public -(str: String): String

String subtraction.

Description
Remove the first occurance of str.
Parameters
str: String The string to remove from this string.
Returns
Return a new string.
Specified
ejscript-1.1

public caseCompare(compare: String): Number

Do a case sensitive comparison between this string and another.

Parameters
compare: String The string to compare against.
Returns
-1 if this string is less than the compare string, zero if equal and 1 if greater than.
Specified
ejscript-1.1

public charAt(index: Number): String

Return the character at a given position in the string.

Returns
A new string containing the selected character. If the index is out of range, returns the empty string.

public charCodeAt(index: Number = 0): Number

Get a character code.

Parameters
index: Number The index of the character to retrieve. [default: 0]
Returns
Return the character code at the specified index. If the index is -1, get the last character. Return NaN if the index is out of range.

public concat(args: Array): String

Concatenate strings and returns a new string.

Parameters
args: Array Strings to append to this string.
Returns
Return a new string.

public contains(pattern: Object): Boolean

Check if a string contains a pattern.

Parameters
pattern: Object The pattern can be either a string or regular expression.
Returns
Returns true if the pattern is found.
Specified
ejscript-1.1

public endsWith(test: String): Boolean

Determine if this string ends with a given string.

Parameters
test: String The string to test with.
Returns
True if the string matches.
Specified
ejscript-1.1

public format(args: Array): String

Format arguments as a string.

Description
Use the string as a format specifier. The format specifier has the form: %[-+ #,][width][precision][type]. See printf(1) for the meaning of the various fields.
Parameters
args: Array Array containing the data to format.
Returns
Formatted string.
Specified
ejscript-1.1
Example
"%5.3f".format(num)

"%s Arg1 %d, arg2 %d".format("Hello World", 1, 2)

static public fromCharCode(codes: Array): String

Create a string from the character code arguments.

Parameters
codes: Array Character codes from which to create the string.
Returns
A new string.

override iterator get(): Iterator

Get an iterator for this array to be used by "for (v in string)".

Returns
An iterator object.

override iterator getValues(): Iterator

Get an iterator for this array to be used by "for each (v in string)".

Returns
An iterator object.

public indexOf(pattern: String, startIndex: Number = 0): Number

Search for an item using strict equality "===".

Description
This call searches from the start of the string for the specified element.
Parameters
pattern: String The string to search for.
startIndex: Number Where in the array (zero based) to start searching for the object. [default: 0]
Returns
The items index into the array if found, otherwise -1.

public lastIndexOf(pattern: String, location: Number = -1): Number

Search right to left for a substring starting at a given index.

Parameters
pattern: String The string to search for.
location: Number The character index at which to start the search. [default: -1]
Returns
Return the starting index of the last match found.

public match(pattern: RegExp): Array

Match the a regular expression pattern against a string.

Parameters
pattern: RegExp The regular expression to search for.
Returns
Returns an array of matching substrings.

public parseJSON(filter: Function = null): Object

Parse the current string object as a JSON string object.

Description
The.
Parameters
filter: Function Optional function to call for each element of objects and arrays. Not yet supported. [default: null]
Returns
An object representing the JSON string.

public printable(): String

Create a new string with all nonprintable characters replaced with unicode hexadecimal equivalents (e.g.

Description
\uNNNN).
Returns
The new string.
Specified
ejscript-1.1

public quote(): String

Wrap a string in double quotes.

Returns
The new string.

public remove(start: Number, end: Number = -1): String

Remove characters from a string.

Description
Remove the elements from start to end inclusive.
Parameters
start: Number Numeric index of the first element to remove. Negative indicies measure from the end of the string. The -1 index refers to the last character element.
end: Number Numeric index of one past the last element to remove. [default: -1]
Returns
A new string with the characters removed.
Specified
ejscript-1.1

public replace(pattern: Object, replacement: String): String

Search and replace.

Description
Search for the given pattern which can be either a string or a regular expression and replace it with the replace text. If the pattern is a string, only the first occurrence is replaced.
Parameters
pattern: Object The regular expression pattern to search for.
replacement: String The string to replace the match with or a function to generate the replacement text.
Returns
Returns a new string.
Specified
ejscript-1.1

public reverse(): String

Reverse a string.

Returns
Returns a new string with the order of all characters reversed.
Specified
ejscript-1.1

public search(pattern: Object): Number

Search for a pattern.

Parameters
pattern: Object Regular expression pattern to search for in the string.
Returns
Return the starting index of the pattern in the string. Returns -1 if not found.

public slice(start: Number, end: Number = -1 , step: Number = 1): String

Extract a substring.

Parameters
start: Number The position of the first character to slice.
end: Number The position one after the last character. Negative indicies are measured from the end of the string. [default: -1 ]
step: Number Extract every "step" character. Step can be negative. [default: 1]

public split(delimiter: Object, limit: Number = -1): Array

Split a string into an array of substrings.

Description
Tokenizes a string using a specified delimiter.
Parameters
delimiter: Object String or regular expression object separating the tokens.
limit: Number At most limit strings are extracted. If limit is set to -1, then unlimited strings are extracted. [default: -1]
Returns
Returns an array of strings.

public startsWith(test: String): Boolean

Tests if this string starts with the string specified in the argument.

Parameters
test: String String to compare against.
Returns
True if it does, false if it doesn't.
Specified
ejscript-1.1

public String(str: Array)

String constructor.

Description
This can take two forms:
  • String()
  • String(str: String)
Parameters
str: Array The args can be either empty or a string. If a non-string arg is supplied, the VM will automatically cast to a string.

public substring(startIndex: Number, end: Number = -1): String

Extract a substring.

Description
Similar to slice but only allows positive indicies. If the end index is larger than start, then the effect of substring is as if the two arguments were swapped.
Parameters
startIndex: Number Integer location to start copying.
end: Number Postitive index of one past the last character to extract. [default: -1]
Returns
Returns a new string.

public times(times: Number): String

Replication.

Description
Replicate the string N times.
Parameters
times: Number The number of times to copy the string.
Returns
A new String with the copies concatenated together. Returns the empty string if times is <= zero.
Specified
ejscript-1.1

public toCamel(): String

Copy the string into a new string and lower case the first character if there is one.

Description
If the first non-white character is not a character or if it is already lower there is no change.
Returns
A new String.
Specified
ejscript-1.1

override public toJSON(): String

Convert the string to an equivalent JSON encoding.

Returns
A quoted string.
Throws
TypeError: If the object could not be converted to a string.

public tokenize(format: String): Array

Scan the input and tokenize according to a string format specifier.

Parameters
format: String Tokenizing format specifier.
Returns
Array containing the tokenized elements.
Specified
ejscript-1.1
Example
for (s in string.tokenize("%s %s %s")) {
    print(s)
}

public toLower(): String

Convert the string to lower case.

Returns
Returns a new lower case version of the string.
Specified
ejscript-1.1

public toPascal(): String

Copy the string into a new string and capitalize the first character if there is one.

Description
If the first non-white character is not a character or if it is already capitalized there is no change.
Returns
A new String.
Specified
ejscript-1.1

override public toString(): String

This function converts an object to a string representation.

Description
Types typically override this to provide the best string representation.
Returns
A string representation of the object. For Objects "[object className]" will be returned, where className is set to the name of the class on which the object was based.

public toUpper(): String

Convert the string to upper case.

Returns
Returns a new upper case version of the string.
Specified
ejscript-1.1

public trim(str: String = null): String

Returns a trimmed copy of the string.

Description
Normally used to trim white space, but can be used to trim any substring from the start or end of the string.
Parameters
str: String May be set to a substring to trim from the string. If not set, it defaults to any white space. [default: null]
Returns
Returns a (possibly) modified copy of the string.