String

String is a value type that can store strings of characters.

Literal syntax

String literals are expressed by enclosing the string in double-quotes.

property String country: "Australia"
property String quote: "Murum aries attigit"

As it is used as the string delimiter, you cannot directly include an actual double-quote character in a literal string. When you need to, you must escape the character first. Escaping refers to including a preceding escape, or backslash, character.

property String text: "\"Run away!\", he exclaimed."

Other special characters can be included in string literals using escape sequences. The most common are "\n" to include a new-line, and "\\" to include a literal backslash. For convenience, Zing supports the same 9 single-character escape sequences as JavaScript.

property String text: "First line.\nSecond line."

You can include more exotic characters in a string by escaping a 16-bit unicode code point value ("\unnnn").

property String appleWatch: "\uF8FF Watch"

Additionally Zing supports the same 2-character hexadecimal character escaping sequences as JavaScript.

Conversions

All value and element types can be converted to a string-ified version using a string cast.

String(123)
String(myVar)
String(Math.floor(2.345))

static function String.base64Decoded(String data) → String

static function String.base64Encoded(String data) → String

Encodes and decodes strings with MIME-style (RFC 2045) base64 coding.

If the data to be encoded is a UTF-16 string, it is first converted to UTF-8 before the bytes are encoded. This conversion is not reversed when decoding.

static function String.xhtmlDecoded(String string) → String

Decodes the XHTML and HTML character references present in the input string. xhtmlDecode decodes both numeric character and character entity references.

var string = "Cookies & Cream"
System.log(String.xhtmlDecoded(string)) // Logs "Cookies & Cream"

static function String.fromCharCode(Int charCode...) → String

Returns a new String consisting of the provided Unicode characters.

var string = String.fromCharCode(104, 101, 108, 108, 111) // "hello"

function append(String string)

Appends the string.

function arg(any value...) → String

Returns a new string, with the lowest numbered argument token replaced by the provided value.

var str = "I caught {0} fish".arg(7) // "I caught 7 fish"

If more than one value is provided, the argument tokens are replaced in ascending order.

// "I ran approximately 4 miles"
var str = "I {1} approximately {0} miles".arg(4, "ran")

function charCodeAt(Int position) → Int

Return a number for the unicode value of the single character at position, or 0 if position is outside the string's bounds.

Int charCode = "hello".charCodeAt(3) // 108

function compare(String other) → Int

Returns 0, -1 or 1 if this string is equal to, less than or greater than other.

Int compare = "silk".compare("cotton") // 1

function concat(String string...) → String

Returns this String consisting of the characters of this String, followed by the characters of each provided string.

String string = "Veni".concat(" vidi", " vici") // "Veni vidi vici"

function contains(String string) → Bool

Returns true if this string contains the substring, false otherwise.

optional Bool caseSensitive: true

Whether the search is case sensitive or insensitive.

function endsWith(String string) → Bool

Returns true if this string ends with the substring.

optional Bool caseSensitive: true

Whether the comparison is case sensitive or insensitive.

function indexOf(String searchString) → Int

Returns the index position of the first occurrence of the searchString in this string. Returns -1 if searchString is not found.

optional Int fromIndex

Begin searching from the specified index, instead of the start of the string.

optional Bool caseSensitive: true

Whether the search is case sensitive or insensitive.

Int index = "hello world!".indexOf("world") // 6

function insert(Int position, String string)

Inserts the string at the specified position.

function lastIndexOf(String searchString) → Int

Returns the index position of the last occurrence of the searchString in this string. Returns -1 if searchString is not found.

optional Int fromIndex

Begin searching from the specified index, instead of the end of the string.

optional Bool caseSensitive: true

Whether the search is case sensitive or insensitive.

Int index = "hello world!".lastIndexOf("l") // 9

function left(Int n) → String

Returns a substring that contains the first n characters of the String.

String string = "hello world!".left(5) // "hello"

property Int lengthread only

The length of the string in characters.

function mid(Int position[, Int n]) → String

Returns a string that contains n characters of this string, starting at the specified position index.

If n is omitted, all characters from position onward will be returned.

String string = "one two three".mid(4, 3) // "two"

function prepend(String string)

Prepends the string.

function remove(Int n)

function remove(Int n, Int length)

Remove length characters from the string, begining at position n. If length isn't provided, a single character is removed.

function right(Int n) → String

Returns a substring that contains the n rightmost characters of the String.

String string = "hello world!".right(6) // "world!"

function split(String separator) → Array<String>

Splits the string into an array of substrings wherever the separator occurs. If the separator does not occur in the string, the result is a single-element array containing the original string.

var fields = "hello,world".split(",") // ["hello", "world"]

function startsWith(String string) → Bool

Returns true if this string starts with the substring.

optional Bool caseSensitive: true

Whether the comparison is case sensitive or insensitive.

function replace(String before, String after)

Replaces all instances of before with after in the string.

String string = "Cats are the best"
string.replace("Cats", "Dogs") // "Dogs are the best"

function toLowerCase() → String

Returns a new string where all characters are now lower case.

"STOP SHOUTING".toLowerCase() // "stop shouting"

function toUpperCase() → String

Returns a new string where all characters are now upper case.

"speak up".toUpperCase() // "SPEAK UP"

function toNumber() → Float

Returns the number value of the string, or Math.NaN if the string is not a number.

Float value = "10.92".toNumber() // 10.92