Back to index

plt-scheme  4.2.1
Public Member Functions | Protected Member Functions | Package Functions | Static Package Functions
java.util.AbstractCollection Class Reference

A basic implementation of most of the methods in the Collection interface to make it easier to create a collection. More...

Inheritance diagram for java.util.AbstractCollection:
Inheritance graph
[legend]
Collaboration diagram for java.util.AbstractCollection:
Collaboration graph
[legend]

List of all members.

Public Member Functions

abstract Iterator iterator ()
 Return an Iterator over this collection.
abstract int size ()
 Return the number of elements in this collection.
boolean add (Object o)
 Add an object to the collection (optional operation).
boolean addAll (Collection c)
 Add all the elements of a given collection to this collection (optional operation).
void clear ()
 Remove all elements from the collection (optional operation).
boolean contains (Object o)
 Test whether this collection contains a given object.
boolean containsAll (Collection c)
 Tests whether this collection contains all the elements in a given collection.
boolean isEmpty ()
 Test whether this collection is empty.
boolean remove (Object o)
 Remove a single instance of an object from this collection (optional operation).
boolean removeAll (Collection c)
 Remove from this collection all its elements that are contained in a given collection (optional operation).
boolean retainAll (Collection c)
 Remove from this collection all its elements that are not contained in a given collection (optional operation).
Object[] toArray ()
 Return an array containing the elements of this collection.
Object[] toArray (Object[] a)
 Copy the collection into a given array if it will fit, or into a dynamically created array of the same run-time type as the given array if not.
String toString ()
 Creates a String representation of the Collection.

Protected Member Functions

 AbstractCollection ()
 The main constructor, for use by subclasses.

Package Functions

boolean removeAllInternal (Collection c)
 Remove from this collection all its elements that are contained in a given collection (optional operation).
boolean retainAllInternal (Collection c)
 Remove from this collection all its elements that are not contained in a given collection (optional operation).

Static Package Functions

static final boolean equals (Object o1, Object o2)
 Compare two objects according to Collection semantics.
static final int hashCode (Object o)
 Hash an object according to Collection semantics.

Detailed Description

A basic implementation of most of the methods in the Collection interface to make it easier to create a collection.

To create an unmodifiable Collection, just subclass AbstractCollection and provide implementations of the iterator() and size() methods. The Iterator returned by iterator() need only provide implementations of hasNext() and next() (that is, it may throw an UnsupportedOperationException if remove() is called). To create a modifiable Collection, you must in addition provide an implementation of the add(Object) method and the Iterator returned by iterator() must provide an implementation of remove(). Other methods should be overridden if the backing data structure allows for a more efficient implementation. The precise implementation used by AbstractCollection is documented, so that subclasses can tell which methods could be implemented more efficiently.

The programmer should provide a no-argument constructor, and one that accepts another Collection, as recommended by the Collection interface. Unfortunately, there is no way to enforce this in Java.

Author:
Original author unknown
Bryce McKinlay
Eric Blake ebb9@.nosp@m.emai.nosp@m.l.byu.nosp@m..edu
See also:
Collection
AbstractSet
AbstractList
Since:
1.2 updated to 1.4

Definition at line 71 of file AbstractCollection.java.


Constructor & Destructor Documentation

The main constructor, for use by subclasses.

Definition at line 76 of file AbstractCollection.java.

  {
  }

Member Function Documentation

boolean java.util.AbstractCollection.add ( Object  o) [inline]

Add an object to the collection (optional operation).

This implementation always throws an UnsupportedOperationException - it should be overridden if the collection is to be modifiable. If the collection does not accept duplicates, simply return false. Collections may specify limitations on what may be added.

Parameters:
othe object to add
Returns:
true if the add operation caused the Collection to change
Exceptions:
UnsupportedOperationExceptionif the add operation is not supported on this collection
NullPointerExceptionif the collection does not support null
ClassCastExceptionif the object is of the wrong type
IllegalArgumentExceptionif some aspect of the object prevents it from being added

Implements java.util.Collection.

Reimplemented in java.util.AbstractList.

Definition at line 113 of file AbstractCollection.java.

  {
    throw new UnsupportedOperationException();
  }

