String

// A view borrows, so it can never outlive the bytes it looks at. Text that a function builds
// and hands back, or that must be kept after its source is gone, needs an owner. That is
// `String`: it keeps its own copy of the bytes, in memory it asked an allocator for, and gives
// that memory back in its destructor when the value's life ends.
//
// Asking for memory can fail, and so can checking that bytes are UTF-8, so the calls that
// make a `String` return `String ! TextError`. `Main` is fallible here, and `?` passes any such
// failure on. The allocator itself is the subject of the Memory part; for now it is simply
// where a String's bytes come from.
import Allocator::{ Allocator, SystemAllocator };
import Io::PrintLine;
import Text::{ String, TextError };

// The reversed letters exist only in this function's array, which is gone once it returns. A
// view of them would be left pointing at nothing, so the function returns a String that owns
// a copy. `FromBytes` checks the bytes are text before copying them, and that check matters
// here: reversed byte by byte, "né" puts the two bytes of `é` in the wrong order, and the
// call fails with `TextError::InvalidUtf8`. The array has room for words of up to 16 bytes.
func Reversed(allocator: Allocator, word: char8[..]) -> String ! TextError {
    var letters: char8[16];
    for i in 0..word.length {
        letters[i] = word[word.length - 1 - i];
    }
    return String::FromBytes(allocator, letters[..word.length]);
}

func Main() -> ! TextError {
    var system = SystemAllocator();
    let allocator: Allocator = system;

    var word = Reversed(allocator, "stressed")?;
    PrintLine("word   {}, {} bytes", word, word.Length());

    // `Clone` makes an independent copy with storage of its own. Replacing the original's text
    // afterwards leaves the clone exactly as it was.
    let saved = word.Clone()?;
    word.ReplaceWith(Reversed(allocator, "drawer")?);
    PrintLine("word   {}", word);
    PrintLine("saved  {}", saved);

    // `let copy = saved;` would also copy, but plain assignment has no way to report failure,
    // so it ends the program if memory runs out. `Clone` hands that failure back as a
    // `TextError` instead, which is why it is the one to use when failure must be handled.

    // A String lends out a view whenever borrowed text is enough, without copying anything.
    let view = saved.View();
    PrintLine("view   {}, {} characters", view, view.ScalarCount());

    // No cleanup is written: `word` and `saved` each release their own memory at the end of
    // `Main`, as the Destructor lesson promised.
}