String

Built-in type · Written “Hello, #{name}”, ‘C:\raw\text’, or “”“ for several lines

A String is a piece of text: a name, a message, a line from a file. A String never changes. Every method on this page gives back a new String and leaves the original as it was.

There are three ways to write one. Double quotes are the usual way; inside them, #{...} puts a value into the text, and a backslash starts an escape such as \n for a new line or \t for a tab. Single quotes write the text exactly as it is, which suits Windows paths and patterns full of backslashes. Three double quotes on lines of their own hold text that spans several lines, with the indentation of the closing quotes removed.

const name = "Ada"
print("Hello, #{name}!")       # prints Hello, Ada!
print('C:\Users\ada')          # prints C:\Users\ada

const poem = """
    Roses are red,
    Emerald is green.
    """

A character is what a reader sees as one character: é is one character, and so is 👋, however it is stored. count, indexing, and every method here count characters that way, so text is never cut in the middle of one. text[0] is the first character, as its own String. Finding the character at an index means counting from the start, so it takes longer for later characters in very long text.

String’s methods take their arguments in order, not by name: "7".pad_start(3, "0").

At a glance

Size
count	How many characters it has
empty?(), blank?()	Whether it has no characters, or only spaces

Characters
chars()	Each character, as a list
code_points(), bytes()	How the text is stored, for advanced uses

Changing case and spaces
upper(), lower(), capitalize()	Capital and small letters
trim(), trim_start(), trim_end()	Without spaces at the ends

Searching
contains?(text)	Whether it contains some text
starts_with?(text), ends_with?(text)	Whether it begins or ends with some text
index_of(text)	Where some text first appears

Taking it apart
substring(start)	Part of it, by position
split(separator)	Pieces between a separator
lines()	Each line
partition(separator)	Before and after the first separator

Making new text
replace(old, new)	With some text replaced
insert_at(index, text)	With text added at a position
remove_prefix(text), remove_suffix(text)	Without a beginning or ending
reverse(), repeat(times)	Backwards, or several times over
collapse_repeats()	With runs of one character shortened to one
pad_start(width), pad_end(width), pad_center(width)	Filled out to a width

Converting
to_int(), to_float()	The number the text spells

Operators

Operator	Meaning	Example
+	Join two strings	"Emerald" + " city" → "Emerald city"
+=	Add to the end of a variable	greeting += "!"
== !=	Compare	"cafe\u{301}" == "café" → true
< <= > >=	Order	"apple" < "banana" → true
text[index]	One character	"hé👋"[1] → "é"
text[start..<end]	Part of the text	"Emerald"[0..<3] → "Eme"

+ only joins two strings: "Score: " + 10 is an error. Write "Score: #{10}", or turn the number into text with to_string() first.

Two strings are equal when they are the same text, even if they were typed differently: an é typed as one character equals an e followed by a combining accent. Order follows Unicode’s numbering of characters, which puts every capital letter before every small one, so "B" < "a" is true.

Like a list, a String can be indexed with a range: text[start..<end] stops before end, and text[start..end] includes it. Either end can be left out inside the brackets: "Emerald"[..<3] is "Eme", and "Emerald"[4..<] is "ald".

A for loop visits each character:

for character in "hé👋" {
    print(character)
}
# prints h, é, 👋

Size

count: Int

How many characters the text has.

"héllo 👋".count   # → 7

empty?(): Bool

Whether the text has no characters at all.

"".empty?()      # → true
"   ".empty?()   # → false

blank?(): Bool

Whether the text is empty or has only spaces, tabs, and line breaks.

"   ".blank?()     # → true
" x ".blank?()     # → false

Characters

chars(): List[String]

Each character, in order, as a list of one-character strings.

"hé👋".chars()   # → ["h", "é", "👋"]

code_points(): List[Int]

The Unicode number of each code point the text is stored as. A character can be stored as more than one code point, so for characters, use chars() instead.

"é".code_points()   # → [233]

bytes(): List[Int]

The text’s UTF-8 bytes, each from 0 to 255. This is how the text is stored in a file, not a list of its characters.

"é".bytes()   # → [195, 169]

Changing case and spaces

upper(): String

The text in capital letters.

"Emerald".upper()   # → "EMERALD"

lower(): String

The text in small letters.

"Emerald".lower()   # → "emerald"

capitalize(): String

The text with its first character in capitals. The rest is left as it was.

"emerald city".capitalize()   # → "Emerald city"

trim(): String

The text without spaces, tabs, or line breaks at either end.

"  hi  ".trim()   # → "hi"

trim_start(): String

The text without spaces at its start.

"  hi  ".trim_start()   # → "hi  "

