+
Point of view
All features
deferred class COLLECTION [E_]
Summary
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). See also class QUEUE and STACK.
The Liberty Eiffel standard library provides five implementations of COLLECTION: ARRAY, FAST_ARRAY, RING_ARRAY, LINKED_LIST and TWO_WAY_LINKED_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, RING_ARRAY, LINKED_LIST and TWO_WAY_LINKED_LIST for more details).
Direct parents
Inherit list: SEARCHABLE, STORABLE, TRAVERSABLE
Known children
Inherit list: ARRAY, ARRAYED_COLLECTION, FAST_ARRAY, LINKED_LIST, MACRO_COMMAND, RING_ARRAY, TWO_WAY_LINKED_LIST
Insert list: LINKED_COLLECTION
Class invariant
Overview
Features
Accessing:
{ANY}
Writing:
{ANY}
Adding:
{ANY}
  • add_first (element: ANY)
    Add a new item in first position : count is increased by one and all other items are shifted right.
  • add_last (element: ANY)
    Add a new item at the end : count is increased by one.
  • add (element: ANY, index: INTEGER_32)
    Add a new element at rank index : count is increased by one and range [index .. upper] is shifted right by one position.
  • append_collection (other: COLLECTION[E_])
    Append other to Current.
  • append_traversable (other: TRAVERSABLE[E_])
    Append other to Current.
Modification:
{ANY}
  • force (element: E_, index: INTEGER_32)
    Make element the item at index, enlarging the collection if necessary (new bounds except index are initialized with default values).
  • copy (other: COLLECTION [E_])
    Reinitialize by copying all the items of other.
  • from_collection (model: TRAVERSABLE[ANY])
    Initialize the current object with the contents of model.
Removing:
{ANY}
Looking and Searching:
{ANY}
Looking and comparison:
{ANY}
Other features:
{ANY}
Implement manifest generic creation:
{}
{ANY}
Other features:
{ANY}
Agent-based features:
{ANY}
Printing:
{ANY}
{ANY}
{}
Counting:
{ANY}
Agent-based features:
{ANY}
{}
Indexing:
{ANY}
Accessing:
{ANY}
Looking and Searching:
{ANY}
infix "@" (i: INTEGER_32): E_
frozen
effective function
{ANY}
The infix notation which is actually just a synonym for item.
See also item.
require ensure
  • definition: Result = item(i)
