Collection

java.lang.Object
- jsimple.lang.Iterable<E>
- - jsimple.util.Collection<E>

All Implemented Interfaces:

java.lang.Iterable<E>

Direct Known Subclasses:

List, Set
```
public abstract class Collection<E>
extends Iterable<E>
```
Collection is the root of the collection hierarchy. It defines operations on data collections and the behavior that they will have in all implementations of Collections.
All direct or indirect implementations of Collection should implement at least two constructors. One with no parameters which creates an empty collection and one with a parameter of type Collection. This second constructor can be used to create a collection of different type as the initial collection but with the same elements. Implementations of Collection cannot be forced to implement these two constructors but at least all implementations under java.util do.
Methods that change the content of a collection throw an UnsupportedOperationException if the underlying collection does not support that operation, though it's not mandatory to throw such an Exception in cases where the requested operation would not change the collection. In these cases it's up to the implementation whether it throws an UnsupportedOperationException or not.
Methods marked with (optional) can throw an UnsupportedOperationException if the underlying collection doesn't support that method.
A subclass must implement the abstract methods iterator() and size() to create an immutable collection. To create a modifiable collection it's necessary to override the add() method that currently throws an UnsupportedOperationException.
Changes from the java.lang version:
void toArray(T[] contents) requires an array of the right size to be passed in, never allocating the array. That avoids the need for reflection & was the most efficient option for using that method anyway.
The contains and remove methods take an E instead of an Object as a parameter. Logically, this makes more sense, is more type safe, and is consistent with C#. This change avoids some generic casting issues.

Constructor Summary

Constructors
Modifier Constructor and Description

protected Collection()
Constructs a new instance of this AbstractCollection.

Constructors
Modifier	Constructor and Description
`protected`	`Collection()` Constructs a new instance of this AbstractCollection.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`add(E object)` Attempts to add `object` to the contents of this `Collection` (optional).
`boolean`	`addAll(Collection<? extends E> collection)` Attempts to add all of the objects contained in `Collection` to the contents of this `Collection` (optional).
`void`	`clear()` Removes all elements from this `Collection`, leaving it empty (optional).
`boolean`	`contains(E object)` Tests whether this `Collection` contains the specified object.
`boolean`	`containsAll(Collection<E> collection)` Tests whether this `Collection` contains all objects contained in the specified `Collection`.
`boolean`	`isEmpty()` Returns if this `Collection` contains no elements.
`abstract Iterator<E>`	`iterator()` Returns an instance of `Iterator` that may be used to access the objects contained by this `Collection`.
`boolean`	`remove(E object)` Removes one instance of the specified object from this `Collection` if one is contained (optional).
`boolean`	`removeAll(Collection<E> collection)` Removes all occurrences in this `Collection` of each object in the specified `Collection` (optional).
`boolean`	`retainAll(Collection<E> collection)` Removes all objects from this `Collection` that are not also found in the `Collection` passed (optional).
`abstract int`	`size()` Returns a count of how many objects this `Collection` contains.
`java.lang.Object[]`	`toArray()` Returns a new array containing all elements contained in this `Collection`.
`void`	`toArray(E[] contents)` Copies all elements contained in this `Collection` to the specified array.
`java.lang.String`	`toString()` Returns the string representation of this `Collection`.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable
forEach, spliterator

- Constructor Detail
  - Collection
```
protected Collection()
```
    Constructs a new instance of this AbstractCollection.
- Method Detail
  - add
```
public boolean add(E object)
```
    Attempts to add object to the contents of this Collection (optional).
    After this method finishes successfully it is guaranteed that the object is contained in the collection.
    If the collection was modified it returns true, false if no changes were made.
    An implementation of Collection may narrow the set of accepted objects, but it has to specify this in the documentation. If the object to be added does not meet this restriction, then an IllegalArgumentException is thrown.
    If a collection does not yet contain an object that is to be added and adding the object fails, this method must throw an appropriate unchecked Exception. Returning false is not permitted in this case because it would violate the postcondition that the element will be part of the collection after this method finishes.
    
    Parameters:
    
    object - the object to add.
    
    Returns:
    
    true if this Collection is modified, false otherwise.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if adding to this Collection is not supported.
    
    java.lang.ClassCastException - if the class of the object is inappropriate for this collection.
    
    java.lang.IllegalArgumentException - if the object cannot be added to this Collection.
    
    java.lang.NullPointerException - if null elements cannot be added to the Collection.
  - addAll
