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 escaped() → String

function unescaped() → String

Escape and unescape a string, according to the string literal escaping rules.

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.

static function String.join(Array<String> strings) → String

Return a new string that is the concatenated version of all the strings in the array.

optional String separator

If provided the separator is inserted between each string.

optional Bool skipEmptyStrings = false

If set, empty strings in the strings list are ignored.

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) → String

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 not provided, all characters from position until the end of the string are 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)

function replaced(String before, String after) → String

Replaces all instances of before with after in the string.

The replace method replaces instances in place, whereas the replaced method returns a copy of the strings with the instances replaced.

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

function trim()

function trimmed() → String

Remove leading and trailing whitespace characters from a string.

The trim method removes the whitespace in place, whereas the trimmed method returns a copy of the string with the whitespace removed.

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 toInt() → Int

Returns the integer value of the string, or 0 if the string is not an integer.

Int value = "37".toInt() // 37

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

static async function String.load(Url url) → String

static async function String.load(Http.Request request) → String

Load text from a url or request.

The url can be a local file in your project, or a network URL.

static function String.tr(String string) → String

Returns the translated version of string into the current language, or string if a translation is not available.

optional String context

The translation context. This is also called a "table" in iOS parlance.

optional String androidId

The name of an Android string resource id to use for this string. If provided, when the project is running in an exported Android app (ie. not Zing Preview), Zing will resolve the Android resource and return the provided string.

If the string resource id is not valid, a warning will be printed and the default string value returned.