Here is the caller graph for this function:

Add all the elements of a given collection to this collection (optional operation).

This implementation obtains an Iterator over the given collection and iterates over it, adding each element with the add(Object) method (thus this method will fail with an UnsupportedOperationException if the add method does). The behavior is unspecified if the specified collection is modified during the iteration, including the special case of trying addAll(this) on a non-empty collection.

Parameters:
cthe collection to add the elements of to this collection
Returns:
true if the add operation caused the Collection to change
Exceptions:
UnsupportedOperationExceptionif the add operation is not supported on this collection
NullPointerExceptionif this collection does not support null, or if the specified collection is null
ClassCastExceptionif an object in c is of the wrong type
IllegalArgumentExceptionif some aspect of an object in c prevents it from being added
See also:
add(Object)

Implements java.util.Collection.

Reimplemented in java.util.SubList, and java.util.AbstractList.

Definition at line 139 of file AbstractCollection.java.

  {
    Iterator itr = c.iterator();
    boolean modified = false;
    int pos = c.size();
    while (--pos >= 0)
      modified = modified | add(itr.next());
    return modified;
  }

Here is the call graph for this function:

Remove all elements from the collection (optional operation).

This implementation obtains an iterator over the collection and calls next and remove on it repeatedly (thus this method will fail with an UnsupportedOperationException if the Iterator's remove method does) until there are no more elements to remove. Many implementations will have a faster way of doing this.

Exceptions:
UnsupportedOperationExceptionif the Iterator returned by iterator does not provide an implementation of remove
See also:
Iterator::remove()

Implements java.util.Collection.

Reimplemented in java.util.AbstractList.

Definition at line 161 of file AbstractCollection.java.

  {
    Iterator itr = iterator();
    int pos = size();
    while (--pos >= 0)
      {
        itr.next();
        itr.remove();
      }
  }

Here is the call graph for this function:

Test whether this collection contains a given object.

That is, if the collection has an element e such that (o == null ? e == null : o.equals(e)). This implementation obtains an iterator over the collection and iterates over it, testing each element for equality with the given object. If it is equal, true is returned. Otherwise false is returned when the end of the collection is reached.

Parameters:
othe object to remove from this collection
Returns:
true if this collection contains an object equal to o

Implements java.util.Collection.

Reimplemented in java.util.SubList, and java.util.AbstractList.

Definition at line 183 of file AbstractCollection.java.

  {
    Iterator itr = iterator();
    int pos = size();
    while (--pos >= 0)
      if (equals(o, itr.next()))
        return true;
    return false;
  }

Here is the call graph for this function:

Here is the caller graph for this function:

Tests whether this collection contains all the elements in a given collection.

This implementation iterates over the given collection, testing whether each element is contained in this collection. If any one is not, false is returned. Otherwise true is returned.

Parameters:
cthe collection to test against
Returns:
true if this collection contains all the elements in the given collection
Exceptions:
NullPointerExceptionif the given collection is null
See also:
contains(Object)

Implements java.util.Collection.

Reimplemented in java.util.SubList, and java.util.AbstractList.

Definition at line 205 of file AbstractCollection.java.

  {
    Iterator itr = c.iterator();
    int pos = c.size();
    while (--pos >= 0)
      if (!contains(itr.next()))
        return false;
    return true;
  }

Here is the call graph for this function:

static final boolean java.util.AbstractCollection.equals ( Object  o1,
Object  o2 
) [inline, static, package]

Compare two objects according to Collection semantics.

Parameters:
o1the first object
o2the second object
Returns:
o1 == null ? o2 == null : o1.equals(o2)

Definition at line 446 of file AbstractCollection.java.

  {
    return o1 == null ? o2 == null : o1.equals(o2);
  }

Here is the caller graph for this function:

static final int java.util.AbstractCollection.hashCode ( Object  o) [inline, static, package]

Hash an object according to Collection semantics.

Parameters:
othe object to hash
Returns:
o1 == null ? 0 : o1.hashCode()

Definition at line 459 of file AbstractCollection.java.

  {
    return o == null ? 0 : o.hashCode();
  }

Here is the caller graph for this function:

Test whether this collection is empty.

This implementation returns size() == 0.

Returns:
true if this collection is empty.
See also:
size()

Implements java.util.Collection.

Reimplemented in java.util.SubList, and java.util.AbstractList.

Definition at line 222 of file AbstractCollection.java.

  {
    return size() == 0;
  }

Here is the call graph for this function:

abstract Iterator java.util.AbstractCollection.iterator ( ) [pure virtual]

Return an Iterator over this collection.

The iterator must provide the hasNext and next methods and should in addition provide remove if the collection is modifiable.

Returns:
an iterator

Implements java.util.Collection.

Implemented in java.util.SubList, java.util.AbstractList, and java.util.AbstractSequentialList.

Here is the caller graph for this function:

Remove a single instance of an object from this collection (optional operation).

That is, remove one element e such that (o == null ? e == null : o.equals(e)), if such an element exists. This implementation obtains an iterator over the collection and iterates over it, testing each element for equality with the given object. If it is equal, it is removed by the iterator's remove method (thus this method will fail with an UnsupportedOperationException if the Iterator's remove method does). After the first element has been removed, true is returned; if the end of the collection is reached, false is returned.

