Development documentation · Some APIs may be unreleased Published release →

Guides

Collections and queries

Choose a collection by the operations you need. Interfaces describe capabilities: Sequence adds count and indexed reads, MutableSequence adds replacement, and List adds growth. A read-only view can still observe changes through another alias.

Choose a collection

Need Implementation Contract
Grow an ordered list ArrayList List / Sequence
Look up values by key HashMap MutableMap / Map
Keep unique elements HashSet MutableSet / Set
First-in, first-out work ArrayQueue Queue
Last-in, first-out work ArrayStack Stack
Lowest-priority work (development) PriorityArrayQueue Explicit Comparer

These are ordinary mutable collections, not concurrent collections. Struct elements are copied; class elements retain shared identity. Collection constructors accept iterables for initialization or copying where the contract provides that overload.

Priority ordering (development)

PriorityArrayQueue<TElement, TPriority> stores an array-backed min-heap. Supply an explicit Comparer<TPriority>, or wrap a comparison callback in FunctionComparer<TPriority>. Peek and Dequeue return Optional<TElement>; PeekPriority exposes the leading priority. Equal priorities have unspecified order.

let queue = PriorityArrayQueue<int, int>(
    FunctionComparer<int>((left, right) => left.CompareTo(right)))
queue.Enqueue(30, 30)
queue.Enqueue(10, 10)
let next = queue.Dequeue() // Some(10)

This pattern is covered by the built-in collection tests. Enqueue and dequeue use O(log n) comparisons, with no per-entry wrapper objects. Capacity can be reserved; removal clears references and Clear retains storage for reuse. See the API contract.

Use capabilities

func Read(values: Sequence<int>) {
    WriteLine(values.Count)
    WriteLine(values[0])
    WriteLine(values.ToList().Count)
}

func Replace(values: MutableSequence<int>, value: int) {
    values[0] = value
}

func Append(values: List<int>) {
    values.Add(11)
}

The complete sample reads arrays and lists, replaces elements through MutableSequence and grows a List. Download it.

Fluent mutable access

map.Entry(key).AndModify(value => value + 1).OrInsert(2) modifies an existing value or inserts the fallback. OrInsertWith evaluates its factory only when absent. The reusable handle resolves current map state on each operation and exposes no storage reference. set.GetOrInsert(candidate) returns the stored equivalent element or inserts the candidate, preserving stored identity. These extensions target MutableMap and MutableSet; they add no synchronization or atomicity.

See member contracts and callback rules.

Recoverable slicing

Array ranges now return borrowed Slice<T> values; ToArray requests a copy. ArrayList range operations still return owned arrays. The former Sliceable<TSlice> interface has been removed because its Result-based contract does not fit borrowed views. Growable collections need explicit invalidation rules before exposing them. See the view contract.

Filter and transform

Import the query operators to compose iterable work:

import System.Linq.*
import System.Console.*

func Main() {
    let values: int[] = [1, 2, 3]
    let query = values.Filter(value => value != 2)
        .Map(value => value * 10)

    for value in query {
        WriteLine(value)
    }
}

Filter and Map correspond to .NET LINQ's Where and Select. Lazy operators defer work until iteration; ToList and ToMap materialize a new collection. Any and All short-circuit. First and Last return Optional; Single returns a Result that distinguishes empty and multiple matches.

Complete query example · Query API

Index and slice carefully

Bracket access is a convenience that can fault on invalid indexes or ranges. Checked Get and Slice methods return Optional or Result. ArrayList provides its own indexing and slice implementation; Sequence access uses the appropriate capability or its iterator fallback. A slice owns independent array storage with shallow-copied elements. No concurrent snapshot is promised.

Arrays · Index and Range contracts

Map keys and comparison

A Map iterates deconstructable KeyValuePair records. MutableMap supports assignment; reading a missing key through an indexer can fault, so prefer checked lookup when presence is uncertain. HashMap can initialize from key/value pairs. Selector-based ToMap builds keys and values from input elements; duplicate behavior is explicit in the selected API.

Use a comparer whose equality and hash rules agree. For strings, StringComparer.Ordinal is an exact policy; OrdinalIgnoreCase supplies consistent case-insensitive comparison and hashing. Avoid changing a key in ways that affect equality while it is stored.

Collection API · String comparison · Optional and Result

Structural data composition

Tuples combine values, unions represent alternatives, and intersections describe simultaneous nominal contracts. These are runtime types with native signatures and introspection, not implicit interface conformance. Tuple element names are retained, while compatibility remains positional. Arrays have a structural runtime shape and a nominal Array<T> representation of the same storage.

The integrated implementation covers bounded native forms; further structural work is parked. Open-generic combinations and broader backend coverage remain incomplete. Use the individual contracts to check supported storage, calls and reflection before relying on a composition. Function types have their own supported API.

Structural families · Tuple contract · Union contract · Intersection contract

Interface variance

Iterable<out T>, Iterator<out T>, Collection<out T> and Sequence<out T> permit compatible reference views. AsyncIterable and AsyncIterator also declare out T. Comparer<in T> and EqualityComparer<in T> consume compatible reference arguments. A mutable collection can expose a wider read-only interface while its writable interface stays invariant.

Raven imports and emits these annotations into native metadata. The runtime keeps nominal conformance explicit; variance does not box elements or widen Result values. Mutable collections and array storage remain invariant. Generic metadata must remain available independently of native executable specialization.

Variance follows explicit nominal interfaces, including those inherited through imported class bases. Compatible producer and consumer views preserve reference identity for classes, interfaces, arrays and strings. For example, an array can widen to its declared Iterable contract without changing its invariant element storage. Strings can expose Object or Iterable<Character> views without copying UTF-8 bytes. Reverse and unrelated conversions are rejected.

See the variance reference for conversion rules, costs and backend limits.

Generic inheritance and constraints

Generic base signatures preserve their arguments through native metadata and host introspection. Raven's neoCLR target supports local and external constructed bases, including reordered parameters, recursive arguments such as Node<T> : Base<Node<T>>, and separately compiled dependencies. Classes remain invariant; inherited interface conformance comes from explicit nominal contracts.

Inherited storage and generic interface dispatch support value and reference arguments. Concrete and abstract generic bases support local and imported virtual slots and direct base calls. Generic virtual methods remain unsupported. Base-constructor expressions support scalar constants and arithmetic; helper calls and control flow remain backend gaps.

Native dependency imports preserve reference/value/default-constructor requirements and nongeneric nominal class bounds. Constrained methods, constructed/interface bounds and external source-bound authoring have remaining gaps. Result variance remain postponed.