String

Module	ejs
Definition	final class String
Inheritance	String Object
Specified	evolving

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

Qualifiers	Property	Type	Description
get	isAlpha	Boolean	Is there is at least one character in the string and all characters are alphabetic. Uses latin-1 for comparisons.
get	isAlphaNum	Boolean	Is there is at least one character in the string and all characters are alphabetic or numeric. Uses latin-1 for comparisons.
get	isDigit	Boolean	Is there is at least one character in the string and all characters are digits.
get	isLower	Boolean	Is there is at least one character in the string and there are no upper case characters.
get	isSpace	Boolean	Is there is at least one character in the string and all characters are white space.
get	isUpper	Boolean	Is there is at least one character in the string and there are no lower case characters.
get	length	Number	The length of the string in bytes.

Inherited Properties

String Class Methods

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

Inherited Methods

String Instance Methods

Qualifiers	Method
	%(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.

Inherited Methods

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

fill	Set 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).
join	Character 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.