package hector

The type of a vector.

A synonym for the type of a vector.

An integer value of type length represents the length of a sequence. For example, it can be the length of an array, the length of a vector, or the length of a segment of an array of vector. A length is nonnegative.

An integer value of type capacity represents the capacity of a vector. A capacity is nonnegative.

An integer value of type index represents an index into a sequence of elements.

create() creates a new vector of length 0 and capacity 0.

make n x creates a new vector of length n and capacity n and initializes this vector by storing the value x everywhere. n must be a valid capacity.

init n f creates a new vector of length n and capacity n and initializes it, from left to right, by computing and storing the value f i at index i. n must be a valid capacity.

copy v creates a new vector whose length and capacity are length v and initializes it with a copy of the data stored in the vector v.

sub v i n produces a new vector whose elements are the elements of the vector segment determined by vector v, index i, and length n. i and n must describe a valid segment of the vector v.

concat vs produces a new vector whose sequence of elements is the concatenation of the sequences of elements of the vectors in the list vs.

get v i fetches the element that lies at index i in the vector v. i must be comprised in the semi-open interval [0, length v).

set v i x overwrites the element that lies at index i in the vector v with the value x. i must be comprised in the semi-open interval [0, length v).

If the vector v is nonempty, top v returns its last element. If the vector v is empty, top v raises Not_found.

get_last is a synonym for top.

If the vector v is nonempty, top_opt v returns its last element. If the vector v is empty, top_opt v returns None.

find_last is a synonym for top_opt.

fill v i n x writes the value x into every slot of the vector segment determined by vector v, index i, and length n. i and n must describe a valid segment of the vector v.

blit v i v' i' n copies data from the vector segment determined by vector v, index i, and length n into the vector segment determined by vector v', index i', and length n. It works correctly even if the source and destination segments overlap. i and n must describe a valid segment of the vector v. i' and n must describe a valid segment of the vector v'.

unsafe_get v i fetches the element that lies at index i in the vector v. i must be comprised in the semi-open interval [0, length v). No bounds check is performed. If the index i is out of bounds, memory safety can be compromised. Use at your own risk!

unsafe_set v i x overwrites the element that lies at index i in the vector v with the value x. i must be comprised in the semi-open interval [0, length v). No bounds check is performed. If the index i is out of bounds, memory safety can be compromised. Use at your own risk!

unsafe_borrow v returns the data array that is part of the internal representation of the vector v. The length of this data array is at least length v, and can be greater than length v. Beyond this guarantee, the length of this data array is unspecified; it is not necessarily the capacity of the vector. As long as the vector v is not modified by other means, the segment of the data array delimited by the semi-open interval [0, length v) can be safely read and written.

push v x extends the vector v with the element x. The length of the vector v is increased by one. If necessary, the capacity of the vector v is increased.

add_last is a synonym for push.

push_array v a extends the vector v with the elements of the array a. The length of the vector v is increased by the length of the array a. If necessary, the capacity of the vector v is increased.

append_array is a synonym for push_array.

push_array_segment v a i n extends the vector v with the elements of the array segment determined by array a, index i, and length n. The length of the vector v is increased by n. If necessary, the capacity of the vector v is increased. i and n must describe a valid segment of the array a.

append_array_segment is a synonym for push_array_segment.

push_vector v v' extends the vector v with the elements of the vector v'. The length of the vector v is increased by the length of the array v'. If necessary, the capacity of the vector v is increased.

append is a synonym for push_vector.

push_list v xs extends the vector v with the elements of the list xs. The length of the vector v is increased by the length of the list xs. If necessary, the capacity of the vector v is increased.

append_list is a synonym for push_list.

push_seq v xs extends the vector v with the elements of the sequence xs. The length of the vector v is increased by the length of the sequence xs. If necessary, the capacity of the vector v is increased. The sequence xs is demanded just once.

append_seq is a synonym for push_seq.

push_iter v iter c pushes each element of the collection c in turn onto the vector v. The function iter is used to iterate over the elements of c. In other words, push_iter v iter c is equivalent to iter (push v) c.

append_iter is a synonym for push_iter.

If the vector v is nonempty, pop v removes and returns its last element. The length of the vector is decreased by one; its capacity is unchanged. If the vector v is empty, pop v raises Not_found.

pop_last is a synonym for pop.

If the vector v is nonempty, pop_opt v removes and returns its last element. The length of the vector is decreased by one; its capacity is unchanged. If the vector v is empty, pop_opt v returns None.

pop_last_opt is a synonym for pop_opt.

If the vector v is nonempty, drop v removes its last element. If the vector v is empty, drop v has no effect. drop v is equivalent to if is_empty v then () else ignore (pop v).

remove_last is a synonym for drop.

iter f v applies the function f in turn, from left to right, to each element x of the vector v.