Parameters:
othe object to remove from this collection
Returns:
true if the remove operation caused the Collection to change, or equivalently if the collection did contain o.
Exceptions:
UnsupportedOperationExceptionif this collection's Iterator does not support the remove method
See also:
Iterator::remove()

Implements java.util.Collection.

Reimplemented in java.util.SubList, and java.util.AbstractList.

Definition at line 246 of file AbstractCollection.java.

  {
    Iterator itr = iterator();
    int pos = size();
    while (--pos >= 0)
      if (equals(o, itr.next()))
        {
          itr.remove();
          return true;
        }
    return false;
  }

Here is the call graph for this function:

Remove from this collection all its elements that are contained in a given collection (optional operation).

This implementation iterates over this collection, and for each element tests if it is contained in the given collection. If so, it is removed by the Iterator's remove method (thus this method will fail with an UnsupportedOperationException if the Iterator's remove method does).

Parameters:
cthe collection to remove the elements of
Returns:
true if the remove operation caused the Collection to change
Exceptions:
UnsupportedOperationExceptionif this collection's Iterator does not support the remove method
See also:
Iterator::remove()

Implements java.util.Collection.

Reimplemented in java.util.SubList, and java.util.AbstractList.

Definition at line 273 of file AbstractCollection.java.

  {
    return removeAllInternal(c);
  }

Here is the call graph for this function:

Remove from this collection all its elements that are contained in a given collection (optional operation).

This implementation iterates over this collection, and for each element tests if it is contained in the given collection. If so, it is removed by the Iterator's remove method (thus this method will fail with an UnsupportedOperationException if the Iterator's remove method does). This method is necessary for ArrayList, which cannot publicly override removeAll but can optimize this call.

Parameters:
cthe collection to remove the elements of
Returns:
true if the remove operation caused the Collection to change
Exceptions:
UnsupportedOperationExceptionif this collection's Iterator does not support the remove method
See also:
Iterator::remove()

Definition at line 293 of file AbstractCollection.java.

  {
    Iterator itr = iterator();
    boolean modified = false;
    int pos = size();
    while (--pos >= 0)
      if (c.contains(itr.next()))
        {
          itr.remove();
          modified = true;
        }
    return modified;
  }

Here is the call graph for this function:

Here is the caller graph for this function:

Remove from this collection all its elements that are not contained in a given collection (optional operation).

This implementation iterates over this collection, and for each element tests if it is contained in the given collection. If not, it is removed by the Iterator's remove method (thus this method will fail with an UnsupportedOperationException if the Iterator's remove method does).

Parameters:
cthe collection to retain the elements of
Returns:
true if the remove operation caused the Collection to change
Exceptions:
UnsupportedOperationExceptionif this collection's Iterator does not support the remove method
See also:
Iterator::remove()

Implements java.util.Collection.

Reimplemented in java.util.SubList, and java.util.AbstractList.

Definition at line 321 of file AbstractCollection.java.

  {
    return retainAllInternal(c);
  }

Here is the call graph for this function:

