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.

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

Methods

`(index) index`

Strings accept Range values for slicing by byte position:

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"

This returns a new string. Slice boundaries must still fall on valid UTF-8 boundaries. Omitted start means 0, omitted end means the string length, and negative endpoints count from the end. Indexes the value.

`(iter)()`

Returns an iterator.

`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.

Example

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

Distinct from trim_end, which is about whitespace generally and takes an optional character set:

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

Iter.chomp lifts this over an iterator — it is exactly .map do |x| x.chomp(), with the mapping done inline.

`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")

`graphemes() -> Iterable[Str]`

Returns an immutable view of the string's extended grapheme clusters.

The view has the same indexing, slicing, iteration, spreading, and destructuring operations as scalars. It keeps combining sequences and emoji sequences together.

Example

let graphemes = "é👩‍💻".graphemes()
assert_eq $graphemes.len 2
assert_eq [...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"

`len() -> Int`

Returns the byte length of the string.

Example

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

`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 … -> Iter[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

`scalars() -> Iterable[Str]`

Returns an immutable view of the string's Unicode scalar values.

The view supports len, positive and negative indexing, contiguous range slicing, iteration, spreading, and positional destructuring. Elements and slices are strings. Its operations do not change the byte-oriented behavior of Str.len or string indexing.

Example

let scalars = "Aé".scalars()
assert_eq $scalars.len 3
assert_eq [...scalars] ["A", "e", "́"]
assert_eq $scalars[-1] "́"

`split delimiter … -> Iter[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"