String

Moduleejs
Definitionfinal class String
InheritanceString inherit Object
Specifiedevolving

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
get isAlphaBooleanIs there is at least one character in the string and all characters are alphabetic. Uses latin-1 for comparisons.
get isAlphaNumBooleanIs there is at least one character in the string and all characters are alphabetic or numeric. Uses latin-1 for comparisons.
get isDigitBooleanIs there is at least one character in the string and all characters are digits.
get isLowerBooleanIs there is at least one character in the string and there are no upper case characters.
get isSpaceBooleanIs there is at least one character in the string and all characters are white space.
get isUpperBooleanIs there is at least one character in the string and there are no lower case characters.
get lengthNumberThe length of the string in bytes.

String Class Methods

QualifiersMethod
static fromCharCode(codes: Array): String
 Create a string from the character code arguments.

String Instance Methods

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

Method Detail

%(arg: Object): String
Description
Format arguments as a string. Use the string as a format specifier.
Parameters
arg: Object The argument to format. Pass an array if multiple arguments are required.
Returns
-1 if less than, zero if equal and 1 if greater than.
Specified
ejscript-2.5
Example
"%5.3f" % num

"Arg1 %d, arg2 %d" % [1, 2] @spec ejs

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

String(str: Array)
Description
String constructor. 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.

caseCompare(compare: String): Number
Description
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-2.5

caselessCompare(compare: String): Number
Description
Do a case insensitive 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-2.5

charAt(index: Number): String
Description
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.

charCodeAt(index: Number = 0): Number
Description
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.

concat(args: Array): String
Description
Concatenate strings and returns a new string.
Parameters
args: Array Strings to append to this string.
Returns
Return a new string.

contains(pattern: Object): Boolean
Description
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-2.5

endsWith(test: String): Boolean
Description
Determine if this string ends with a given string.
Parameters
test: String The string to test with.
Returns
True if the string matches.
Specified
ejs 8

expand(obj: Object, options: Object = null): String
Description
Replace tokens in the string and return an expanded string. Tokens are represented by '{field}' where field may contain '.'. For example {user.name}. To preserve an {token} unmodified, preceed the token with an extra ''. For example: ${token}.
Parameters
obj: Object Containing tokens to expand.
options: Object Options hash. [default: null]
Options
fillSet to a string to use for missing properties. Set to undefined, null or omit the fill option to throw an exception for missing properties. Set fill to true to preserve undefined tokens as-is. This permits multi-pass expansions. Set to false to remove the token. Otherwise set to any string to replace the token with the string value. Default is to throw an exception (undefined).
joinCharacter to use to join array elements. Defaults to space.
Returns
Expanded string.

format(args: Array): String
Description
Format arguments as a string. 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
-1 if less than, zero if equal and 1 if greater than.
Specified
ejscript-2.5
Example
"%5.3f".format(num)
\n\n
"%s Arg1 %d, arg2 %d".format("Hello World", 1, 2)
@spec ejs

override iterator get(): Iterator
Description
Get an iterator for this array to be used by "for (v in string)".
Returns
An iterator object.

override iterator getValues(): Iterator
Description
Get an iterator for this array to be used by "for each (v in string)".
Returns
An iterator object.

indexOf(pattern: String, startIndex: Number = 0): Number
Description
Search for an item using strict equality "===". 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.

static fromCharCode(codes: Array): String
Description
Create a string from the character code arguments.
Parameters
codes: Array Character codes from which to create the string.
Returns
A new string.

lastIndexOf(pattern: String, location: Number = -1): Number
Description
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.

match(pattern: RegExp): Array
Description
Match a pattern using a regular expression.
Parameters
pattern: RegExp The regular expression pattern to search for.
Returns
If matches found, returns an array of matching substrings. Otherwise returns null.

parseJSON(filter: Function = null): Object
Description
Parse the current string object as a JSON string object. 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.

printable(): String
Description
Create a new string with all nonprintable characters replaced with unicode hexadecimal equivalents (e.g. \uNNNN).
Returns
The new string.
Specified
ejscript-2.5

quote(): String
Description
Wrap a string in double quotes.
Returns
The new string.

remove(start: Number, end: Number = -1): String
Description
Remove characters from a string. Remove the elements from.
Parameters
start: Number Numeric index of the first element to remove. Negative indicies measure from the end of the string. -1 is 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-2.5

replace(pattern: Object, replacement: Object = ): String
Description
Search and replace. 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 or string pattern to search for.
replacement: Object The string to replace the match with or a function to generate the replacement text. The replacement string can contain special replacement patterns: "$" inserts a "$", "$&" inserts the matched substring, "$`" inserts the portion that preceeds the matched substring, "$'" inserts the portion that follows the matched substring, and "$N" inserts the Nth parenthesized substring. The replacement parameter can also be a function which will be invoked and the function return value will be used as the resplacement text. The function will be invoked multiple times for each match to be replaced if the regular expression is global. The function will be invoked with the signature: function (matched, submatch_1, submatch_2, ..., matched_offset, original_string). [default: ]
Returns
Returns a new string.
Specified
ejscript-2.5

reverse(): String
Description
Reverse a string.
Returns
Returns a new string with the order of all characters reversed.
Specified
ejscript-2.5

search(pattern: Object): Number
Description
Search for a pattern.
Parameters
pattern: Object Regular expression or string pattern to search for in the string.
Returns
Return the starting index of the pattern in the string. Return -1 if not found.

slice(start: Number, end: Number = -1, step: Number = 1): String
Description
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. The -1 index means the last character, so slice(0, -1) will return all characters except the last. [default: -1]
step: Number Extract every "step" character. [default: 1]

split(delimiter: Object, limit: Number = -1): Array
Description
Split a string into an array of substrings. 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. P.

startsWith(test: String): Boolean
Description
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-2.5

substring(startIndex: Number, end: Number = -1): String
Description
Extract a substring. 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.

times(times: Number): String
Description
Replication. 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 empty string if times is <= zero.
Specified
ejscript-2.5

toCamel(): String
Description
Copy the string into a new string and lower case the first character if there is one. 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-2.5

override toJSON(): String
Description
Convert the string to an equivalent JSON encoding.
Returns
A quoted string.
Throws
TypeError: If the object could not be converted to a string. 8

toLowerCase(): String
Description
Convert the string to lower case.
Returns
Returns a new lower case version of the string.
Specified
ejscript-2.5

toPascal(): String
Description
Copy the string into a new string and capitalize the first character if there is one. 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-2.5

toPath(): Path
Description
Convert the string to a path.
Returns
Returns an equivalent Path object.
Specified
ejscript-2.5

override toString(): String
Description
This function converts an object to a string representation. 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.

toUpperCase(): String
Description
Convert the string to upper case.
Returns
Returns a new upper case version of the string.
Specified
ejscript-2.5

tokenize(format: String): Array
Description
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-2.5
Example
for (s in string.tokenize("%s %s %s")) {
    print(s)
}
@spec ejs

trim(str: String = null): String
Description
Returns a trimmed copy of the string. Normally used to trim white space, but can be used to trim any substring from the start and 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.

trimEnd(str: String = null): String
Description
Trim text from the end of a 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.

trimStart(str: String = null): String
Description
Trim text from the start of a 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.