java::util::Set Class Reference

Inheritance diagram for java::util::Set:

Inheritance graph
java::util::AbstractSetjava::util::SortedSetjava::util::Collectionjava::lang::Interfacejava::lang::Objectjava::util::HashSetjava::util::TreeSet
[legend]
Collaboration diagram for java::util::Set:

Collaboration graph
java::util::Collectionjava::lang::Interfacejava::lang::Object
[legend]

List of all members.


Detailed Description

A collection that contains no duplicate elements.

More formally, sets contain no pair of elements e1 and e2 such that e1.equals(e2), and at most one null element. As implied by its name, this interface models the mathematical set abstraction.

The Set interface places additional stipulations, beyond those inherited from the Collection interface, on the contracts of all constructors and on the contracts of the add, equals and hashCode methods. Declarations for other inherited methods are also included here for convenience. (The specifications accompanying these declarations have been tailored to the Set interface, but they do not contain any additional stipulations.)

The additional stipulation on constructors is, not surprisingly, that all constructors must create a set that contains no duplicate elements (as defined above).

Note: Great care must be exercised if mutable objects are used as set elements. The behavior of a set is not specified if the value of an object is changed in a manner that affects equals comparisons while the object is an element in the set. A special case of this prohibition is that it is not permissible for a set to contain itself as an element.

Some set implementations have restrictions on the elements that they may contain. For example, some implementations prohibit null elements, and some have restrictions on the types of their elements. Attempting to add an ineligible element throws an unchecked exception, typically NullPointerException or ClassCastException. Attempting to query the presence of an ineligible element may throw an exception, or it may simply return false; some implementations will exhibit the former behavior and some will exhibit the latter. More generally, attempting an operation on an ineligible element whose completion would not result in the insertion of an ineligible element into the set may throw an exception or it may succeed, at the option of the implementation. Such exceptions are marked as "optional" in the specification for this interface.

Author:
Josh Bloch
Version:
1.27, 12/03/01
See also:
Collection

List

SortedSet

HashSet

TreeSet

AbstractSet

Collections::singleton(java.lang.Object)

Collections::EMPTY_SET

Since:
1.2

Static Public Member Functions

static Ref< SetemptySet ()
 The empty set (immutable).
static Ref< SetsingletonSet (const ObjectRef &o)
 Returns an immutable set containing only the specified object.
static Ref< SetsynchronizedSet (const Ref< Set > &c, const Ref< Sync > &sync=0)
 Returns a synchronized (thread-safe) set backed by the specified set.
static Ref< SetimmutableSet (const Ref< Set > &c)
 Returns an unmodifiable view of the specified set.

Member Function Documentation

static Ref<Set> java::util::Set::emptySet (  )  [static]

The empty set (immutable).

static Ref<Set> java::util::Set::singletonSet ( const ObjectRef o  )  [static]

Returns an immutable set containing only the specified object.

Parameters:
o the sole object to be stored in the returned set.
Returns:
an immutable set containing only the specified object.

static Ref<Set> java::util::Set::synchronizedSet ( const Ref< Set > &  c,
const Ref< Sync > &  sync = 0 
) [static]

Returns a synchronized (thread-safe) set backed by the specified set.

In order to guarantee serial access, it is critical that all access to the backing set is accomplished through the returned set.

It is imperative that the user manually synchronize on the returned set when iterating over it:

  Set s = Collections.synchronizedSet(new HashSet());
      ...
  synchronized(s) {
      Iterator i = s.iterator(); // Must be in the synchronized block
      while (i.hasNext())
          foo(i.next());
  }
 
Failure to follow this advice may result in non-deterministic behavior.

The returned set will be serializable if the specified set is serializable.

Parameters:
s the set to be "wrapped" in a synchronized set.
Returns:
a synchronized view of the specified set.

static Ref<Set> java::util::Set::immutableSet ( const Ref< Set > &  c  )  [static]

Returns an unmodifiable view of the specified set.

This method allows modules to provide users with "read-only" access to internal sets. Query operations on the returned set "read through" to the specified set, and attempts to modify the returned set, whether direct or via its iterator, result in an UnsupportedOperationException.

The returned set will be serializable if the specified set is serializable.

Parameters:
s the set for which an unmodifiable view is to be returned.
Returns:
an unmodifiable view of the specified set.


The documentation for this class was generated from the following file:
Generated on Fri May 16 11:56:51 2008 for CrossPlatformJavaLikeC++API by  doxygen 1.5.3