6.2 Shared Methods

The collection classes share many functions based on the Collection and Sequence interfaces. The javadocs contain a complete discussion of all methods, which are briefly described below.

6.2.1 The Collection Interface

The Collection interface contains methods for the insertion, retrieval, and removal of elements. Method insert(Object) inserts an item into the collection, while insertMany(Enumeration) inserts all the elements in an Enumeration.

For retrieval operations, find(Object) returns the element equivalent to the given item, while elements() returns an Enumeration object which can be used to visit each element of the collection in turn. Method contains(Object) returns true if the collection contains an element equivalent to the given item, isEmpty() returns true if the collection is empty, occurrencesOf(Object) returns the number of elements in the collection equivalent to a given item, and size() returns the number of entries in the collection

For removal operations, clear() removes all elements from the collection. Method remove(Object) removes the first element that is equivalent to the given item; removeAll(Object) removes all such elements, and removeMany(Enumeration) removes the first element equivalent to each item enumerated by the given Enumeration.

The Collection interface also includes two higher-order functions. Method apply(UnaryFunction) applies a unary function to every element of the collection in turn. The return value is ignored. This method might be used, for example, to print all the elements of a collection meeting some criterion. Method reduce(BinaryFunction, Object) reduces the collection to a single value. It might be used, for example, to sum all the elements in a collection of numbers.

6.2.2 The Sequence Interface

The Sequence interface, which extends the Collection interface, contains methods for collections in which the order of elements can be determined externally by the client of the collection, and elements can be accessed by index.

For insertion operations, insertAt(int, Object) inserts an item at a particular location within the collection, while atPut(int, Object) replaces an element at a particular location. Method append(Object) can be used to add an item to the end of the collection, and prepend(Object) to add an item to the front.

For retrieval operations, at(int) returns an element from a particular location within the collection, first() returns the first element, and last() returns the last element. Method containsReference(Object) returns true if the collection contains an element identical to the given item, while occurrencesOfReference(Object) returns the number of such elements. Method index(Object) returns the location of the first element equivalent to a given, and indexReference(Object) returns the location of the first element identical to the given item.

For removal operations, removeAt(int) removes an element from a particular location within the collection, removeFirst() removes the first element, and removeLast() removes the last element. Method removeReference(Object) removes from the collection the first element that is identical to the given item, while removeAllReference(Object) removes all such elements.

The Sequence interface also includes one higher-order function. Method transform(UnaryFunction) replaces each member of the collection with the result of applying the unary function to that member. It might be used, for example, to change all entries to lower case in a collection of strings.