```
public boolean addAll(Collection<? extends E> collection)
```
    Attempts to add all of the objects contained in Collection to the contents of this Collection (optional). If the passed Collection is changed during the process of adding elements to this Collection, the behavior is not defined.
    The default implementation iterates over the given Collection and calls add for each element. If any of these calls return true, then true is returned as result of this method call, false otherwise. If this Collection does not support adding elements, an UnsupportedOperationException is thrown.
    
    Parameters:
    
    collection - the Collection of objects.
    
    Returns:
    
    true if this Collection is modified, false otherwise.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if adding to this Collection is not supported.
    
    java.lang.ClassCastException - if the class of an object is inappropriate for this Collection.
    
    java.lang.IllegalArgumentException - if an object cannot be added to this Collection.
    
    java.lang.NullPointerException - if collection is null, or if it contains null elements and this Collection does not support such elements.
  - clear
```
public void clear()
```
    Removes all elements from this Collection, leaving it empty (optional).
    The default implementation iterates over this Collection and calls the remove method on each element. If the iterator does not support removal of elements, an UnsupportedOperationException is thrown.
    Concrete implementations usually can clear a Collection more efficiently and should therefore overwrite this method.
    
    Throws:
    
    java.lang.UnsupportedOperationException - it the iterator does not support removing elements from this Collection
    
    See Also:
    
    iterator(), isEmpty(), size()
  - contains
```
public boolean contains(E object)
```
    Tests whether this Collection contains the specified object. Returns true if and only if at least one element elem in this Collection meets following requirement: (object==null ? elem==null : object.equals(elem)).
    The default implementation iterates over this Collection and tests, whether any element is equal to the given object. If object != null then object.equals(e) is called for each element e returned by the iterator until the element is found. If object == null then each element e returned by the iterator is compared with the test e == null.
    
    Parameters:
    
    object - the object to search for.
    
    Returns:
    
    true if object is an element of this Collection, false otherwise.
    
    Throws:
    
    java.lang.ClassCastException - if the object to look for isn't of the correct type.
    
    java.lang.NullPointerException - if the object to look for is null and this Collection doesn't support null elements.
  - containsAll
```
public boolean containsAll(Collection<E> collection)
```
    Tests whether this Collection contains all objects contained in the specified Collection. If an element elem is contained several times in the specified Collection, the method returns true even if elem is contained only once in this Collection.
    The default implementation iterates over the specified Collection. If one element returned by the iterator is not contained in this Collection, then false is returned; true otherwise.
    
    Parameters:
    
    collection - the collection of objects.
    
    Returns:
    
    true if all objects in the specified Collection are elements of this Collection, false otherwise.
    
    Throws:
    
    java.lang.ClassCastException - if one or more elements of collection isn't of the correct type.
    
    java.lang.NullPointerException - if collection contains at least one null element and this Collection doesn't support null elements.
    
    java.lang.NullPointerException - if collection is null.
  - isEmpty
```
public boolean isEmpty()
```
    Returns if this Collection contains no elements.
    The default implementation tests whether size returns 0.
    
    Returns:
    
    true if this Collection has no elements, false otherwise.
    
    See Also:
    
    size()
  - iterator
```
public abstract Iterator<E> iterator()
```
    Returns an instance of Iterator that may be used to access the objects contained by this Collection. The order in which the elements are returned by the Iterator is not defined unless the instance of the Collection has a defined order. In that case, the elements are returned in that order.
    
    Specified by:
    
    iterator in interface java.lang.Iterable<E>
    
    Specified by:
    
    iterator in class Iterable<E>
    
    Returns:
    
    an iterator for accessing the Collection contents.
  - remove