trim_end(): String

The text without spaces at its end.

"  hi  ".trim_end()   # → "  hi"

Searching

These look for the exact text they are given: "a.b".contains?(".") looks for a dot. To search for a pattern, such as any run of digits, use a Regex.

contains?(text: String): Bool

Whether text appears anywhere in the text. It matches whole characters only, so "café".contains?("e") is false: the é is one character, not an e.

"a.b".contains?(".")   # → true

starts_with?(text: String): Bool

Whether the text begins with text.

"Emerald".starts_with?("Em")   # → true

ends_with?(text: String): Bool

Whether the text ends with text.

"Emerald".ends_with?("ld")   # → true

index_of(text: String): Int?

Where text first appears, counting characters from 0, or nothing when it does not appear.

"banana".index_of("an")   # → 1
"banana".index_of("x")    # → nothing

Taking it apart

substring(start: Int): String

The text from position start to the end. A start equal to count gives "".

"Emerald".substring(4)   # → "ald"

Raises when start is negative or past the end.

substring(start: Int, count: Int): String

count characters, beginning at position start.

"Emerald".substring(1, 3)   # → "mer"

Raises when start or count is negative, or the part runs past the end.

split(separator: String): List[String]

The pieces of text between each separator, in order. Two separators side by side give an empty piece between them.

"a,b,,c".split(",")   # → ["a", "b", "", "c"]

Raises when separator is "". To split text into characters, use chars().

lines(): List[String]

Each line, without its line break. A line break at the very end does not start another, empty line, and a Windows line break (\r\n) counts as one.

"one\ntwo\r\nthree\n".lines()   # → ["one", "two", "three"]

partition(separator: String): (String, String, String)

The text before the first separator, the separator itself, and the text after it. When the separator does not appear, the whole text comes first and the other two are empty.

"key=value=x".partition("=")   # → ("key", "=", "value=x")
"none".partition("=")          # → ("none", "", "")

Raises when separator is "".

Making new text

replace(old: String, new: String): String

The text with every old replaced by new.

"banana".replace("a", "o")   # → "bonono"

Raises when old is "".

insert_at(index: Int, text: String): String

The text with text added before the character at index. An index equal to count adds it at the end.

"Emrald".insert_at(2, "e")   # → "Emerald"

Raises when index is negative or past the end.

remove_prefix(text: String): String

The text without text at its start. When it does not start with text, it is returned as it was.

"Mr. Smith".remove_prefix("Mr. ")   # → "Smith"

remove_suffix(text: String): String

The text without text at its end. When it does not end with text, it is returned as it was.

"report.txt".remove_suffix(".txt")   # → "report"

reverse(): String

The characters in the opposite order.

"stressed".reverse()   # → "desserts"

repeat(times: Int): String

The text, times times over.

"ab".repeat(3)   # → "ababab"

collapse_repeats(): String

The text with every run of the same character shortened to one.

"baallooon".collapse_repeats()   # → "balon"

pad_start(width: Int, fill: String = " "): String

The text with fill added at its start until it is width characters long. Text already that long is returned as it was.

"7".pad_start(3, "0")      # → "007"
"long text".pad_start(3)   # → "long text"

Raises when width is negative, or fill is not exactly one character.

pad_end(width: Int, fill: String = " "): String

The text with fill added at its end until it is width characters long.

"hi".pad_end(5, ".")   # → "hi..."

Raises when width is negative, or fill is not exactly one character.

pad_center(width: Int, fill: String = " "): String

The text with fill added on both sides until it is width characters long. When the sides cannot be even, the extra character goes at the end.

"hi".pad_center(5, "-")   # → "-hi--"

Raises when width is negative, or fill is not exactly one character.

Converting

to_int(): Int

The whole number the text spells, such as "42" or "-7". Spaces around it are allowed.

"42".to_int()   # → 42

Raises when the text is not a whole number.

to_int_or(fallback: Int): Int

The whole number the text spells, or fallback when it is not one.

"abc".to_int_or(0)   # → 0

to_int_maybe(): Int?

The whole number the text spells, or nothing when it is not one.

"4.5".to_int_maybe()   # → nothing

to_float(): Float

The number the text spells, which may have a decimal point or an exponent, such as "3.75" or "1e3".

"3.75".to_float()   # → 3.75
"1e3".to_float()    # → 1000.0

Raises when the text is not a number.

to_float_or(fallback: Float): Float

The number the text spells, or fallback when it is not one.

"x".to_float_or(1.5)   # → 1.5

to_float_maybe(): Float?

The number the text spells, or nothing when it is not one.

"x".to_float_maybe()   # → nothing