6.26 Strings

8.14.0.2

6.26 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 guaratee 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.

The . operator can be used on a string expression as equivalent to calling String functions:

str.append(str2, ...)
is
String.append(str, str2, ...)
str.length()
is
String.length(str)
str.get(n)
is
String.get(str, n)
str.substring(arg, ...)
is
String.substring(str, arg, ...)
str.contains(substr)
is
String.contains(str, substr)
str.utf8_bytes(arg, ...)
is
String.utf8_bytes(str, arg, ...)
str.latin1_bytes(arg, ...)
is
String.latin1_bytes(str, arg, ...)
str.locale_bytes(arg, ...)
is
String.locale_bytes(str, arg, ...)
str.to_int()
is
String.to_int(str)
str.to_number()
is
String.to_number(str)
str.to_string()
is
String.to_string(str)
str.upcase(arg)
is
String.upcase(str, arg)
str.downcase(arg)
is
String.downcase(str, arg)
str.foldcase(arg)
is
String.foldcase(str, arg)
str.titlecase(arg)
is
String.titlecase(str, arg)
str.normalize_nfd()
is
String.normalize_nfd(str)
str.normalize_nfkd()
is
String.normalize_nfkd(str)
str.normalize_nfc()
is
String.normalize_nfc(str)
str.normalize_nfkc()
is
String.normalize_nfkc(str)
str.grapheme_span(arg, ...)
is
String.grapheme_span(str, arg, ...)
str.grapheme_count(arg, ...)
is
String.grapheme_count(str, arg, ...)
str.to_sequence()
is
String.to_sequence(str)
str.copy()
is
String.copy(str)
str.snapshot()
is
String.snapshot(str)

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.

annotation

String

annotation

ReadableString

annotation

ReadableString.to_string

Matches strings. The ReadableString annotation allows mutable Racket strings as well as immutable Rhombus strings. The ReadableString.to_string converter annotation allows the same strings as ReadableString, but converts a mutable Racket string to an immutable Rhombus string.

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

function

