Strings
Immutable byte strings, explicit formatting, and independent copies.
String values#
A string is an immutable, heap-backed sequence of i8 bytes. len(text) reports the number of bytes in the string and is the usual way to ask for its length. The .length, .capacity, and .size properties currently report that same byte count for a string, but len(text) states the intention more clearly. Indexing reads a signed byte and checks bounds. Equality compares all bytes, including embedded NUL bytes.
Immutability applies to the bytes of a string value. You can still assign a new string to a string variable, and += constructs and assigns a concatenation. Neither operation grants permission to mutate the original byte storage through an index. This distinction matters when several variables began with equal text.
Strings compare by content, not by allocation address. Two independently created strings with the same bytes are equal. A byte count is useful for output and storage, but it is not necessarily the number of characters a person sees because a Unicode character can use several UTF-8 bytes, and a visible character can contain more than one Unicode scalar value. For text consisting only of ASCII characters, each character occupies one byte.
Strings also support <, <=, >, and >=. Ordering compares unsigned bytes from left to right. The first differing byte decides the order. If one string is an exact byte prefix of the other, the shorter string comes first. It is case-sensitive, includes embedded NUL bytes, and performs no locale collation or Unicode normalization.
greeting := "Hello, Ocean!";
length := len(greeting);
same := greeting == "Hello, Ocean!";
greeting += "\n";
The initial value has thirteen bytes, and same is true. Appending a newline replaces greeting with a new value containing one extra byte. A previous copy of the string would still contain its original text.
Unicode and escapes#
Source identifiers support Unicode 16.0 identifier characters. Strings encode Unicode escapes as UTF-8. A character literal represents one Unicode scalar value, rather than one UTF-8 byte. This differs from indexing a string, which reads a byte. Indexing and range on a string still work on bytes, not user-perceived characters.
A source file is read as UTF-8. Common escapes include \n for a newline, \t for a tab, \" for a quote, and \\ for a backslash. Unicode escapes specify a scalar value that is encoded into one or more UTF-8 bytes in the resulting string. Invalid UTF-8 and invalid scalar escapes are rejected.
Keep byte operations separate from character operations. For example, indexing a non-ASCII string may read only one byte of a multi-byte encoding. It is not a Unicode character decoder, and a range loop over a string does not change that fact.
text := "A wave: \u2248";
line := "first\nsecond";
quote := "say \"hello\"";
The first string contains the approximately-equal symbol (≈). The second contains an actual newline between two words; it does not contain a literal backslash followed by n. The last string contains double quotes around hello.
Mutable bytes#
Convert or assign a string to i8[] to obtain an independent mutable copy. Replacing a string allocates a new value; you cannot write its elements or call dynamic array mutation methods on it.
A byte array is the appropriate representation when an algorithm needs to change individual bytes. The conversion from a string gives the array its own storage, so mutations do not affect the source string. Converting the array back to a string also makes an independent value.
This is useful when preparing writable data for a native API or when performing an explicitly byte-oriented transformation. It does not make arbitrary edits to UTF-8 safe: changing one byte inside a multi-byte sequence can still produce invalid encoded text.
text := "Ocean";
bytes: i8[] = text;
bytes[0] = 'o';
// text is still "Ocean".
Only the first byte of bytes changes. The original text remains "Ocean", while the mutable array now contains the bytes for "ocean". Both owned values are cleaned up when their scopes end.
Formatting output#
The io package uses {} placeholders for template formatting. A template such as "Depth: {} meters" supplies its own punctuation and spaces. io.Sprintf returns Result<string>: a formatted string on success, or an error if the placeholder and argument counts differ. io.Sprint instead converts values directly to a plain string, with no template.
For direct output, io.Print writes converted values and io.Println adds a newline. These conversion functions insert a space only between two adjacent non-string arguments. Include spaces explicitly when combining strings and numbers, or use a template with io.Printf or io.Printfln.
Choose the formatting function according to where the result should go. io.Printfln writes formatted text and a newline to standard output. io.Sprintf builds a string for later use, which is useful when constructing a message without printing it immediately.
A pair of braces consumes one argument in order. The template supplies punctuation, units, and spacing. This is usually easier to read than assembling a message through several concatenations, especially when the values are numbers or other non-string types.
import "io";
// Inside a function:
io.Printfln("Depth: {} meters", 42);
message := io.Sprintf("Hello, {}!", "Ocean").unwrap();
The printed line is Depth: 42 meters. The second call stores Hello, Ocean! in message; it produces no output by itself. Import io at the top of any source file that uses these qualified names.