Dynamic array

// An inline array, `int32[4]`, carries its length in its type. The compiler fixes it, and the
// elements live wherever the array itself lives — inside a local, a struct, another array.
//
// Sometimes the length is only known once the program runs: a count read from a file, a size
// passed in by a caller. `Collections::Array<T>` is for that case. It asks an allocator for a
// block of the length you choose at run time, and once made, that length never changes. It is
// not a vector: there is no `Push`. A fixed run whose size is decided late is the whole idea.
import Allocator::{ Allocator, SystemAllocator };
import Collections::{ Array, CollectionError };
import Io::{ Print, PrintLine };

// The length arrives as an ordinary parameter. `int32[count]` would be rejected, because an
// inline array's length must be known while compiling; a dynamic array has no such limit.
func Squares(allocator: Allocator, count: uint) -> Array<int32> ! CollectionError {
    // `Filled` makes `count` copies of one value. Asking for memory can fail, hence `?`.
    var squares = Array::Filled<int32>(allocator, count, 0)?;
    for i in 0..count {
        squares.Set(i, (i * i) as int32)?;
    }
    // The array owns its block, so returning it moves the block out to the caller.
    return <-squares;
}

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

    let primes: int32[4] = [2, 3, 5, 7];
    PrintLine("inline length   {}", primes.length);

    var squares = Squares(allocator, 6)?;
    Print("squares        ");
    for value in squares {
        Print(" {}", value);
    }
    PrintLine("   (length {})", squares.Length());

    // `FromSlice` copies an inline array onto the heap. The copy is independent: changing it
    // leaves the original alone.
    var copy = Array::FromSlice<int32>(allocator, primes)?;
    copy.Set(0, 99)?;
    PrintLine("copy[0]         {}, primes[0] still {}", copy.Get(0) ?? -1, primes[0]);

    // Both kinds check an index, but they differ in what a wrong one costs. On an inline array,
    // a constant index past the end does not build, `primes[7]` being "index 7 is out of range
    // for an array of 4 elements", and a computed one stops the program with "Panic: index out
    // of range". A dynamic array's `Get` and `Set` report it in their types instead: `Get`
    // returns `none`, and `Set` fails with `IndexOutOfRange`, so the program decides what to do.
    PrintLine("copy[9]         {}", copy.Get(9) ?? -1);
    copy.Set(9, 1) catch {
        e => { PrintLine("copy.Set(9)     failed: {}", e); }
    };

    // One more difference: an inline array is copied by `=`, but a dynamic array owns its block
    // and cannot be copied. Writing `let other = copy;` is rejected; `let other <- copy;` moves it.
    // When `squares` and `copy` go out of scope, each gives its block back to the allocator.
}