iter_down f v applies the function f in turn, from right to left, to each element x of the vector v.

iteri f v applies the function f in turn, from left to right, to each index i and corresponding element x of the vector v.

fold_left f s v applies the function f in turn, from left to right, to each element x of the vector v. A state, whose initial value is s, is threaded through this sequence of function invocations, and is eventually returned.

fold_right f v s applies the function f in turn, from right to left, to each element x of the vector v. A state, whose initial value is s, is threaded through this sequence of function invocations, and is eventually returned.

map f v applies the function f in turn, from left to right, to each element x of the vector v, and constructs a new vector of the results of these calls.

mapi f v applies the function f in turn, from left to right, to each index i and corresponding element x of the vector v, and constructs a new vector of the results of these calls.

filter f v applies the function f in turn, from left to right, to each element x of the vector v, and constructs a new vector containing just the elements x such that f x returned true.

filter_map f v applies the function f in turn, from left to right, to each element x of the vector v, and constructs a new vector containing just the values y such that f x returned Some y.

exists f v determines whether at least one element x of the vector v satisfies the predicate f. The vector is scanned from left to right.

for_all f v determines whether all elements x of the vector v satisfy the predicate f. The vector is scanned from left to right.

find f v finds the leftmost element x of the vector v such that f x is true, and returns its index. If no such element exists, then find f v raises Not_found.

Provided eq is an equality on elements, equal eq is the pointwise equality of vectors. In other words, equal eq v v' determines whether the sequences of elements of the vectors v and v' are pointwise equal, using the function eq to test whether two elements are equal.

Provided cmp is a preorder on elements, compare cmp is the lexicographic preorder on vectors. In other words, compare cmp v v' compares the sequences of elements of the vectors v and v', according to the lexicographic preorder, and using the function cmp to compare two elements.

Caution: compare behaves like List.compare, not like Dynarray.compare. Dynarray.compare implements a preorder on vectors that is not is the lexicographic preorder.

sort cmp v sorts the vector v, in place, according to the preorder cmp.

sort is currently a synonym for stable_sort.

stable_sort cmp v sorts the vector v, in place, according to the preorder cmp. This is a stable sort: if two elements are equivalent according to cmp then their relative order in the sequence is preserved. This is a merge sort algorithm; it is the same algorithm as in Array.stable_sort.

fast_sort cmp v sorts the vector v, in place, according to the preorder cmp.

fast_sort is currently a synonym for stable_sort.

of_array a returns a new vector whose elements are the elements of the array a. The length and capacity of the new vector are the length of the array a.

of_list xs returns a new vector whose elements are the elements of the list xs. The length and capacity of the new vector are the length of the list xs.

of_seq xs returns a new vector whose elements are the elements of the sequence xs. The length and capacity of the new vector are the length of the sequence xs.

to_array v creates a new array whose elements are the elements of the vector v. The length of the new array is the length of the vector v.

to_list v creates a new list whose elements are the elements of the vector v. The length of the new list is the length of the vector v.

to_seq v creates a sequence whose elements are the elements of the vector v. The length of this sequence is the length of the vector v. This sequence can be demanded as many times as one wishes. However, this sequence is valid only as long as the vector v is not modified. As soon as v is modified, this sequence must no longer be used.

to_seq_rev v creates a sequence whose elements are the elements of the vector v, in reverse order. The length of this sequence is the length of the vector v. This sequence can be demanded as many times as one wishes. However, this sequence is valid only as long as the vector v is not modified. As soon as v is modified, this sequence must no longer be used.

show f v returns a textual representation of the contents of the vector v. The user-supplied function f is used to obtain a textual representation of each element.

length v is the (logical) length of the vector v.

s_empty v is equivalent to length v = 0.

If n is less than length v, then truncate v n sets the length of the vector v to n. Otherwise, nothing happens. In either case, the capacity of the vector v is unchanged. This is a constant-time operation.

clear v is equivalent to truncate v 0. The length of the vector v becomes zero. Its capacity is unchanged.

reset v sets the length and the capacity of the vector v to zero.

ensure_capacity v c ensures that the capacity of the vector v is at least c. If necessary, the capacity of the vector v is increased.

ensure_extra_capacity v delta ensures that the capacity of the vector v is at least length v + delta. If necessary, the capacity of the vector v is increased. The increment delta must be nonnegative.

fit_capacity v ensures that the capacity of the vector v matches its length. If necessary, the capacity of the vector v is decreased.

set_capacity v c ensures that the capacity of the vector v is exactly c. If c is less than length v, then the vector v is truncated: some elements are lost. Otherwise, the elements of the vector v are preserved, and its capacity is decreased or increased as necessary.

This module offers the same API as the standard library module Stdlib.Stack, but is implemented using vectors.