Collections

std.collections contains owned data structures. The current public containers are Array<T> and HashMap<K, V>.

import {
    Array
} from std.collections;

fn main() {
    let values = Array<i32>();
    try values.append(10);
    try values.append(32);

    assert values.length == 2;
    assert values[0] == 10;
}

Array<T> owns or borrows contiguous storage, tracks length and capacity, and grows through an allocator. It can store copyable or move-only elements.

append, prepend, pop, remove, clear, reserve, shrink, drop, slice, count, index, and [] work for all T. Default iteration borrows elements as const &T.

import {
    Array
} from std.collections;
import {
    String
} from std.string;

fn main() {
    let values = Array<String>();

    try values.append(try String("alpha"));
    try values.prepend(try String("zero"));
    assert values.length == 2;

    let popped = values.pop();
    assert popped != null;
}

Copy-style operations add method-local T: Copy bounds:

Method	Bound	Purpose
copy_iter	T: Copy	Iterate by copied values.
extend	T: Copy	Copy all items from another array.
clone	T: Copy	Copy the array and backing storage.

count and index use caller-supplied equality. This keeps the container from choosing a default equality rule for user structs.

import {
    Array
} from std.collections;

fn same(a: const &i32, b: const &i32) -> bool {
    return *a == *b;
}

fn main() {
    let values = Array<i32>();
    try values.append(1);
    try values.append(2);
    try values.append(2);
    let two = 2;

    assert values.count(&two, same) == 2;
    assert values.index(&two, (a, b) => *a == *b) != null;
}

HashMap<K, V> stores owned keys and values. Its constructor requires explicit hash and equality functions for keys.

import {
    HashMap
} from std.collections;

fn hash_i32(key: const &i32) -> u64 {
    return (*key) as u64;
}

fn eq_i32(a: const &i32, b: const &i32) -> bool {
    return *a == *b;
}

fn main() {
    let map = HashMap<i32, i32>(hash_i32, eq_i32);

    assert (try map.put(1, 10)) == null;
    let one = 1;
    assert map.contains(&one);
    assert map.get(&one) != null;

    let old = try map.put(1, 20);
    assert old != null;

    let removed = map.remove(&one);
    assert removed != null;
    assert !map.contains(&one);
}

put(key, value) inserts or replaces an entry and returns the replaced value as V? throws(AllocError). contains, get, and remove take explicit const &K key borrows. get(key) returns const &V?. remove(key) drops the stored key and returns the owned value as V?. drop() releases the map storage and consumes all remaining owned keys and values.

Type	Public fields	Main methods
Array<T>	length, capacity	append, prepend, reserve, shrink, remove, pop, clear, drop, count, index, slice, iter, copy_iter, extend, clone, []
ArrayIter<T>	none	next() -> const &T?
ArrayCopyIter<T: Copy>	none	next() -> T?
HashMap<K, V>	length, capacity	put, get, contains, remove, reserve, clear, drop

The current HashMap surface does not include get_mut, entry APIs, borrowed-key lookup, default hashers, or stable iteration order.

See Move, Copy, and Clone for element ownership rules.