(std mutable vec)

Reference

Overview

In-place growable array backed directly by .NET List<T>.

(import (std mutable vec))

(def v (mutablevec))
(mutablevec-add! v 3)
(mutablevec-add! v 1)
(mutablevec-add! v 2)
(mutablevec-sort! v)
(mutablevec-ref v 0)       ; 1
(mutablevec-set! v 0 10)
(mutablevec-pop! v)        ; (Some 3)
(mutablevec->list v)       ; (10 2)

(MutableVec a) directly aliases .NET List<T>. It provides a contiguous backing array that doubles its capacity when full. Index lookups, updates, and appending at the end run in O(1) amortized time. Inserting or removing elements at arbitrary indices takes O(n) time. Foreign interop via import/extern taking List<T> accepts MutableVec directly.

Mutability. Operations such as mutablevec-add! mutate the vector in place and return unit. All references to the vector observe the changes immediately. In contrast, Vec is an immutable, persistent collection.

Comparison to builders. Unlike VecBuilder and ListBuilder (which only support appending and produce immutable collections upon completion), MutableVec allows arbitrary indexed writes, in-place sorting, and removals.

Indexing. Indices are 0-based. Out-of-bounds access with mutablevec-ref, mutablevec-set!, mutablevec-insert!, or mutablevec-remove-at! raises System.ArgumentOutOfRangeException. Use mutablevec-try-ref to return Option safely. mutablevec-pop! returns None on an empty vector without raising.

Equality and hashing. Value searches (mutablevec-contains?, mutablevec-index-of, mutablevec-remove!) use .NET’s default equality comparer (EqualityComparer<T>.Default), which resolves to Bjolang’s Eq for Bjolang types. Two vectors are = if they contain equal elements in the same order. Because vectors are mutable, eq-hash raises an exception to prevent mutable vectors from being used as hash map keys.

Iteration. Iterating via Iterable (e.g. for-each or (:for x v)) checks the count dynamically. Modifying the vector during iteration via mutablevec->seq raises System.InvalidOperationException.

Thread safety. Vectors are not thread-safe. Concurrent reads are safe if no writes occur, but concurrent mutations require external synchronization.

Traits. Implements Refable with an integer index, Iterable, Collection, Addable!, Eq, Written and Displayed.

See also: MutableVec, mutablevec, mutablevec-add!, mutablevec-ref, mutablevec-pop!

Reference

Types

Functions

Types

MutableVec

type alias ↑ Types

In-place growable array of %a (aliases .NET List<T>).

%a
The element type.

See also: mutablevec, vec->mutablevec, Vec

Functions

mutablevec

function ↑ Functions

(: mutablevec (-> (MutableVec %a)))

Creates an empty mutable vector.

returns
A new empty vector.

See also: mutablevec-with-capacity, list->mutablevec

mutablevec-with-capacity

function ↑ Functions

(: mutablevec-with-capacity (-> int (MutableVec %a)))

Creates an empty mutable vector with preallocated capacity.

capacity
Initial capacity before reallocation is required. Must be >= 0.
returns
A new empty vector.
raises System.ArgumentOutOfRangeException
When capacity is negative.

Use this when the expected element count is known in advance to avoid repeated array reallocations.

See also: mutablevec

mutablevec-length

function ↑ Functions

(: mutablevec-length (-> (MutableVec %a) int))

Returns the number of elements in a vector.

v
The vector.
returns
The element count.

See also: mutablevec-empty?

mutablevec-empty?

function ↑ Functions

(: mutablevec-empty? (-> (MutableVec %a) bool))

Tests if a vector contains no elements.

v
The vector.
returns
#t if the vector is empty, otherwise #f.

See also: mutablevec-length

mutablevec-ref

function ↑ Functions

(: mutablevec-ref (-> (MutableVec %a) int %a))

Returns the element at the specified index.

v
The vector.
i
Zero-based index. Must be less than length.
returns
The element at index i.
raises System.ArgumentOutOfRangeException
When i is negative or >= length.

See also: mutablevec-try-ref, mutablevec-set!, ref

mutablevec-try-ref

function ↑ Functions

(: mutablevec-try-ref (-> (MutableVec %a) int (out %a) (Option %a)))

Returns the element at an index, or None if the index is out of bounds.

