java.util
Class AbstractCollection<E>
- Collection<E>, Iterable<E>
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.
| T[] toArray(T[] 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.
|
boolean | add(E o)- Add an object to the collection (optional operation).
|
boolean | addAll(E> 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.
|
abstract Iterator | iterator()- Return an Iterator over this collection.
|
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).
|
abstract int | size()- Return the number of elements in this collection.
|
Object[] | toArray()- Return an array containing the elements of this collection.
|
String | toString()- Creates a String representation of the Collection.
|
clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait |
AbstractCollection
protected AbstractCollection()
The main constructor, for use by subclasses.
T[] toArray
public T[] toArray(T[] 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. 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.
- T[] toArray in interface Collection<E>
a - the array to copy into, or of the correct run-time type
- the array that was produced
add
public boolean add(E o)
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.
- add in interface Collection<E>
- true if the add operation caused the Collection to change
addAll
public boolean addAll(E> c)
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.
- addAll in interface Collection<E>
c - the collection to add the elements of to this collection
- true if the add operation caused the Collection to change
clear
public void clear()
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.
- clear in interface Collection<E>
contains
public boolean contains(Object o)
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.
- contains in interface Collection<E>
o - the object to remove from this collection
- true if this collection contains an object equal to o
containsAll
public boolean containsAll(Collection c)
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.
- containsAll in interface Collection<E>
c - the collection to test against
- true if this collection contains all the elements in the given
collection
isEmpty
public boolean isEmpty()
Test whether this collection is empty. This implementation returns
size() == 0.
- isEmpty in interface Collection<E>
- true if this collection is empty.
iterator
public abstract Iterator iterator()
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.
- iterator in interface Collection<E>
- iterator in interface Iterable<E>
remove
public boolean remove(Object o)
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.
- remove in interface Collection<E>
o - the object to remove from this collection
- true if the remove operation caused the Collection to change, or
equivalently if the collection did contain o.
removeAll
public boolean removeAll(Collection c)
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).
- removeAll in interface Collection<E>
c - the collection to remove the elements of
- true if the remove operation caused the Collection to change
retainAll
public boolean retainAll(Collection c)
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).
- retainAll in interface Collection<E>
c - the collection to retain the elements of
- true if the remove operation caused the Collection to change
size
public abstract int size()
Return the number of elements in this collection. If there are more than
Integer.MAX_VALUE elements, return Integer.MAX_VALUE.
- size in interface Collection<E>
toArray
public Object[] toArray()
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.
- toArray in interface Collection<E>
- an array containing the elements of this collection
toString
public String toString()
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. "" is inserted when the collection
contains itself (only works for direct containment, not for collections
inside collections).
- toString in interface Object
- a String representation of the Collection
AbstractCollection.java -- Abstract implementation of most of Collection
Copyright (C) 1998, 2000, 2001, 2004, 2005 Free Software Foundation, Inc.
This file is part of GNU Classpath.
GNU Classpath is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.
GNU Classpath is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with GNU Classpath; see the file COPYING. If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA.
Linking this library statically or dynamically with other modules is
making a combined work based on this library. Thus, the terms and
conditions of the GNU General Public License cover the whole
combination.
As a special exception, the copyright holders of this library give you
permission to link this library with independent modules to produce an
executable, regardless of the license terms of these independent
modules, and to copy and distribute the resulting executable under
terms of your choice, provided that you also meet, for each linked
independent module, the terms and conditions of the license of that
module. An independent module is a module which is not derived from
or based on this library. If you modify this library, you may extend
this exception to your version of the library, but you are not
obligated to do so. If you do not wish to do so, delete this
exception statement from your version.