fun to_string(v :: Any,

~mode: mode :: PrintMode = #'text) :: String

function

fun repr(v :: Any) :: String

The to_string function coerces v to a string.

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'"

operator

operator ((v1 :: Any) +& (v2 :: Any)) :: String

Coerces v1 and v2 to a string, then appends the strings.

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"

function

fun String.append(str :: ReadableString, ...) :: String

Appends all strs to create a new string.

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

function

fun String.make(len :: NonnegInt, c :: Char) :: String

Creates a string of length n where every position in the string contains c.

> String.make(5, "x"[0])
"xxxxx"

function

fun String.length(str :: ReadableString) :: NonnegInt

Returns the number of characters in str.

> String.length("hello")
5
> "hello".length()
5

function

fun String.contains(str :: ReadableString,

substr :: ReadableString)

:: Boolean

Checks whether str contains substr as a substring.

> String.contains("howdy", "how")
#true
> "howdy".contains("how")
#true
> String.contains("howdy", "nope")
#false
> "howdy".contains("nope")
#false

function

fun String.get(str :: ReadableString, n :: NonnegInt) :: Char

Equivalent to str[n] (with the default implicit #%index form). Returns the nth character of str (starting from 0).

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

function

fun String.substring(str :: ReadableString,

start :: NonnegInt,

end :: NonnegInt = String.length(str))

:: String

Returns the substring of str from start (inclusive) to end (exclusive).

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

function

fun String.utf8_bytes(str :: ReadableString,

err_byte :: maybe(Byte) = #false,

start :: NonnegInt = 0,

end :: NonnegInt = String.length(str))

:: Bytes

function

fun String.latin1_bytes(str :: ReadableString,

err_byte :: maybe(Byte) = #false,

start :: NonnegInt = 0,

end :: NonnegInt = String.length(str))

:: Bytes

function

fun String.locale_bytes(str :: ReadableString,

err_byte :: maybe(Byte) = #false,

start :: NonnegInt = 0,

end :: NonnegInt = String.length(str))

:: Bytes

Converts a string to a byte string, encoding by UTF-8, Latin-1, or the current locale’s encoding. The err_byte argument provides a byte to use in place of an encoding error, where #false means that an exception is thrown. (No encoding error is possible with String.utf8_bytes, but err_byte is accepted for consistency.)

> "hello".utf8_bytes()
#"hello"

function

fun String.to_int(str :: ReadableString) :: maybe(Int)

Parses str as an integer, returning #false if the string does not parse as an integer, otherwise returning the integer value.

> String.to_int("-42")
-42
> String.to_int("42.0")
#false
> String.to_int("fourty-two")
#false
> "100".to_int()
100

function

fun String.to_number(str :: ReadableString) :: maybe(Number)

Parses str as a number, returning #false if the string does not parse as a number, otherwise returning the number value.

> String.to_number("-42")
-42
> String.to_number("42.0")
42.0
> String.to_number("fourty-two")
#false
> "3/4".to_number()
3/4

function

fun String.to_string(str :: ReadableString)

:: String

function

fun ReadableString.to_string(str :: ReadableString)

:: String

The same as to_string, but constrained to a ReadableString argument. These functions exist for consistency with the ReadableString.to_string annotation.

function

fun String.upcase(str :: ReadableString) :: String

function

fun String.downcase(str :: ReadableString) :: String

function

fun String.foldcase(str :: ReadableString) :: String

function

fun String.titlecase(str :: ReadableString) :: String

Case-conversion functions.

function

fun String.normalize_nfd(str :: ReadableString) :: String

function

fun String.normalize_nfkd(str :: ReadableString) :: String

function

fun String.normalize_nfc(str :: ReadableString) :: String

function

fun String.normalize_nfkc(str :: ReadableString) :: String

Unicode normalization functions.

function

fun String.grapheme_span(str :: ReadableString,

start :: NonnegInt = 0,

end :: NonnegInt = String.length(str))

:: NonnegInt

Returns the number of characters (i.e., code points) in the string that form a Unicode grapheme cluster starting at start, assuming that start is the start of a grapheme cluster and extending no further than the character before end. The result is 0 if start equals end.

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

function

fun String.grapheme_count(str :: ReadableString,

start :: NonnegInt = 0,

end :: NonnegInt = String.length(str))

:: NonnegInt

Returns the number of grapheme clusters in String.substring(str, start, end).

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

function

fun String.to_sequence(str :: ReadableString) :: Sequence

Implements Sequenceable by returning a sequence of str’s characters in order.

function

fun String.copy(str :: ReadableString) :: ReadableString

Creates a mutable copy of str.

> "apple".copy()
String.copy("apple")

function

fun String.snapshot(str :: ReadableString)

:: String

Returns an immutable string as-is or copies a mutable string’s content to an immutable string.

> "apple".copy().snapshot()
"apple"

annotation

StringCI

annotation

ReadableStringCI

A veneer for a string that redirects comparable operations like < and > to case-insensitive comparisons, equivalent to using String.foldcase on each string before comparing.

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

1	Rhombus Essentials
2	Collections and Iteration
3	Syntax Objects and Macros
4	Classes and Interfaces
5	Static Information and Binding
6	Core Reference
7	Meta and Macros Reference
8	Rhombus Static by Default
9	Libraries
10	Naming Conventions

6.1	General Forms
6.2	Definitions
6.3	Namespaces
6.4	Import
6.5	Export
6.6	Functions
6.7	Operators
6.8	Classes and Interfaces
6.9	Veneers
6.10	Mutable Variables and Assignment
6.11	Repetitions
6.12	Block
6.13	Conditionals
6.14	Matching
6.15	Iteration
6.16	Recursion
6.17	Context Parameters
6.18	Exceptions
6.19	Continuations
6.20	Implicit Forms
6.21	Static and Dynamic Lookup
6.22	Modules and Submodules
6.23	Booleans
6.24	Numbers
6.25	Characters
6.26	Strings
6.27	Keywords
6.28	Symbols
6.29	Byte Strings
6.30	Lists
6.31	Pairs and Pair Lists
6.32	Mutable Lists
6.33	Arrays
6.34	Maps
6.35	Sets
6.36	Boxes
6.37	Ranges
6.38	Indexables
6.39	Listables
6.40	Sequences
6.41	Appendables
6.42	Comparables
6.43	Paths
6.44	Source Locations
6.45	Void
6.46	Equality
6.47	Dot
6.48	Multiple Values
6.49	Annotations
6.50	Enumerations
6.51	String Formatting
6.52	Input and Output
6.53	Eval
6.54	Syntax Objects
6.55	Syntax Classes
6.56	Simple Expression Macros
6.57	Unit Testing

str.append(str2, ...)	is	String.append(str, str2, ...)
str.length()	is	String.length(str)
str.get(n)	is	String.get(str, n)
str.substring(arg, ...)	is	String.substring(str, arg, ...)
str.contains(substr)	is	String.contains(str, substr)
str.utf8_bytes(arg, ...)	is	String.utf8_bytes(str, arg, ...)
str.latin1_bytes(arg, ...)	is	String.latin1_bytes(str, arg, ...)
str.locale_bytes(arg, ...)	is	String.locale_bytes(str, arg, ...)
str.to_int()	is	String.to_int(str)
str.to_number()	is	String.to_number(str)
str.to_string()	is	String.to_string(str)
str.upcase(arg)	is	String.upcase(str, arg)
str.downcase(arg)	is	String.downcase(str, arg)
str.foldcase(arg)	is	String.foldcase(str, arg)
str.titlecase(arg)	is	String.titlecase(str, arg)
str.normalize_nfd()	is	String.normalize_nfd(str)
str.normalize_nfkd()	is	String.normalize_nfkd(str)
str.normalize_nfc()	is	String.normalize_nfc(str)
str.normalize_nfkc()	is	String.normalize_nfkc(str)
str.grapheme_span(arg, ...)	is	String.grapheme_span(str, arg, ...)
str.grapheme_count(arg, ...)	is	String.grapheme_count(str, arg, ...)
str.to_sequence()	is	String.to_sequence(str)
str.copy()	is	String.copy(str)
str.snapshot()	is	String.snapshot(str)