v
The vector.
i
Zero-based index.
returns
(Some x) if index i is valid, otherwise None.

See also: mutablevec-ref, try-ref

mutablevec-set!

function ↑ Functions

(: mutablevec-set! (-> (MutableVec %a) int %a void))

Replaces the element at the specified index.

v
The vector to modify.
i
Zero-based index. Must be less than length.
x
The new element value.
raises System.ArgumentOutOfRangeException
When i is negative or >= length.

Does not expand the vector’s length. Use mutablevec-add! or mutablevec-insert! to add elements.

See also: mutablevec-ref, mutablevec-insert!

mutablevec-add!

function ↑ Functions

(: mutablevec-add! (-> (MutableVec %a) %a void))

Appends an element to the end of a vector.

v
The vector to modify.
x
The element to append.

O(1) amortized. When full, the underlying array doubles in capacity.

See also: mutablevec-add-all!, mutablevec-insert!, mutablevec-pop!

mutablevec-add-all!

function ↑ Functions

(: mutablevec-add-all! (-> (MutableVec %a) (Seq %a) void))

Appends all elements from a sequence to the end of a vector.

v
The vector to modify.
xs
The elements to append.

See also: mutablevec-add!

mutablevec-insert!

function ↑ Functions

(: mutablevec-insert! (-> (MutableVec %a) int %a void))

Inserts an element at the specified index, shifting subsequent elements.

v
The vector to modify.
i
Zero-based index, from 0 to length inclusive. Inserting at length appends.
x
The element to insert.
raises System.ArgumentOutOfRangeException
When i is negative or greater than length.

Runs in O(n) time proportional to the number of elements shifted after index i.

See also: mutablevec-add!, mutablevec-remove-at!

mutablevec-remove-at!

function ↑ Functions

(: mutablevec-remove-at! (-> (MutableVec %a) int void))

Removes the element at the specified index, shifting subsequent elements.

v
The vector to modify.
i
Zero-based index. Must be less than length.
raises System.ArgumentOutOfRangeException
When i is negative or >= length.

Runs in O(n) time proportional to the number of elements shifted after index i.

See also: mutablevec-insert!, mutablevec-remove!, mutablevec-pop!

mutablevec-remove!

function ↑ Functions

(: mutablevec-remove! (-> (MutableVec %a) %a bool))

Removes the first occurrence of an element matching a value.

v
The vector to modify.
x
The value to find and remove.
returns
#t if an element was found and removed, otherwise #f.

See also: mutablevec-remove-at!, mutablevec-remove-where!, mutablevec-index-of

mutablevec-remove-where!

function ↑ Functions

(: mutablevec-remove-where! (-> (MutableVec %a) (-> %a bool) int))

Removes all elements satisfying a predicate.

v
The vector to modify.
pred
Predicate function returning #t to remove an element.
returns
The number of elements removed.
(mutablevec-remove-where! v (fun (x) (< x 0)))   ; remove negative numbers

Executes in a single pass over the vector, maintaining the relative order of remaining elements.

See also: mutablevec-remove!

mutablevec-pop!

function ↑ Functions

(: mutablevec-pop! (-> (MutableVec %a) (out %a) (Option %a)))

Removes and returns the last element of a vector, or None if empty.

v
The vector to modify.
returns
(Some x) containing the last element, or None if the vector was empty.
;; Use the vector as a stack.
(let loop ()
  (match (mutablevec-pop! stack)
    (None unit)
    ((Some x) (visit x) (loop))))

See also: mutablevec-add!

mutablevec-clear!

function ↑ Functions

(: mutablevec-clear! (-> (MutableVec %a) void))

Removes all elements from a vector.

v
The vector to clear.

Retains allocated buffer capacity so subsequent appends do not require immediate reallocation.

mutablevec-contains?

function ↑ Functions

(: mutablevec-contains? (-> (MutableVec %a) %a bool))

Tests if a vector contains an element matching a value.

v
The vector to search.
x
The value to locate.
returns
#t if a matching element is found, otherwise #f.

Runs in O(n) time, scanning forward until the first match.

See also: mutablevec-index-of

mutablevec-index-of

function ↑ Functions

(: mutablevec-index-of (-> (MutableVec %a) %a int))