Remove from this collection all its elements that are not contained in a given collection (optional operation).

This implementation iterates over this collection, and for each element tests if it is contained in the given collection. If not, it is removed by the Iterator's remove method (thus this method will fail with an UnsupportedOperationException if the Iterator's remove method does). This method is necessary for ArrayList, which cannot publicly override retainAll but can optimize this call.

Parameters:
cthe collection to retain the elements of
Returns:
true if the remove operation caused the Collection to change
Exceptions:
UnsupportedOperationExceptionif this collection's Iterator does not support the remove method
See also:
Iterator::remove()

Definition at line 342 of file AbstractCollection.java.

  {
    Iterator itr = iterator();
    boolean modified = false;
    int pos = size();
    while (--pos >= 0)
      if (!c.contains(itr.next()))
        {
          itr.remove();
          modified = true;
        }
    return modified;
  }

Here is the call graph for this function:

Here is the caller graph for this function:

abstract int java.util.AbstractCollection.size ( ) [pure virtual]

Return the number of elements in this collection.

If there are more than Integer.MAX_VALUE elements, return Integer.MAX_VALUE.

Returns:
the size

Implements java.util.Collection.

Implemented in java.util.SubList, and java.util.AbstractList.

Here is the caller graph for this function:

Object [] java.util.AbstractCollection.toArray ( ) [inline]

Return an array containing the elements of this collection.

This implementation creates an Object array of size size() and then iterates over the collection, setting each element of the array from the value returned by the iterator. The returned array is safe, and is not backed by the collection.

Returns:
an array containing the elements of this collection

Implements java.util.Collection.

Reimplemented in java.util.SubList, and java.util.AbstractList.

Definition at line 365 of file AbstractCollection.java.

  {
    Iterator itr = iterator();
    int size = size();
    Object[] a = new Object[size];
    for (int pos = 0; pos < size; pos++)
      a[pos] = itr.next();
    return a;
  }

Here is the call graph for this function:

Object [] java.util.AbstractCollection.toArray ( Object[]  a) [inline]

Copy the collection into a given array if it will fit, or into a dynamically created array of the same run-time type as the given array if not.

If there is space remaining in the array, the first element after the end of the collection is set to null (this is only useful if the collection is known to contain no null elements, however). This implementation first tests whether the given array is large enough to hold all the elements of the collection. If not, the reflection API is used to allocate a new array of the same run-time type. Next an iterator is obtained over the collection and the elements are placed in the array as they are returned by the iterator. Finally the first spare element, if any, of the array is set to null, and the created array is returned. The returned array is safe; it is not backed by the collection. Note that null may not mark the last element, if the collection allows null elements.

Parameters:
athe array to copy into, or of the correct run-time type
Returns:
the array that was produced
Exceptions:
NullPointerExceptionif the given array is null
ArrayStoreExceptionif the type of the array precludes holding one of the elements of the Collection

Implements java.util.Collection.

Reimplemented in java.util.SubList, and java.util.AbstractList.

Definition at line 397 of file AbstractCollection.java.

  {
     throw new RuntimeException("toArray(Object[]) is unimplemented");
//    int size = size();
//    if (a.length < size)
//      a = (Object[]) Array.newInstance(a.getClass().getComponentType(),
//                                       size);
//    else if (a.length > size)
//      a[size] = null;

//    Iterator itr = iterator();
//    for (int pos = 0; pos < size; pos++)
//      a[pos] = itr.next();
//
//    return a;
  }

Creates a String representation of the Collection.

The string returned is of the form "[a, b, ...]" where a and b etc are the results of calling toString on the elements of the collection. This implementation obtains an Iterator over the Collection and adds each element to a StringBuffer as it is returned by the iterator.

Returns:
a String representation of the Collection

Definition at line 423 of file AbstractCollection.java.

  { return super.toString();
    //Iterator itr = iterator();
    //StringBuffer r = new StringBuffer("[");
    //for (int pos = size(); pos > 0; pos--)
    //  {
    //    r.append(itr.next());
    //    if (pos > 1)
    //      r.append(", ");
    //  }
    //r.append("]");
    //return r.toString();
  }

The documentation for this class was generated from the following file: