String v0.1.0

An immutable, heap-allocated string.

Package: Text

Struct

struct String {
    data:   *char8;
    length: uint;
}

A String owns the block of length bytes behind data and never writes to it again: every transformation below returns a fresh String and leaves the receiver untouched. The fields are an implementation detail — read them with Data and Length.

The bytes are not terminated by a null, and length counts bytes rather than characters, so a multi-byte UTF-8 sequence counts for more than one.

Ownership

Assignment copies the struct, not the block, so two String values can name the same allocation. Take Clone when both of them have to be freed, and pass each one to Free exactly once. The empty String owns no block, which is why New allocates nothing and Free can be called on anything this package returns.

Because each transformation allocates, + in a loop is a chain of allocations. Accumulate with a StringBuilder instead.

Methods

Construction

Method	Description
`New`	Creates an empty string, without allocating.
`From`	Creates a string by copying a literal or a buffer.
`Clone`	Returns an independent copy, with its own block.
`Free`	Releases the block the string owns.

Accessors

Method	Description
`Data`	The pointer to the underlying bytes.
`Length`	The length in bytes.
`IsEmpty`	Whether the string holds no bytes.
`At`	The byte at an index.

Comparison

Method	Description
`Equals`	Whether two strings hold the same bytes. Also `==` and `!=`.

Search

Method	Description
`StartsWith`	Whether the string opens with a prefix.
`EndsWith`	Whether the string closes with a suffix.
`IndexOf`	The offset of the first match, or `-1`.
`Contains`	Whether a substring occurs anywhere.

Transformation

Each returns a new String and leaves the receiver unchanged.

Method	Description
`+`	Joins two strings, or a string and a literal.
`Substring`	A copy of the bytes in a range.
`ToUpper`	A copy with ASCII letters uppercased.
`ToLower`	A copy with ASCII letters lowercased.
`Trim`	A copy with surrounding whitespace dropped.
`Repeat`	A copy of the contents laid down N times.

Example

import Io::PrintLine;
import Text::String;

func Main() -> int {
    var greeting = String::From("Hello, Rux!");
    var needle = String::From("Rux");

    PrintLine(greeting.Length());        // 11
    PrintLine(greeting.Contains(needle)); // true
    PrintLine(greeting.IndexOf(needle));  // 7

    var shout = greeting.ToUpper(); // "HELLO, RUX!"

    shout.Free();
    needle.Free();
    greeting.Free();
    return 0;
}