Str

Strings are immutable sequences of UTF-8 bytes.

Implements: Index[Range[Int], Str]

Constructor

`Str value`

Accepts a string or decodes UTF-8 binary data. The lowercase str function instead returns the general-purpose textual representation of any value.

Parameters

Name	Type	Description
`value`	`Value`

Errors

DataError if binary data is not valid UTF-8.

assert_eq (Str b"hello") "hello"
assert_eq (str 42) "42"

Fields

len @ Int ^[get]

Returns the byte length of the string.

Example

assert_eq $"hello".len 5
assert_eq $"".len 0

Methods

`(index) range -> Str`

Returns the bytes in a range as a new string.

assert_eq $"abcd"[1..3] "bc"
assert_eq $"abcd"[..2] "ab"
assert_eq $"abcd"[2..] "cd"
assert_eq $"abcd"[..] "abcd"
assert_eq $"foobar"[-3..] "bar"

The range must lie within the string, and its endpoints must fall on UTF-8 character boundaries. Omitted start means 0, omitted end means the string length, and negative endpoints count from the end.

Parameters

Name	Type	Description
`range`	`Range[Int]`

`chomp() -> Str`

Removes one trailing line terminator.

One complete terminator — \r\n or \n, never a lone \r — and nothing else. A string without one is returned unchanged. Distinct from trim_end, which is about whitespace generally and takes an optional character set. Iterable.chomp does the same to each item of an iterable.

Example

assert_eq ("line\n".chomp()) "line"
assert_eq ("line\r\n".chomp()) "line"
assert_eq ("line".chomp()) "line"
assert_eq ("z  \n".chomp()) "z  "
assert_eq ("z  \n".trim_end()) "z"

`contains needle -> Bool`

Tests whether the string contains the given substring.

Parameters

Name	Type	Description
`needle`	`Str`	the substring to find

Example

assert ("foobar".contains "foo")
assert ("foobar".contains "bar")
assert (!"foobar".contains "baz")
assert ("foobar".contains "")  # empty string is always contained

`ends_with suffix -> Bool`

Tests whether the string ends with the given suffix.

Parameters

Name	Type	Description
`suffix`	`Str`	the suffix string

Example

assert ("foobar".ends_with "bar")

`grapheme_bounds() -> UnpackIter[Int]`

Iterates over the string's grapheme boundary byte offsets.

Each offset starts the corresponding fragment in graphemes, followed by the string's byte length. An empty string yields only 0. Destructuring reads from the current position without advancing the iterator.

Example

let s = "Aé"
let bounds = [...s.grapheme_bounds()]
assert_eq $s[bounds[1]..bounds[-1]] "é"

`graphemes() -> UnpackIter[Str]`

Iterates over the string's extended grapheme clusters.

Keeps combining sequences and emoji sequences together. Destructuring reads from the current position without advancing the iterator. Materialize [...s.graphemes()] for positional access.

Example

assert_eq [..."é👩‍💻".graphemes()] ["é", "👩‍💻"]

`join … -> Str`

Joins values from an input source using this string as a separator.

Parameters

Name	Type	Description
`iter?`	`Iterable[Value]`	iterable to join; uses the default input when omitted

Example

assert_eq (",".join ["a", "b", "c"]) "a,b,c"

`lower() -> Str`

Returns the string converted to lowercase.

Example

assert_eq ("HELLO".lower()) "hello"
assert_eq ("Hello World".lower()) "hello world"

`repeat count -> Str`

Returns the string repeated count times.

Parameters

Name	Type	Description
`count`	`Int`	non-negative repetition count

Example

assert_eq ("ab".repeat 3) "ababab"
assert_eq ("ab".repeat 0) ""

`replace from to -> Str`

Returns a new string with all non-overlapping occurrences of from replaced with to.

Parameters

Name	Type	Description
`from`	`Str`	substring to replace
`to`	`Str`	replacement string

Example

assert_eq ("foo bar foo".replace "foo" "baz") "baz bar baz"
assert_eq ("banana".replace "na" "") "ba"
assert_eq ("abc".replace "" "-") "-a-b-c-"

`rsplit delimiter … -> UnpackIter[Str]`

Like split, but yields segments in right-to-left order (rightmost segment first).

Parameters

Name	Type	Description
`delimiter`	`Str`	the delimiter string
`:limit?`	`Int`	Maximum splits; negative values split from the left.

`:limit`

