Section Header
    + name := COLLECTION[E];
    - comment := "Common abstract definition of a sequenceable collection of objects.";
Such a collection is traversable using a simple INTEGER index from `lower'
to `upper' using `item'. All COLLECTIONs are resizable thanks to
`add_last' / `remove_last', `add_first' / `remove_first' as well as
`add' / `remove' .
This abstraction provides feature to view a COLLECTION as a stack
(as an example by using `add_last', `last', and `remove_last').
One can also use a COLLECTION as a queue (as an example, by using
`add_last', `first' and `remove_first').
The Lisaac standard library provides five implementations of COLLECTION:
ARRAY, FAST_ARRAY, LINKED_LIST and LINKED2_LIST. Except for creations all
implementations have exactly the same behavior. Switching from one
implementation to another only change the memory used and the execution
time (see header comment of ARRAY, FAST_ARRAY, LINKED_LIST and LINKED2_LIST
for more details).
Section Inherit
- parent_storage:STORAGE := STORAGE;
    - parent_traversable:TRAVERSABLE[E] :=
Section Public
Accessing:
    - item i:INTEGER :E <-
        Item at the corresponding index `i'.
       
        See also `lower', `upper', `valid_index', `put', `swap'.
Writing:
    - put element:E to i:INTEGER <-
        Make `element' the item at index `i'.
       
        See also `lower', `upper', `valid_index', `item', `swap', `force'.
    - swap i1:INTEGER with i2:INTEGER <-
        Swap item at index `i1' with item at index `i2'.
       
        See also `item', `put'.
    - set_all_with v:E <-
        Set all items with value `v'.
       
        See also `set_slice_with'.
    - set_slice lower_index:INTEGER to upper_index:INTEGER with v:E <-
        Set all items in range [`lower_index' .. `upper_index'] with `v'.
       
        See also `set_all_with'.
    - clear_all <-
        Set every item to its default value.
        The `count' is not affected
       
        see also `clear', `all_default'.
Adding:
    - add_first element:E <-
        Add a new item in first position : `count' is increased by
        one and all other items are shifted right.
       
        See also `add_last', `first', `last', `add'.
    - add_last element:E <-
        Add a new item at the end : `count' is increased by one.
       
        See also `add_first', `last', `first', `add'.
    - add element:E to index:INTEGER <-
        Add a new `element' at rank `index' : `count' is increased
        by one and range [`index' .. `upper'] is shifted right
        by one position.
       
        See also `add_first', `add_last', `append_collection'.
    - append_collection other:COLLECTION[E] <-
        Append `other' to Current.
       
        See also `add_last', `add_first', `add'.
Modification:
    - force element:E to index:INTEGER <-
        Make `element' the item at `index', enlarging the collection if
        necessary (new bounds except `index' are initialized with
        default values).
       
        See also `put', `item', `swap'.
    - copy other:SELF <-
        Reinitialize by copying all the items of `other'.
    - from_collection model:COLLECTION[E] <-
        Initialize the current object with the contents of `model'.
Removing:
    - remove_first <-
        Remove the `first' element of the collection.
       
        See also `remove_last', `remove', `remove_head'.
    - remove_head n:INTEGER <-
        Remove the `n' elements of the collection.
       
        See also `remove_tail', `remove', `remove_first'.
    - remove index:INTEGER <-
        Remove the item at position `index'. Followings items
        are shifted left by one position.
       
        See also `remove_first', `remove_head', `remove_tail', `remove_last'.
    - remove_last <-
        Remove the `last' item.
       
        See also `remove_first', `remove', `remove_tail'.
    - remove_tail n:INTEGER <-
        Remove the last `n' item(s).
       
        See also `remove_head', `remove', `remove_last'.
    - clear <-
        Discard all items in order to make it `is_empty'.
       
        See also `clear_all'.
Looking and Searching:
    - has x:E :BOOLEAN <-
        Look for `x' using `equal' for comparison.
       
        See also `fast_has', `index_of', `fast_index_of'.
    - fast_has x:E :BOOLEAN <-
        Look for `x' using basic `=' for comparison.
       
        See also `has', `fast_index_of', `index_of'.
    - first_index_of element:E :INTEGER <-
        Give the index of the first occurrence of `element' using
        `==' for comparison.
        Answer `upper + 1' when `element' is not inside.
       
        See also `fast_first_index_of', `index_of', `last_index_of',
        `reverse_index_of'.
    - index_of element:E start start_index:INTEGER :INTEGER <-
        Using `is_equal' for comparison, gives the index of the first occurrence
        of `element' at or after `start_index'. Answer `upper + 1' when `element'
        when the search fail.
       
        See also `fast_index_of', `reverse_index_of', `first_index_of'.
    - reverse_index_of element:E start start_index:INTEGER :INTEGER <-
        Using `is_equal' for comparison, gives the index of the first occurrence of
        `element' at or before `start_index'. Search is done in reverse direction,
        which means from the `start_index' down to the `lower' index .
        Answer `lower -1' when the search fail.
       
        See also `fast_reverse_index_of', `last_index_of', `index_of'.
    - last_index_of element:E :INTEGER <-
        Using `is_equal' for comparison, gives the index of the last occurrence
        of `element' at or before `upper'. Search is done in reverse direction,
        which means from the `upper' down to the `lower' index . Answer `lower -1'
        when the search fail.
       
        See also `fast_last_index_of', `reverse_index_of', `index_of'.
    - fast_first_index_of element:E :INTEGER <-
        Give the index of the first occurrence of `element' using basic `='
        for comparison. Answer `upper + 1' when `element' is not inside.
       
        See also `first_index_of', `last_index_of', `fast_last_index_of'.
    - fast_index_of element:E start start_index:INTEGER :INTEGER <-
        Using basic `=' for comparison, gives the index of the first occurrence
        of `element' at or after `start_index'. Answer `upper + 1' when `element'
        when the search fail.
       
        See also `index_of', `fast_reverse_index_of', `fast_first_index_of'.
    - fast_reverse_index_of element:E start start_index:INTEGER :INTEGER <-
        Using basic `=' comparison, gives the index of the first occurrence
        of `element' at or before `start_index'. Search is done in reverse
        direction, which means from the `start_index' down to the `lower'
        index . Answer `lower -1' when the search fail.
       
        See also `reverse_index_of', `fast_index_of', `fast_last_index_of'.
    - fast_last_index_of element:E :INTEGER <-
        Using basic `=' for comparison, gives the index of the last occurrence
        of `element' at or before `upper'. Search is done in reverse direction,
        which means from the `upper' down to the `lower' index . Answer `lower -1'
        when the search fail.
       
        See also `fast_reverse_index_of', `last_index_of'.
Looking and comparison:
    - '==' Right 60 other:COLLECTION[E] :BOOLEAN <-
        Do both collections have the same `lower', `upper', and
        items?
        The basic `=' is used for comparison of items.
       
        See also `is_equal_map', `same_items'.
    - is_equal_map other:SELF :BOOLEAN <-
        Do both collections have the same `lower', `upper', and
        items?
        Feature `==' is used for comparison of items.
       
        See also `==', `same_items'.
    - all_default:BOOLEAN <-
        Do all items have their type's default value?
        Note: for non NULL items, the test is performed with the `is_default' predicate.
       
        See also `clear_all'.
    - same_items other:COLLECTION[E] :BOOLEAN <-
        Do both collections have the same items? The basic `=' is used
        for comparison of items and indices are not considered (for
        example this routine may yeld true with `Current' indexed in
        range [1..2] and `other' indexed in range [2..3]).
       
        See also `is_equal_map', `is_equal'.
    - occurrences element:E :INTEGER <-
        Number of occurrences of `element' using `equal' for comparison.
       
        See also `fast_occurrences', `index_of'.
    - fast_occurrences element:E :INTEGER <-
        Number of occurrences of `element' using basic `=' for comparison.
       
        See also `occurrences', `index_of'.
Printing:
    - fill_tagged_out_memory <-
Agents based features:
    - foreach action:BLOCK <-
    - do_all action:BLOCK <-
        Apply `action' to every item of `Self'.
       
        See also `for_all', `exists'.
    - foreach action:BLOCK while test:BLOCK <-
        Apply `action' to every item of `Self' while test is true
    - foreach action:BLOCK until test:BLOCK <-
        Apply `action' to every item of `Self' until test is true
    - foreach action:BLOCK only_if test:BLOCK <-
    - is_all test:BLOCK :BOOLEAN <-
    - for_all test:BLOCK :BOOLEAN <-
        Do all items satisfy `test'?
       
        See also `do_all', `exists'.
    - exists test:BLOCK :BOOLEAN <-
        Does at least one item satisfy `test'?
       
        See also `do_all', `for_all'.
Traditionals features (in functional languages)
    - filter test:BLOCK in other:SELF <-
        Filter all element which `test' element is true
    - fold_left function:BLOCK with element:E :E <-
    - fold_right function:BLOCK with element:E :E <-
Other features
    - replace_all old_value:E with new_value:E <-
        Replace all occurrences of the element `old_value' by `new_value'
        using `equal' for comparison.
       
        See also `fast_replace_all', `move'.
    - fast_replace_all old_value:E with new_value:E <-
        Replace all occurrences of the element `old_value' by `new_value'
        using operator `=' for comparison.
       
        See also `replace_all', `move'.
    - move lower_index:INTEGER to upper_index:INTEGER by distance:INTEGER <-
        Move range `lower_index' .. `upper_index' by `distance'
        positions. Negative distance moves towards lower indices.
        Free places get default values.
       
        See also `slice', `replace_all'.
    - slice min:INTEGER to max:INTEGER :SELF <-
        New collection consisting of items at indexes in [`min'..`max'].
        Result has the same dynamic type as `Current'.
        The `lower' index of the `Result' is the same as `lower'.
       
        See also `from_collection', `move', `replace_all'.
    - reverse <-
        Reverse the order of the elements.
Invariant.
[
-? { lower <= upper + 1 };
];