API String

String

Text conversion helpers and the immutable string instance API.

Script API Reference

Overview

AuroraScript strings are immutable values. Every instance method returns new text or a computed result and never mutates the original string. Indexes count .NET UTF-16 code units.

String is callable, so String(value) converts a value directly and always produces a primitive string rather than a wrapper object.

Quick Reference

Member	Returns	Summary
String([value])	string	Converts a value to a string.
String.valueOf(value)	string	Converts a value to a string.
String.fromCharCode(charCode)	string	Creates a one-character string from a character code.
String.compare(left, right)	number	Compares two strings and returns their ordering.
text.length	number	Number of UTF-16 code units.
text.contains(value)	boolean	Reports whether a substring occurs.
text.indexOf(value)	number	First index of a substring.
text.lastIndexOf(value)	number	Last index of a substring.
text.startsWith(value)	boolean	Reports whether the string starts with a prefix.
text.endsWith(value)	boolean	Reports whether the string ends with a suffix.
text.substring(start, [end])	string	Extracts a substring.
text.slice(start, [end])	string	Extracts a slice.
text.split([separator])	array	Splits the string into an array.
text.match(pattern)	any	Matches against a regex or pattern.
text.matchAll(pattern)	array	Returns all matches.
text.replace(pattern, replacement)	string	Replaces matched text.
text.padLeft(width, padding)	string	Pads the string on the left.
text.padRight(width, padding)	string	Pads the string on the right.
text.trim()	string	Trims both ends.
text.trimLeft()	string	Trims the left end.
text.trimRight()	string	Trims the right end.
text.charCodeAt(index)	number	Character code at an index.
text.toLowerCase()	string	Lowercase copy.
text.toUpperCase()	string	Uppercase copy.
text.toString()	string	Returns the same string value.

Constructors

String([value])

Parameters

Name	Type	Required	Description
value	any	No	Value to convert.

Returns

string — the converted text.

Behavior

Missing or non-string-convertible input produces an empty string.

Example

return String(42); // "42"

Properties

text.length

Returns

number — the string length in UTF-16 code units.

Example

return "Aurora".length; // 6

Methods

String.valueOf(value)

Parameters

Name	Type	Required	Description
value	any	Yes	Value to convert.

Returns

string — the converted text.

Example

return String.valueOf(true); // "true"

String.fromCharCode(charCode)

Parameters

Name	Type	Required	Description
charCode	number	Yes	UTF-16 character code.

Returns

string — a one-character string.

Example

return String.fromCharCode(65); // "A"

String.compare(left, right)

Parameters

Name	Type	Required	Description
left	string	Yes	First string in the comparison.
right	string	Yes	Second string in the comparison.

Returns

number — negative when left sorts first, zero when the strings are equal, positive when right sorts first.

Example

return String.compare("a", "b") < 0; // true

text.contains(value)

Parameters

Name	Type	Required	Description
value	string	Yes	Substring to search for.

Returns

boolean — whether the substring occurs.

Example

return "AuroraScript".contains("Script"); // true

text.indexOf(value)

Parameters

Name	Type	Required	Description
value	string	Yes	Substring to search for.

Returns

number — the first match index, or -1 when the substring is missing.

Example

return "a-b-a".indexOf("a"); // 0

text.lastIndexOf(value)

Parameters

Name	Type	Required	Description
value	string	Yes	Substring to search for.

Returns

number — the last match index, or -1 when the substring is missing.

Example

return "a-b-a".lastIndexOf("a"); // 4

text.startsWith(value)

Parameters

Name	Type	Required	Description
value	string	Yes	Prefix to test.

Returns

boolean — whether the string starts with the prefix.

Example

return "AuroraScript".startsWith("Aurora"); // true

text.endsWith(value)

Parameters

Name	Type	Required	Description
value	string	Yes	Suffix to test.

Returns

boolean — whether the string ends with the suffix.

Example

return "AuroraScript".endsWith("Script"); // true

text.substring(start, [end])

Parameters

Name	Type	Required	Description
start	number	Yes	Index of the first code unit to copy.
end	number	No	Index after the last code unit to copy.

Returns

string — the extracted substring.

Behavior

Indexes are clamped to the valid bounds of the string, and the runtime swaps start and end when start > end.

Example

return "Aurora".substring(0, 3); // "Aur"

text.slice(start, [end])

Parameters

Name	Type	Required	Description
start	number	Yes	Index of the first code unit to copy.
end	number	No	Index after the last code unit to copy.

Returns

string — the extracted slice.

Example

return "Aurora".slice(3); // "ora"

text.split([separator])

Parameters

Name	Type	Required	Description
separator	string	No	Delimiter that separates the segments.

Returns

array — the resulting segments.

Behavior

Omitting the separator returns an array containing the original text as its only element.

Example

return "a,b,c".split(",").length; // 3

text.match(pattern)

Parameters

Name	Type	Required	Description
pattern	regex or string	Yes	A Regex instance or a pattern string.

Returns

any — the match result, or null when there is no match.

Example

return "v42".match(new Regex("[0-9]+"));

text.matchAll(pattern)

Parameters

Name	Type	Required	Description
pattern	regex or string	Yes	A Regex instance or a pattern string.

Returns

array — every match found in the string.

Important

Collecting all matches requires a global regex. Pass the g flag, as in new Regex("[0-9]", "g").

Example

return "a1b2".matchAll(new Regex("[0-9]", "g")).length; // 2

text.replace(pattern, replacement)

Parameters

Name	Type	Required	Description
pattern	string or regex	Yes	Literal text or a Regex instance to match.
replacement	string or function	Yes	Replacement text, or a callback that produces the replacement for each match.

Returns

string — new text with the matches replaced.

Behavior

A global regex replaces every match. A string pattern uses literal text-match replacement semantics.

Example

return "a-b".replace("-", ":"); // "a:b"

text.padLeft(width, padding)

Parameters

Name	Type	Required	Description
width	number	Yes	Target total length.
padding	string	Yes	Padding text; its first character is used.

Returns

string — the padded text.

Example

return "7".padLeft(3, "0"); // "007"

text.padRight(width, padding)

Parameters

Name	Type	Required	Description
width	number	Yes	Target total length.
padding	string	Yes	Padding text; its first character is used.

Returns

string — the padded text.

Example

return "7".padRight(3, "_"); // "7__"

text.trim()

Parameters

None.

Returns

string — new text with leading and trailing whitespace removed.

Example

return "  Aurora  ".trim(); // "Aurora"

text.trimLeft()

Parameters

None.

Returns

string — new text with leading whitespace removed.

Example

return "  Aurora".trimLeft(); // "Aurora"

text.trimRight()

Parameters

None.

Returns

string — new text with trailing whitespace removed.

Example

return "Aurora  ".trimRight(); // "Aurora"

text.charCodeAt(index)

Parameters

Name	Type	Required	Description
index	number	Yes	Zero-based code-unit index.

Returns

number — the UTF-16 code unit at the index.

Behavior

An index outside the string returns NaN rather than raising an error.

Example

return "A".charCodeAt(0); // 65

text.toLowerCase()

Parameters

None.

Returns

string — a lowercase copy.

Example

return "Aurora".toLowerCase(); // "aurora"

text.toUpperCase()

Parameters

None.

Returns

string — an uppercase copy.

Example

return "Aurora".toUpperCase(); // "AURORA"

text.toString()

Parameters

None.

Returns

string — the same string value.

Example

return "Aurora".toString(); // "Aurora"