limit: N splits at most N times from the right; the last element yielded is the unsplit left remainder.
limit: -N splits at most N times from the left, but still yields segments right-to-left.
Omitted splits fully with no limit.

Example

assert_eq [..."a,b,c".rsplit ","] ["c", "b", "a"]
assert_eq [..."a,b,c".rsplit "," limit: 1] ["c", "a,b"]

# Negative limit: split from the left, yield right-to-left
assert_eq [..."a,b,c".rsplit "," limit: -1] ["b,c", "a"]

`scalar() -> Int`

Returns the Unicode scalar value encoded by a single-scalar string.

Errors

Raises ValueError if the string contains zero or multiple Unicode scalar values.

Example

assert_eq ("A".scalar()) 65
assert_eq ("😀".scalar()) 128512

`scalar_bounds() -> UnpackIter[Int]`

Iterates over the string's scalar boundary byte offsets.

Each offset starts the corresponding fragment in scalars, followed by the string's byte length. An empty string yields only 0. Destructuring reads from the current position without advancing the iterator.

Example

let s = "Aé"
let bounds = [...s.scalar_bounds()]
assert_eq $s[bounds[1]..bounds[-1]] "é"

`scalars() -> UnpackIter[Str]`

Iterates over the string's Unicode scalar values.

Destructuring reads from the current position without advancing the iterator. Materialize [...s.scalars()] for positional access.

Example

assert_eq [..."Aé".scalars()] ["A", "e", "́"]

`split delimiter … -> UnpackIter[Str]`

Splits the string by the delimiter, returning an iterator that yields segments in left-to-right order.

Parameters

Name	Type	Description
`delimiter`	`Str`	the delimiter string
`:limit?`	`Int`	Maximum splits; negative values split from the right.

`:limit`

limit: N (positive) splits at most N times from the left; the last element is the unsplit remainder.
limit: -N (negative) splits at most N times from the right, but still yields segments left-to-right. This is useful for splitting off a known-length suffix such as a file extension.
Omitted splits fully with no limit.

Example

assert_eq [..."a,b,c".split ","] ["a", "b", "c"]
assert_eq [..."a,b,c".split "," limit: 1] ["a", "b,c"]

# Negative limit: split from the right, yield left-to-right
let base ext = "archive.tar.gz".split "." limit: -1
assert_eq $base "archive.tar"
assert_eq $ext "gz"

Open in playground

`starts_with prefix -> Bool`

Tests whether the string starts with the given prefix.

Parameters

Name	Type	Description
`prefix`	`Str`	the prefix string

Example

assert ("foobar".starts_with "foo")
assert (!("foobar".starts_with "bar"))

`trim … -> Str`

Removes whitespace (or specified characters) from both ends.

Parameters

Name	Type	Description
`chars?`	`(Str \| Iterable[Str])`

Example

assert_eq ("  hello  ".trim()) "hello"
assert_eq ("xxhelloxx".trim "x") "hello"
assert_eq ("xyhelloyx".trim ["x", "y"]) "hello"

`trim_end … -> Str`

Removes whitespace (or specified characters) from the end.

Parameters

Name	Type	Description
`chars?`	`(Str \| Iterable[Str])`

Example

assert_eq ("  hello  ".trim_end()) "  hello"
assert_eq ("xxhelloxx".trim_end "x") "xxhello"

`trim_start … -> Str`

Removes whitespace (or specified characters) from the start.

Parameters

Name	Type	Description
`chars?`	`(Str \| Iterable[Str])`

Example

assert_eq ("  hello  ".trim_start()) "hello  "
assert_eq ("xxhelloxx".trim_start "x") "helloxx"

`upper() -> Str`

Returns the string converted to uppercase.

Example

assert_eq ("hello".upper()) "HELLO"
assert_eq ("Hello World".upper()) "HELLO WORLD"

`without_prefix prefix -> Str`

Returns the string with the prefix removed if it matches, otherwise returns the original string.

Parameters

Name	Type	Description
`prefix`	`Str`	the prefix to remove

Example

assert_eq ("foobar".without_prefix "foo") "bar"
assert_eq ("foobar".without_prefix "baz") "foobar"

`without_suffix suffix -> Str`

Returns the string with the suffix removed if it matches, otherwise returns the original string.

Parameters

Name	Type	Description
`suffix`	`Str`	the suffix to remove

Example

assert_eq ("foobar".without_suffix "bar") "foo"