put (element: ANY, i: INTEGER_32) assign item
deferred procedure
{ANY}
Make element the item at index i.
require ensure
swap (i1: INTEGER_32, i2: INTEGER_32)
effective procedure
{ANY}
Swap item at index i1 with item at index i2.
See also item, put.
require ensure
set_all_with (v: ANY)
deferred procedure
{ANY}
Set all items with value v.
See also set_slice_with.
ensure
set_slice_with (v: ANY, lower_index: INTEGER_32, upper_index: INTEGER_32)
effective procedure
{ANY}
Set all items in range [lower_index .. upper_index] with v.
See also set_all_with.
require ensure
clear_all
effective procedure
{ANY}
Set every item to its default value.
The count is not affected.
See also clear, all_default.
ensure
add_first (element: ANY)
deferred procedure
{ANY}
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.
ensure
add_last (element: ANY)
deferred procedure
{ANY}
Add a new item at the end : count is increased by one.
See also add_first, last, first, add.
ensure
add (element: ANY, index: INTEGER_32)
deferred procedure
{ANY}
Add a new element at rank index : count is increased by one and range [index .. upper] is shifted right by one position.
require ensure
append_collection (other: COLLECTION[E_])
effective procedure
{ANY}
Append other to Current.
This feature is obsolete: Use `append_traversable' instead.
append_traversable (other: TRAVERSABLE[E_])
effective procedure
{ANY}
Append other to Current.
See also add_last, add_first, add.
require
  • other /= Void
ensure
force (element: E_, index: INTEGER_32)
deferred procedure
{ANY}
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.
require ensure
copy (other: COLLECTION [E_])
deferred procedure
{ANY}
Reinitialize by copying all the items of other.
require
    • not immutable
    • same_dynamic_type(other)
      • not immutable
      • same_dynamic_type(other)
      • not immutable
      • same_dynamic_type(other)
ensure
  • is_equal(other)
from_collection (model: TRAVERSABLE[ANY])
deferred procedure
{ANY}
Initialize the current object with the contents of model.
require
  • model /= Void
  • useful_work: model /= Current
ensure
remove_first
deferred procedure
{ANY}
Remove the first element of the collection.
require ensure
remove_head (n: INTEGER_32)
deferred procedure
{ANY}
Remove the n elements of the collection.
require ensure
remove (index: INTEGER_32)
deferred procedure
{ANY}
Remove the item at position index.
Followings items are shifted left by one position.
See also remove_first, remove_head, remove_tail, remove_last.
require ensure
remove_last
deferred procedure
{ANY}
Remove the last item.
require ensure
remove_tail (n: INTEGER_32)
deferred procedure
{ANY}
Remove the last n item(s).
require ensure
clear_count
deferred procedure
{ANY}
Discard all items (is_empty is True after that call).
If possible, the actual implementation supposed to keep its internal storage area in order to refill Current in an efficient way.
See also clear_count_and_capacity.
ensure
clear_count_and_capacity
deferred procedure
{ANY}
Discard all items (is_empty is True after that call).
If possible, the actual implementation supposed to release its internal storage area for this memory to be used by other objects.
See also clear_count.
ensure
has (x: ANY): BOOLEAN
effective function
{ANY}
Look for x using is_equal for comparison.
ensure
  • definition: Result = valid_index(first_index_of(x))
fast_has (x: ANY): BOOLEAN
effective function
{ANY}
Look for x using basic = for comparison.
See also has, fast_index_of, index_of.
ensure
  • definition: Result = valid_index(fast_first_index_of(x))
last_index_of (element: ANY): INTEGER_32
effective function
{ANY}
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.
ensure
  • definition: Result = reverse_index_of(element, upper)
fast_last_index_of (element: ANY): INTEGER_32
effective function
{ANY}
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.
ensure
  • definition: Result = fast_reverse_index_of(element, upper)
fast_is_equal (other: COLLECTION [E_]): BOOLEAN
deferred function
{ANY}
Do both collections have the same lower, upper, and items?
The basic = is used for comparison of items.
See also is_equal, same_items.
ensure
is_equal (other: COLLECTION [E_]): BOOLEAN
deferred function
{ANY}
Do both collections have the same lower, upper, and items?
Feature is_equal is used for comparison of items.
See also fast_is_equal, same_items.
require
    • other /= Void
      • other /= Void
      • other /= Void
ensure
  • Result implies lower = other.lower and upper = other.upper
  • commutative: generating_type = other.generating_type implies Result = other.is_equal(Current)
is_equal_map (other: COLLECTION [E_]): BOOLEAN
effective function
{ANY}
Do both collections have the same lower, upper, and items?
This feature is obsolete: Use `is_equal' instead.
all_default: BOOLEAN
deferred function
{ANY}
Do all items have their type's default value?
Note: for non Void items, the test is performed with the is_default predicate.
See also clear_all.
same_items (other: COLLECTION[E_]): BOOLEAN
effective function
{ANY}
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 yield True with Current indexed in range [1..2] and other indexed in range [2..3]).
See also is_equal, fast_is_equal.
require
  • other /= Void
ensure
occurrences (element: ANY): INTEGER_32
deferred function
{ANY}
Number of occurrences of element using is_equal for comparison.
ensure
  • Result >= 0
fast_occurrences (element: ANY): INTEGER_32
deferred function
{ANY}
Number of occurrences of element using basic = for comparison.
See also occurrences, index_of.
ensure
  • Result >= 0
replace_all (old_value: ANY, new_value: ANY)
deferred procedure
{ANY}
Replace all occurrences of the element old_value by new_value using is_equal for comparison.
See also fast_replace_all, move.
ensure
fast_replace_all (old_value: ANY, new_value: ANY)
deferred procedure
{ANY}
Replace all occurrences of the element old_value by new_value using basic = for comparison.
See also replace_all, move.
ensure
move (lower_index: INTEGER_32, upper_index: INTEGER_32, distance: INTEGER_32)
effective procedure
{ANY}
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.
require ensure
slice (min: INTEGER_32, max: INTEGER_32): COLLECTION [E_]
deferred function
{ANY}
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.
require ensure
reverse
deferred procedure
{ANY}
Reverse the order of the elements.
ensure
manifest_semicolon_check: BOOLEAN
is False
constant attribute
{}
manifest_put (index: INTEGER_32, element: ANY)
deferred procedure
{}
require
  • index >= 0
