Basic collections

abstract object collection[T];
extend type collection[`T] subtypes collection[`S >= T];

collection[T] is a collection of items of some type T (or any subtype of T). A collection of some type T is a subtype of all collections of types that are supertypes of T.

signature length(collection[`T]):int;
method is_empty(c@:collection[`T]):bool;  - length = 0
method non_empty(c@:collection[`T]):bool;  - length > 0
method is_singleton(c@:collection[`T]):bool;  - length = 1
method is_multiple(c@:collection[`T]):bool;  - length > 0

Collections support a length operation (implemented by subclasses) which returns the number of elements in the collection, plus a number of length-related predicates.

signature do(collection[`T], closure:&(T):void):void;

Collections support a number of control structures. Primary among all control structures is the do method that iterates through the collection and invokes an argument closure on each element. Elements are processed in some unspecified order which may vary from invocation to invocation, even if the collection is not modified between finishing one do loop and starting the next. For example:

  myCollection.do(&(elem:elemType){     - bind elem to each element
      ...                               - of myCollection in turn
  });

method do_allowing_updates(t@:collection[`T], closure:&(T):void):void;

The collection cannot be modified while do is active without potentially bizarre results. A related control structure, do_allowing_updates, allows the collection to be modified during the iteration. (The effect of modification during iteration depends on the kind of collection and the kind of update.)

method =_unordered(c1@:collection[`T <= comparable[T]],
                   c2@:collection[T]):bool;
method !=_unordered(c1@:collection[`T <= comparable[T]],
                    c2@:collection[T]):bool;

Two collections of comparable elements can be compared to see if they have the same elements, ignoring order, using =_unordered.

method includes(c@:collection[`T <= comparable[T]], x:T):bool;
method includes_all(c1@:collection[`T <= comparable[T]],
                    c2:collection[T]):bool;
method includes_some(c@:collection[`T], test:&(T):bool):bool;

The includes method computes whether the collection c contains an element which is equal, using =, to x. The includes_all method returns true if c contains elements which are equal to all the elements of c2. The includes_some method returns true if c contains an element which satisfies the predicate test.

method count(c@:collection[`T <= comparable[T]], x:T):int;

The count method returns the number of times an element appears in a collection.

method count_pred(c@:collection[`T], test:&(T):bool):int;

The count_pred method returns the number of elements of the collection c for which the predicate test evaluates to true.

method find(c@:collection[`T], test:&(T):bool):T;
method find(c@:collection[`T], test:&(T):bool, if_absent:&():`S):T|S;

The find method returns an element of collection c satisfying the predicate test.

method every(c@:collection[`T], test:&(T):bool):bool;
method any(c@:collection[`T], test:&(T):bool):bool;

Tests whether the predicate is true of every or any collection element.

method reduce(t@:collection[`T], bin_op:&(T,S):S, init:`S):S;

Implements the classic functional reduce operation over collections.

method reduce(t@:collection[`T], bin_op:&(T,T):T):T;
method reduce_nonempty(t@:collection[`T], bin_op:&(T,T):T):T;
method reduce_nonempty(t@:collection[`T], bin_op:&(T,T):T, if_empty:&():T):T;

Implements a streamlined version that works only on nonempty collections, invoking a closure on an empty collection, and doesn't require an init value.

method min(t@:collection[`T <= ordered[T]]):T;
method min_over_all(t@:collection[`T <= ordered[T]]):T;
method min_over_all(t@:collection[`T <= ordered[T]], if_empty:&():T):T;
method max(t@:collection[`T <= ordered[T]]):T;
method max_over_all(t@:collection[`T <= ordered[T]]):T;
method max_over_all(t@:collection[`T <= ordered[T]], if_empty:&():T):T;
method average(t@:collection[`T <= num]):T;
method average_over_all(t@:collection[`T <= num]):T;
method average_over_all(t@:collection[`T <= num], if_empty:&():T):T;
method total(t@:collection[`T <= num]):T|int;

The min, max, and average methods are defined on collections as well as pairs of values. They are synonyms of the (min|max|average)_over_all methods, which optionally take a closure to handle empty conditions.

method pick_any(c@:collection[`T]):T;
method pick_any(c@:collection[`T1], if_empty:&():`T2):T1|T2;
method only(c@:collection[`T]):T;
method only(c@:collection[`T1], if_non_singleton:&():`T2):T1|T2;
method select(c:collection[`T], pred:&(T):bool):collection[T];
method select_first(c:collection[`T], howmany:int):collection[T];
method select_first(c:collection[`T], hmy:int, pred:&(T):bool):collection[T];
method select_as_m_list(c:collection[`T], howmany:int, pred:&(T):bool
                        ) :m_list[T];
method select_as_array(c:collection[`T], howmany:int, pred:&(T):bool
                       ) :array[T];
method select_as(c:collection[`T], howmany:int, pred:&(T):bool,
                 result:`R <= extensible_sequence[T]
) : R;

The pick_any method returns some element of the collection, invoking if_empty or producing an error if the collection is empty. The only method returns the only element of the argument collection, producing an error or invoking if_non_singleton if the collection has zero or multiple elements.

signature copy(collection[`T]):collection[T];

Collections can be copied. This copy is a shallow copy; the elements of the collection are not copied. If the collection is immutable, the copy function usually returns the collection itself without doing a copy.

method as_ordered_collection(c@:collection[`T]):ordered_collection[T];
method as_m_indexed(c@:collection[`T]):m_indexed[T];
method as_vector(c@:collection[`T]):vector[T];
method as_i_vector(c@:collection[`T]):i_vector[T];
method as_m_vector(c@:collection[`T]):m_vector[T];
method as_byte_vector(c@:collection[int]):byte_vector;
method as_i_byte_vector(c@:collection[int]):i_byte_vector;
method as_m_byte_vector(c@:collection[int]):m_byte_vector;
method as_short_vector(c@:collection[int]):short_vector;
method as_i_short_vector(c@:collection[int]):i_short_vector;
method as_m_short_vector(c@:collection[int]):m_short_vector;
method as_list_set(c@:collection[`T <= comparable[T]]):m_set[T];

Collection conversions may or may not involve a copy, e.g., as_vector on a list copies, while as_vector on a vector does not.

method print_string(c@:collection[`T]):string;
method print(c@:collection[`T]):void;
signature collection_name(collection[`T]):string;
method open_brace(c@:collection[`T]):string;
method close_brace(@:collection[`T]):string;
method elems_print_string(c@:collection[`T]):string;
method elems_print(c@:collection[`T]):void;
method elem_separator(@:collection[`T]):string;
method elem_print_string(t@:collection[`T], elem:T, first:bool):string;
method elem_print(t@:collection[`T], elem:T, first:bool):void;

Various variations on printing a collection are available. The standard print_string behavior includes open_brace, elems_print_string, and then close_brace. By default open_brace contains the name of the collection and an open brace, elems_print_string consists of the elements of the collection, separated by the elem_separator (by default, a comma), and close_brace is a close brace.