Strings

String Literals
String Interpolation
Equality
Comparisons
Concatenating
Iterating
Indexing
Containment
Methods

A string, str, is an immutable array of bytes.

$str(arg: any) -> str

Stringifies the argument — i.e. returns its default string representation. If the argument has a $str() method, the output of this method will be returned.

Note that calling $str() on an f64 prints its value to 6 decimal digits of precision, stripping trailing zeros after the decimal point.

Pyro strings have methods that let you manipulate them as ASCII or as UTF-8 but the string type itself is agnostic about its encoding — a string can contain any sequence of byte values including null bytes or invalid UTF-8.

String Literals

String literals come in two flavours — regular (double-quoted) and raw (backticked). Both can contain arbitrary byte sequences, including literal newlines.

Regular string literals use double quotes:

var foo = "a string";

var bar = "a string
with multiple
lines";

Regular string literals process the following backslashed escapes:

`\\`	backslash
`\0`	null byte
`\"`	double quote
`\'`	single quote
`\$`	dollar symbol
`\b`	backspace
`\e`	escape
`\n`	newline
`\r`	carriage return
`\t`	tab
`\x##`	8-bit hex-encoded byte value
`\u####`	16-bit hex-encoded unicode code point (output as UTF-8)
`\U########`	32-bit hex-encoded unicode code point (output as UTF-8)

Raw string literals use backticks:

var foo = `a raw string`;

var bar = `a raw string
with multiple
lines`;

Raw string literals ignore backslashed escapes. The only character a raw string literal can't contain is a backtick as this would end the string.

String Interpolation

You can interpolate the value of an expression into a double-quoted string using ${}, e.g.

var value = "xyz";
assert "abc ${value} def" == `abc xyz def`;
assert "abc ${value:to_upper()} def" == `abc XYZ def`;

You can interpolate the value of any expression into a string using ${}. If the value of the expression isn't a string, it will be automatically stringified — this is equivalent to calling $str() on the value, e.g.

var value = 123;
assert "abc ${value} def" == `abc 123 def`;
assert "abc ${value + 1} def" == `abc 124 def`;

You can backslash-escape a $ symbol in a double-quoted string to prevent it being treated as the opening of an interpolated expression, e.g.

var value = 123;
assert "abc \${value} def" == `abc ${value} def`;

Interpolated expressions can be nested arbitrarily — i.e. an interpolated expression can contain a double-quoted string containing an interpolated expression containing a double-quoted string containing an interpolated expression, etc.

You can format the value of an interpolated expression by supplying a format-specifier after a semicolon, e.g.

var value = 123;
assert "${value;05d}" == `00123`;

See the string formatting documentation for the syntax of format-specifiers.

Equality

Strings compare as equal using the == operator if they have the same content, e.g.

var foo = "foobar";
var bar = "foobar";
assert foo == bar;

Comparisons

You can compare strings using the comparison operators, <, <=, >, >=, e.g.

assert "abc" < "def";

Strings are compared lexicographically by byte value, e.g.

assert "a" < "aa";
assert "aa" < "aaa";

Concatenating

You can concatenate two strings using the + operator, e.g.

assert "abc" + "def" == "abcdef";

You can multiply a string by an integer n to produce a new string containing n copies of the original, e.g.

assert "foo" * 3 == "foofoofoo"

Iterating

A string is an immutable sequence of bytes. You can iterate over this sequence in three different ways.

You can iterate over a string directly. This iterates over the individual byte values, returning each value as a single-byte string, e.g.

>>> for char in "foo" {
...     echo $debug(char);
... }
"f"
"o"
"o"

You can iterate over the string's byte values as integers using the :bytes() method, e.g.

>>> for byte in "foo":bytes() {
...     echo $debug(byte);
... }
102
111
111

You can iterate over the string's rune values, i.e. UTF-8 encoded Unicode code points, using the :runes() method, e.g.

>>> for rune in "foo":runes() {
...     echo $debug(rune);
... }
'f'
'o'
'o'

Indexing

You can index into a string to get (but not set) individual byte values. Each byte value is returned as a single-byte string, e.g.

assert "foobar"[0] == "f";
assert "foobar"[1] == "o";

Indices are zero-based. A negative index counts backwards from the end of the string, e.g.

assert "foobar"[-1] == "r";
assert "foobar"[-2] == "a";

Use the :byte() method to access individual byte values as integers, e.g.

assert "foobar":byte(0) == 102;
assert "foobar":byte(1) == 111;

Use the :rune() method to access individual UTF-8 encoded code points, e.g.

assert "foobar":rune(0) == 'f';
assert "foobar":rune(1) == 'o';

Containment

You can check if a string contains a substring using the in operator:

assert "foo" in "foobar";

You can also use the in operator to check if a string contains a rune:

assert 'b' in "foobar";

This is equivalent to calling the string's :contains() method.

Methods

:byte(index: i64) -> i64

Returns the byte value at index as an integer in the range [0, 255].

A negative index counts backwards from the end of the string.

:byte_count() -> i64

Returns the number of bytes in the string.

:bytes() -> iter[i64]

Returns an iterator over the string's individual byte values, returning each value as an integer.

:contains(target: str|rune) -> bool

Returns true if the string contains the substring or (UTF-8 encoded) rune target.

(Note that every string contains the empty string "" as the empty string is a valid substring of every string.)

:count() -> i64

Returns the number of bytes in the string. This method is an alias for :byte_count().

:ends_with(suffix: str) -> bool

Returns true if the string ends with the string suffix, otherwise false.

:index_of(target: str) -> i64|err
:index_of(target: str, start_index: i64) -> i64|err

Returns the byte index of the next matching instance of the string target. Starts searching at start_index, which defaults to 0 if not specified. Returns an err if target is not found.

:is_ascii() -> bool

Returns true if the string contains only byte values in the range [0, 127].