enumerate: ENUMERATE[E_]
effective function
{ANY}
new_iterator: ITERATOR[E_]
deferred function
{ANY}
ensure
get_new_iterator: ITERATOR[E_]
frozen
effective function
{ANY}
This feature is obsolete: Use `new_iterator' instead. This historical SmartEiffel feature is badly named.
for_each (action: PROCEDURE[TUPLE[TUPLE 1[E_]]])
effective procedure
{ANY}
Apply action to every item of Current.
See also for_all, exists, aggregate.
require
  • action /= Void
for_all (test: FUNCTION[TUPLE[TUPLE 1[E_]]]): BOOLEAN
effective function
{ANY}
Do all items satisfy test?
See also for_each, exists, aggregate.
require
  • test /= Void
exists (test: FUNCTION[TUPLE[TUPLE 1[E_]]]): BOOLEAN
effective function
{ANY}
Does at least one item satisfy test?
See also for_each, for_all, aggregate.
require
  • test /= Void
aggregate (action: FUNCTION[TUPLE[TUPLE 2[E_, E_], E_]], initial: E_): E_
effective function
{ANY}
Aggregate all the elements starting from the initial value.
See also for_each, for_all, exists.
require
  • action /= Void
out_in_tagged_out_memory
effective procedure
{ANY}
Append terse printable representation of current object in tagged_out_memory.
require
  • locked: tagged_out_locked
ensure
  • still_locked: tagged_out_locked
  • not_cleared: tagged_out_memory.count >= old tagged_out_memory.count
  • append_only: old tagged_out_memory.twin.is_equal(tagged_out_memory.substring(1, old tagged_out_memory.count))
generation: INTEGER_32
writable attribute
{ANY}
next_generation
effective procedure
{}
ensure
count: INTEGER_32
deferred function
{ANY}
Number of available items in the hoard.
See also is_empty
ensure
  • Result >= 0
is_empty: BOOLEAN
deferred function
{ANY}
Is the hoard empty ?
See also count.
ensure
  • definition: Result = count = 0
do_all (action: ROUTINE[TUPLE[TUPLE 1[E_]]])
frozen
effective procedure
{ANY}
Apply action to every item of Current.
This feature is obsolete: Use `for_each` instead. This feature is not secure because it accepts a FUNCTION, the result of which is lost.
_inline_agent1 (a: ROUTINE[TUPLE[TUPLE 1[E_]]], e: E_)
frozen
effective procedure
{}
lower: INTEGER_32
deferred function
{ANY}
Minimum index.
See also upper, valid_index, item.
upper: INTEGER_32
deferred function
{ANY}
Maximum index.
See also lower, valid_index, item.
valid_index (i: INTEGER_32): BOOLEAN
effective function
{ANY}
True when i is valid (i.e., inside actual bounds).
See also lower, upper, item.
ensure
item (i: INTEGER_32): E_
deferred function
{ANY}
Item at the corresponding index i.
See also lower, upper, valid_index.
require
first: E_
deferred function
{ANY}
The very first item.
See also last, item.
require ensure
last: E_
deferred function
{ANY}
The last item.
See also first, item.
require ensure
first_index_of (element: ANY): INTEGER_32
deferred function
{ANY}
Give the index of the first occurrence of element using is_equal for comparison.
Answer upper + 1 when element is not inside.
See also fast_first_index_of, index_of, last_index_of, reverse_index_of.
ensure
index_of (element: ANY, start_index: INTEGER_32): INTEGER_32
deferred function
{ANY}
Using is_equal for comparison, gives the index of the first occurrence of element at or after start_index.
Return upper + 1 if the search for element failed.
See also fast_index_of, reverse_index_of, first_index_of.
ensure
reverse_index_of (element: ANY, start_index: INTEGER_32): INTEGER_32
deferred function
{ANY}
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.
require ensure
fast_first_index_of (element: ANY): INTEGER_32
deferred function
{ANY}
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.
ensure
fast_index_of (element: ANY, start_index: INTEGER_32): INTEGER_32
deferred function
{ANY}
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.
ensure
fast_reverse_index_of (element: ANY, start_index: INTEGER_32): INTEGER_32
deferred function
{ANY}
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.
require ensure