7.4 Strings🔗ℹ

A string is a sequence of Unicode characters. A string works with map-referencing […] to access a character via #%index. A string also works with the ++ operator to append strings, but a +& can be used to append strings with the static guarantee that the result is a string. A string can be used as sequence, in which case it supplies its characters in order.

Although Racket supports mutable strings, the String annotation recognizes only immutable strings, and Rhombus operations generate immutable strings. Some operations allow mutable strings as input, and ReadableString recognizes both mutable and immutable strings.

Two strings are equal by is_now as long as they have equal contents, even if one is mutable and the other is immutable.

Strings are comparable, which means that generic operations like < and > work on strings.

Static information associated by String, etc., makes an expression acceptable as a sequence to for in static mode.

The string form of a value corresponds to the way that print would print, which means that strings, symbols, identifiers, and keywords convert as their character content in the default #'text mode.

The repr function is a shorthand for to_string with ~mode: #'expr.

For converting a syntax object to a string, see also Syntax.to_source_string.

> to_string(10)

"10"

> to_string('hello')

"hello"

> to_string([1, 2, 3])

"[1, 2, 3]"

> to_string('hello', ~mode: #'expr)

"'hello'"

The value is coerced to a string in the same way as by to_string.

> "hello" +& "world"

"helloworld"

> "it goes to " +& 11

"it goes to 11"

> "the list " +& [1, 2, 3] +& " has " +& 3 +& " elements"

"the list [1, 2, 3] has 3 elements"

> String.append()

""

> String.append("this")

"this"

> String.append("this", " and ", "that")

"this and that"

> String.make(5, Char"x")

"xxxxx"

> String.length("hello")

5

> "hello".length()

5

> "abc"[0] +& "abc".get(0)

"aa"

When given one argument, rge is used to derive start and end. The rge range is first canonicalized in the sense of Range.canonicalize, then 0 or str.length() is added as the starting or ending point if rge lacks one (i.e., rge.start() or rge.end() is #neginf or #inf). The derived range’s starting and ending points are then taken as start and end.

> String.substring("hello", 2, 4)

"ll"

> "hello".substring(2..=4)

"llo"

> "hello".substring(2..)

"llo"

> "hello".substring(..4)

"hell"

> "hello".substring(..)

"hello"

> String.contains("howdy", "how")

#true

> "howdy".contains("how")

#true

> "howdy".contains("nope")

#false

> "say howdy".find("how")

4

> "say howdy".find("nope")

#false

> "say howdy".starts_with("say")

#true

> "say howdy".ends_with("dy")

#true

> String.replace("Hello", "l", "x")

"Hexlo"

> String.replace("Hello", "l", "x", ~all: #true)

"Hexxo"

> String.join(["Hello", "World"])

"Hello World"

> String.join(["lions", "tigers", "bears"], ", ", ~before_last: ", and ")

"lions, tigers, and bears"

If trim is true, then the result list never starts or ends with an empty string. Otherwise, an instance of sep at the start or end of str implies an empty-string result.

The repeat argument is relevant only when sep is a string instead of a regexp. When repeat is true, then sep is converted to a pattern that matches one or more consecutive instances of sep.

> "Hello  World".split()

["Hello", "World"]

> "Hello  World".split(" ")

["Hello", "", "World"]

> "Hello  World".split(" ", ~repeat: #true)

["Hello", "World"]

> "Hello  World".split(rx'upper')

["ello  ", "orld"]

> "Hello  World".split(rx'upper', ~trim: #false)

["", "ello  ", "orld"]

The repeat argument is relevant only when sep is a string instead of a regexp. When repeat is true, then sep is converted to a pattern that matches one or more consecutive instances of sep.

> "  Hello World  ".trim()

"Hello World"

> "  Hello World  ".trim(~start: #false)

"  Hello World"

> "  Hello World  ".trim(~end: #false)

"Hello World  "

> "_Hello World__".trim("_")

"Hello World_"

> "_Hello World__".trim("_", ~repeat: #true)

"Hello World"

> "hello".utf8_bytes()

#"hello"

> String.to_int("-42")

-42

> String.to_int("42.0")

String.to_int: string does not parse as an integer

string: "42.0"

> String.maybe_to_int("42.0")

#false

> String.to_int("forty-two")

String.to_int: string does not parse as an integer

string: "forty-two"

> String.maybe_to_int("forty-two")

#false

> "100".to_int()

100

> "100".maybe_to_int()

100

The String.to_int converter annotation is satisfied by an immutable string that can be converted to an integer via String.to_int, and it converts to that integer.

> def n :: String.to_int = "-42"

> n

-42

> def m :: String.to_int && Int.in(0, 40) = "-42"

def: value does not satisfy annotation

value: "-42"

annotation: String.to_int && Int.in(0, 40)

> String.to_number("-42")

-42

> String.to_number("42.0")

42.0

> String.to_number("forty-two")

String.to_number: string does not parse as a number

string: "forty-two"

> String.maybe_to_number("forty-two")

#false

> "3/4".to_number()

3/4

> "3/4".maybe_to_number()

3/4

The String.to_number converter annotation is satisfied by an immutable string that can be converted to a number via String.to_number, and it converts to that number.

> def n :: String.to_number = "42.0"

> n

42.0

The start and end arguments must be valid indices as for String.substring.

The start and end arguments must be valid indices as for String.substring.

> def s = "apple"

> s.copy()

String.copy("apple")

> s.copy() is_now s

#true

As always for a veneer, StringCI and ReadableStringCI work only in static mode (see use_static) to help ensure that they have the intended effect.

> "apple" < "BANANA"

#false

> ("apple" :: StringCI) < ("BANANA" :: StringCI)

#true