```
public boolean remove(E object)
```
    Removes one instance of the specified object from this Collection if one is contained (optional). The element elem that is removed complies with (object==null ? elem==null : object.equals(elem).
    The default implementation iterates over this Collection and tests for each element e returned by the iterator, whether e is equal to the given object. If object != null then this test is performed using object.equals(e), otherwise using object == null. If an element equal to the given object is found, then the remove method is called on the iterator and true is returned, false otherwise. If the iterator does not support removing elements, an UnsupportedOperationException is thrown.
    
    Parameters:
    
    object - the object to remove.
    
    Returns:
    
    true if this Collection is modified, false otherwise.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if removing from this Collection is not supported.
    
    java.lang.ClassCastException - if the object passed is not of the correct type.
    
    java.lang.NullPointerException - if object is null and this Collection doesn't support null elements.
  - removeAll
```
public boolean removeAll(Collection<E> collection)
```
    Removes all occurrences in this Collection of each object in the specified Collection (optional). After this method returns none of the elements in the passed Collection can be found in this Collection anymore.
    The default implementation iterates over this Collection and tests for each element e returned by the iterator, whether it is contained in the specified Collection. If this test is positive, then the remove method is called on the iterator. If the iterator does not support removing elements, an UnsupportedOperationException is thrown.
    
    Parameters:
    
    collection - the collection of objects to remove.
    
    Returns:
    
    true if this Collection is modified, false otherwise.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if removing from this Collection is not supported.
    
    java.lang.ClassCastException - if one or more elements of collection isn't of the correct type.
    
    java.lang.NullPointerException - if collection contains at least one null element and this Collection doesn't support null elements.
    
    java.lang.NullPointerException - if collection is null.
  - retainAll
```
public boolean retainAll(Collection<E> collection)
```
    Removes all objects from this Collection that are not also found in the Collection passed (optional). After this method returns this Collection will only contain elements that also can be found in the Collection passed to this method.
    The default implementation iterates over this Collection and tests for each element e returned by the iterator, whether it is contained in the specified Collection. If this test is negative, then the remove method is called on the iterator. If the iterator does not support removing elements, an UnsupportedOperationException is thrown.
    
    Parameters:
    
    collection - the collection of objects to retain.
    
    Returns:
    
    true if this Collection is modified, false otherwise.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if removing from this Collection is not supported.
    
    java.lang.ClassCastException - if one or more elements of collection isn't of the correct type.
    
    java.lang.NullPointerException - if collection contains at least one null element and this Collection doesn't support null elements.
    
    java.lang.NullPointerException - if collection is null.
  - size
```
public abstract int size()
```
    Returns a count of how many objects this Collection contains.
    
    Returns:
    
    how many objects this Collection contains, or Integer.MAX_VALUE if there are more than Integer.MAX_VALUE elements in this Collection.
  - toArray
```
public java.lang.Object[] toArray()
```
    Returns a new array containing all elements contained in this Collection.
    If the implementation has ordered elements it will return the element array in the same order as an iterator would return them.
    The array returned does not reflect any changes of the Collection. A new array is created even if the underlying data structure is already an array.
    
    Returns:
    
    an array of the elements from this Collection.
  - toArray
```
public void toArray(E[] contents)
```
    Copies all elements contained in this Collection to the specified array. Unlike the regular java.util version of this method, here the array is never allocated & returned but instead a big enough array must be passed in. If the specified array isn't big enough to hold all elements, an exception is thrown. If it's bigger than needed, the array element following the Collection elements is set to null.
    Changes to the standard java.util version of this method avoid the need for reflection and make it a little simpler. Typical usage would be to just allocate an array of exactly the right length, with size() elements.
    
    Parameters:
    
    contents - the array.
  - toString
```
public java.lang.String toString()
```
    Returns the string representation of this Collection. The presentation has a specific format. It is enclosed by square brackets ("[]"). Elements are separated by ', ' (comma and space).
    Note that this method doesn't support collections with a loop in the object graph that end up containing themselves (e.g. collection with itself an element or a collection that includes another collection that in turn includes the original collection). Such collection will result in infinite recursion and ultimately a stack overflow exception.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    the string representation of this Collection.

Class Collection<E>

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Constructor Detail

Collection

Method Detail

add

addAll

clear

contains

containsAll

isEmpty

iterator

remove

removeAll

retainAll

size

toArray

toArray

toString