Returns the 0-based index of the first occurrence of a value, or -1.

v
The vector to search.
x
The value to locate.
returns
The zero-based index of the first match, or -1 if not found.

Returns -1 rather than Option to avoid heap allocation.

See also: mutablevec-contains?, mutablevec-remove-at!

mutablevec-reverse!

function ↑ Functions

(: mutablevec-reverse! (-> (MutableVec %a) void))

Reverses the order of elements in place.

v
The vector to reverse.

mutablevec-sort!

function ↑ Functions

(: mutablevec-sort! (-> (MutableVec %a) void))
(mutablevec-sort! xs)

Sorts a vector in place in ascending order using Ord. Stable.

xs
The vector to sort.

Performs a stable sort: equal elements maintain their relative positions.

See also: mutablevec-sort-by!, compare

mutablevec-sort-by!

function ↑ Functions

(: mutablevec-sort-by! (-> (MutableVec %a) (-> %a %a int) void))

Sorts a vector in place using a custom comparison function. Stable.

v
The vector to sort.
cmp
Comparison function returning negative if a < b, 0 if equal, and positive if a > b.
(mutablevec-sort-by! v (fun (a b) (compare b a)))   ; sort descending

Performs a stable sort preserving the order of equal elements. Uses insertion sort on 16-element runs combined with merge passes and a temporary buffer.

See also: mutablevec-sort!

mutablevec-copy

function ↑ Functions

(: mutablevec-copy (-> (MutableVec %a) (MutableVec %a)))

Creates a shallow copy of a vector.

v
The vector to copy.
returns
A new vector with identical elements. Does not clone elements.

See also: mutablevec->vec

list->mutablevec

function ↑ Functions

(: list->mutablevec (-> (List %a) (MutableVec %a)))
(list->mutablevec xs)

Constructs a new vector containing the elements of a list in order.

xs
The source list.
returns
A new mutable vector.

See also: mutablevec->list

mutablevec->list

function ↑ Functions

(: mutablevec->list (-> (MutableVec %a) (List %a)))
(mutablevec->list xs)

Converts a vector’s elements into a list in order.

xs
The source vector.
returns
A new list.

See also: list->mutablevec

vec->mutablevec

function ↑ Functions

(: vec->mutablevec (-> (Vec %a) (MutableVec %a)))
(vec->mutablevec v)

Constructs a new mutable vector from a persistent Vec.

v
The source persistent vec.
returns
A new mutable vector.

See also: mutablevec->vec

mutablevec->vec

function ↑ Functions

(: mutablevec->vec (-> (MutableVec %a) (Vec %a)))
(mutablevec->vec xs)

Converts a mutable vector into an immutable persistent Vec.

xs
The source vector.
returns
A new persistent Vec. Subsequent modifications to xs do not affect it.

See also: vec->mutablevec

seq->mutablevec

function ↑ Functions

(: seq->mutablevec (-> (Seq %a) (MutableVec %a)))

Constructs a new vector from a sequence in order.

xs
The source sequence.
returns
A new mutable vector.

See also: mutablevec->seq

mutablevec->seq

function ↑ Functions

(: mutablevec->seq (-> (MutableVec %a) (Seq %a)))

Views a vector as a sequence without copying.

v
The source vector.
returns
The vector itself viewed as a Seq.

Wraps the live vector directly. Modifying the vector while iterating over this sequence causes iteration to raise System.InvalidOperationException. To snapshot elements beforehand, use mutablevec->list or mutablevec->vec.

See also: seq->mutablevec, mutablevec->list

mutablevec->array

function ↑ Functions

(: mutablevec->array (-> (MutableVec %a) (Array %a)))

Copies the elements of a vector into a new .NET array.

v
The source vector.
returns
A newly allocated .NET array.

See also: mutablevec->vec

mutablevec->str

function ↑ Functions

(: mutablevec->str (-> (MutableVec %a) string))
(mutablevec->str xs)

Deprecated: use displayed. Formats a vector as text in the form #mvec(a b c).

xs
The vector to format.
returns
String representation formatted using displayed for each element.
(displayed (list->mutablevec (list 1 2 3)))   ; "#mvec(1 2 3)"

The same text as displayed gives for a mutable vector. Provided for human-readable display; no reader macro parses this representation.