com.webobjects.foundation
Class NSSet

java.lang.Object
  com.webobjects.foundation.NSSet

All Implemented Interfaces:

NSCoding, Serializable, Cloneable, Iterable, Collection, Set

Direct Known Subclasses:

NSMutableSet

public class NSSet
extends Object
implements Cloneable, Serializable, NSCoding, Set

NSSet declares an API for an object that manages a collection of objects similar to a mathematical set. A set, both in its mathematical sense and in the implementation of NSSet, is an unordered collection of distinct elements. The NSMutableSet subclass is provided for sets whose contents may be altered.

Use sets as an alternative to arrays when the order of elements is not important and performance in testing whether an object is contained in the set is a consideration. While arrays are ordered, testing for membership is much slower than with sets.

Methods that add entries to sets, whether during construction (for all sets) or modification (for mutable sets), add each member to the set directly. This means that you must ensure that the members do not change. If the members are expected to change for any reason, you should make copies of them and add the copies to the set or otherwise guarantee that the members do not change with respect to either the equals or hashCode methods.

The following table describes the NSSet methods that provide the basis for all NSSet's other methods; that is, all other methods are implemented in terms of these three. If you create a subclass of NSSet, you need only ensure that these base methods work properly. Having done so, you can be sure that all his subclass's inherited methods operate properly.

NSSet's Base API

Method	Description
count	returns the number of members in the set
member	returns the object in the set that is equal to the specified object
objectsNoCopy	returns the actual array of objects in the set

NSSet provides methods for querying the elements of the set. The allObjects method returns an array containing the objects in a set. The anyObject method returns some object in the set. Additionally, intersectsSet tests for set intersection, isEqualToSet tests for set equality, and isSubsetOfSet tests for one set being a subset of another.

The objectEnumerator method provides for traversing elements of the set one by one.

See Also:

Set, HashSet, NSSet._count, NSSet.allObjects(), NSSet.member(java.lang.Object), NSSet.intersectsSet(com.webobjects.foundation.NSSet), Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface com.webobjects.foundation.NSCoding

NSCoding.Support

Field Summary

static boolean	CheckForNull Convenience for the constructor methods
static NSSet	EmptySet A shared NSSet instance containing no members.
static boolean	IgnoreNull Convenience for the constructor methods

Constructor Summary

NSSet()
Creates an empty NSSet.

NSSet(Collection collection)
Creates an NSSet containing all the elements in collection

NSSet(Object object)
Creates an NSSet containing the single object.

NSSet(Object[] objects)
Creates an NSSet containing all the elements in objects Note: NSSet assumes that the member objects are immutable.

NSSet(NSArray objects)
Creates an NSSet containing all the elements in objects Note: NSSet assumes that the member objects are immutable.

NSSet(NSSet otherSet)
Creates a new NSSet containing the same objects as another NSSet.

NSSet(Set set, boolean ignoreNull)
Creates an NSSet containing all the elements in set

Method Summary

boolean	add(Object o) Operation not supported
boolean	addAll(Collection c) Operation not supported
NSArray	allObjects() Provides an array with all the members of this NSSet.
Object	anyObject() Returns one of the objects in this set, essentially chosen at random, or null if the set contains no objects.
Class	classForCoder() Conformance with NSCoding.
void	clear() Operation not supported
Object	clone() Since NSSets are immutable, there's no need to make an actual copy.
boolean	contains(Object o) NSSets cannot contain null values and therefore do not adhere to the java.util.Set specification
boolean	containsAll(Collection c)
boolean	containsObject(Object object) Indicates whether a object is a member of this NSSet as determined by equals
int	count()
static Object	decodeObject(NSCoder coder) Creates an NSSet from the data in an NSCoder.
static NSSet	emptySet() Returns the empty NSSet (immutable).
void	encodeWithCoder(NSCoder coder) Encodes the receiver using coder.
boolean	equals(Object object) Determines whether this NSSet is equal to object This is true if object is an NSSet or subclass of NSSet and both sets contain identical members.
int	hashCode() Provides an appropriate hash code useful for storing this NSSet in a hash-based data structure.
HashSet	hashSet() Creates a java.util.HashSet with the same contents as this object.
NSSet	immutableClone() Since the NSSets are immutable, there's no need to make an actual
boolean	intersectsSet(NSSet otherSet) The result of this method corresponds to the mathematical concept of disjoint sets: if the sets are not disjoint, this method returns true; otherwise, it returns false.
boolean	isEmpty()
boolean	isEqualToSet(NSSet otherSet) Provided for backward compatibility.
boolean	isSubsetOfSet(NSSet otherSet) Determines whether every member of this NSSet is a member of otherSet.
Iterator	iterator()
Object	member(Object object) Determines whether an object is a member of this NSSet based on the results of the object's equals method.
NSMutableSet	mutableClone() This method creates a duplicate NSMutableSet with the same objects.
Enumeration	objectEnumerator() Provides an Enumeration object that can be used to access each member of this NSSet.
protected Object[]	objectsNoCopy() This method should be used only by subclasses.
boolean	remove(Object o) Operation not supported
boolean	removeAll(Collection c) Operation not supported
boolean	retainAll(Collection c) Operation not supported
NSSet	setByIntersectingSet(NSSet otherSet) Creates a new NSSet that is the result of intersecting another NSSet with this NSSet.
NSSet	setBySubtractingSet(NSSet otherSet) Creates a new NSSet whose members are in this NSSet but not in otherSet.
NSSet	setByUnioningSet(NSSet otherSet) Creates a new NSSet whose members are in this NSSet or in otherSet, or both.
int	size()
Object[]	toArray()
Object[]	toArray(Object[] objects)
String	toString() The string has the form "(object1, object2, ...)".

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

EmptySet

public static final NSSet EmptySet

A shared NSSet instance containing no members.

CheckForNull

public static final boolean CheckForNull

Convenience for the constructor methods

See Also:

Constant Field Values

IgnoreNull

public static final boolean IgnoreNull

Convenience for the constructor methods

See Also:

Constant Field Values

Constructor Detail

NSSet

public NSSet()

Creates an empty NSSet. To improve performance, use the EmptySet constant.

See Also:

NSSet.EmptySet

NSSet

public NSSet(Object object)

Creates an NSSet containing the single object. Note: NSSet assumes that member objects are immutable. If your member objects are mutable, you should make copies of them and add the copies to the set.

Parameters:

object - single object contained in the new NSSet

NSSet

public NSSet(Object[] objects)

Creates an NSSet containing all the elements in objects Note: NSSet assumes that the member objects are immutable. If your member objects are mutable, you should make copies of them and add the copies to the set.

Parameters:

objects - array of objects to be contained in the new NSSet

NSSet

public NSSet(NSArray objects)

Creates an NSSet containing all the elements in objects Note: NSSet assumes that the member objects are immutable. If your member objects are mutable, you should make copies of them and add the copies to the set.

Parameters:

objects - array of objects to be contained in the new NSSet

NSSet

public NSSet(NSSet otherSet)

Creates a new NSSet containing the same objects as another NSSet. One should use immutableClone instead. Note: NSSet assumes that the member objects are immutable. If your member objects are mutable, you should make copies of them and add the copies to the set.

Parameters:

otherSet - the set to duplicate

See Also:

NSSet.immutableClone(), NSSet.mutableClone(), NSSet.clone()

NSSet

public NSSet(Set set,
             boolean ignoreNull)

Creates an NSSet containing all the elements in set

Parameters:

set - object that implements java.util.Set

ignoreNull - whether to ignore null values in vector or throw exception

Throws:

IllegalArgumentException - if a null element exists in Set or the Set parameter is null.

Since:

5.3

See Also:

Set

NSSet

public NSSet(Collection collection)

Creates an NSSet containing all the elements in collection

Parameters:

collection - object that implements java.util.Collection

Throws:

IllegalArgumentException - if a null element exists in collection or java.lang.NullPointerException if the collection parameter is null.

Since:

5.4

See Also:

Set

Method Detail

objectsNoCopy

protected Object[] objectsNoCopy()

This method should be used only by subclasses. It will avoid making copies whenever possible.

Returns:

an array with the members of this NSSet.

count

public int count()

Returns:

number of members in this NSSet.

member

public Object member(Object object)

Determines whether an object is a member of this NSSet based on the results of the object's equals method.

Parameters:

object - object to search for in this NSSet

Returns:

the equivalent object matching object from this NSSet, or null if object is not a member.

See Also:

Object.equals(java.lang.Object)

setByIntersectingSet

public NSSet setByIntersectingSet(NSSet otherSet)

Creates a new NSSet that is the result of intersecting another NSSet with this NSSet. Returns a set of objects that are in both this set and otherSet.

Parameters:

otherSet - NSSet to intersect this NSSet with

Returns:

a new NSSet with the members that this NSSet and otherSet have in common

See Also:

NSSet.intersectsSet(com.webobjects.foundation.NSSet), NSSet.isSubsetOfSet(com.webobjects.foundation.NSSet), NSSet.setBySubtractingSet(com.webobjects.foundation.NSSet), NSSet.setByUnioningSet(com.webobjects.foundation.NSSet)

setBySubtractingSet

public NSSet setBySubtractingSet(NSSet otherSet)

Creates a new NSSet whose members are in this NSSet but not in otherSet.

Parameters:

otherSet - NSSet whose members are subtracted from this NSSet

Returns:

a new NSSet whose members are in this NSSet but not in otherSet

See Also:

NSSet.intersectsSet(com.webobjects.foundation.NSSet), NSSet.isSubsetOfSet(com.webobjects.foundation.NSSet), NSSet.setByIntersectingSet(com.webobjects.foundation.NSSet), NSSet.setByUnioningSet(com.webobjects.foundation.NSSet)

setByUnioningSet

public NSSet setByUnioningSet(NSSet otherSet)

Creates a new NSSet whose members are in this NSSet or in otherSet, or both.

Parameters:

otherSet - NSSet whose members are added to this NSSet

Returns:

a new NSSet whose members are in this NSSet or in otherSet

See Also:

NSSet.intersectsSet(com.webobjects.foundation.NSSet), NSSet.isSubsetOfSet(com.webobjects.foundation.NSSet), NSSet.setByIntersectingSet(com.webobjects.foundation.NSSet), NSSet.setBySubtractingSet(com.webobjects.foundation.NSSet)

containsObject

public boolean containsObject(Object object)

Indicates whether a object is a member of this NSSet as determined by equals

Parameters:

object - object to search for in this NSSet

Returns:

true if object is a member of this NSSet

See Also:

NSSet.member(java.lang.Object)

intersectsSet

public boolean intersectsSet(NSSet otherSet)

The result of this method corresponds to the mathematical concept of disjoint sets: if the sets are not disjoint, this method returns true; otherwise, it returns false.

Parameters:

otherSet - NSSet this NSSet is compared against

Returns:

true if at least one object in this NSSet is also a member of otherSet

See Also:

NSSet.isSubsetOfSet(com.webobjects.foundation.NSSet)

isSubsetOfSet

public boolean isSubsetOfSet(NSSet otherSet)

Determines whether every member of this NSSet is a member of otherSet.

Parameters:

otherSet - the potential superset

Returns:

true if this NSSet is a subset of otherSet

See Also:

NSSet.intersectsSet(com.webobjects.foundation.NSSet)

isEqualToSet

public boolean isEqualToSet(NSSet otherSet)

Provided for backward compatibility. Use equals instead.

Parameters:

otherSet - NSSet this NSSet is compared against

Returns:

true if the contents of otherSet are equal to the contents of this NSSet

See Also:

NSSet.equals(java.lang.Object)

equals

public boolean equals(Object object)

Determines whether this NSSet is equal to object This is true if object is an NSSet or subclass of NSSet and both sets contain identical members. Two sets have equal contents if they each have the same number of members and if each member matches a member in the other set as determined by equals.

Specified by:

equals in interface Collection

Specified by:

equals in interface Set

Overrides:

equals in class Object

Parameters:

object - the object this NSSet is compared against

Returns:

true if object is an NSSet equal to this NSSet

See Also:

Object.equals(java.lang.Object), NSSet.intersectsSet(com.webobjects.foundation.NSSet), NSSet.isSubsetOfSet(com.webobjects.foundation.NSSet)

anyObject

public Object anyObject()

Returns one of the objects in this set, essentially chosen at random, or null if the set contains no objects.

Returns:

one of the objects in this NSSet or null if this NSSet is empty

See Also:

NSSet.allObjects(), NSSet.objectEnumerator()

allObjects

public NSArray allObjects()

Provides an array with all the members of this NSSet. The order of the objects in the array returned is not defined.

Returns:

array containing this NSSet's members or an empty array if this NSSet doesn't have any members.

See Also:

NSSet.anyObject(), NSSet.objectEnumerator()

objectEnumerator

public Enumeration objectEnumerator()

Provides an Enumeration object that can be used to access each member of this NSSet. When using this method with mutable subclasses of NSSet, your code shouldn't modify the set during enumeration. If you intend to modify the set, use the allObjects method to create a snapshot of this set's members. Enumerate over the snapshot, but make your modifications to the original set.

Returns:

an Enumeration for this NSSet

See Also:

NSSet.allObjects(), Enumeration

classForCoder

public Class classForCoder()

Conformance with NSCoding.

Specified by:

classForCoder in interface NSCoding

Returns:

NSSet.class

See Also:

NSCoding

decodeObject

public static Object decodeObject(NSCoder coder)

Creates an NSSet from the data in an NSCoder.

Parameters:

coder - NSCoder from which the new NSSet's members are derived from

Returns:

a new NSSet

See Also:

NSCoding

encodeWithCoder

public void encodeWithCoder(NSCoder coder)

Description copied from interface: NSCoding

Encodes the receiver using coder. Object type information along with an object's data is stored.

Specified by:

encodeWithCoder in interface NSCoding

Parameters:

coder - an NSCoder object that will be used to encode object of classes that implement this interface

See Also:

NSCoder

hashCode

public int hashCode()

Provides an appropriate hash code useful for storing this NSSet in a hash-based data structure. This value is the number of objects in the set.

Specified by:

hashCode in interface Collection

Specified by:

hashCode in interface Set

Overrides:

hashCode in class Object

Returns:

this NSSet's hash code.

See Also:

Object.hashCode()

hashSet

public HashSet hashSet()

Creates a java.util.HashSet with the same contents as this object.

Returns:

a java.util.HashSet with the same elements as this NSSet

Since:

5.3

clone

public Object clone()

Since NSSets are immutable, there's no need to make an actual copy. Overriden by mutable subclases.

Overrides:

clone in class Object

Returns:

this

See Also:

Object.clone(), NSSet.immutableClone(), NSSet.mutableClone()

immutableClone

public NSSet immutableClone()

Since the NSSets are immutable, there's no need to make an actual

Returns:

an immutable clone of this NSSet

See Also:

NSSet.mutableClone(), Object.clone()

mutableClone

public NSMutableSet mutableClone()

This method creates a duplicate NSMutableSet with the same objects.

Returns:

a mutable copy of this NSSet

See Also:

NSSet.immutableClone(), Object.clone()

toString

public String toString()

The string has the form "(object1, object2, ...)".

Overrides:

toString in class Object

Returns:

a string representation of this NSSet

emptySet

public static final NSSet emptySet()

Returns the empty NSSet (immutable). This set is serializable.

This example illustrates the type-safe way to obtain an empty list:

 Set<String>      s       = NSSet.emptySet();
 

Implementation note: Implementations of this method need not create a separate NSSet object for each call. Using this method is likely to have comparable cost to using the like-named field. (Unlike this method, the field does not provide type safety.)

Since:

5.4

See Also:

NSSet.EmptySet

size

public int size()

Specified by:

size in interface Collection

Specified by:

size in interface Set

Since:

5.3

See Also:

Set.size()

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface Collection

Specified by:

isEmpty in interface Set

Since:

5.3

See Also:

Set.isEmpty()

contains

public boolean contains(Object o)

NSSets cannot contain null values and therefore do not adhere to the java.util.Set specification

Specified by:

contains in interface Collection

Specified by:

contains in interface Set

Since:

5.3

See Also:

Set.contains(java.lang.Object)

containsAll

public boolean containsAll(Collection c)

Specified by:

containsAll in interface Collection

Specified by:

containsAll in interface Set

Parameters:

c - - collection to be checked for containment in this set

Throws:

NullPointerException - if c is null

Since:

5.3

See Also:

Set.containsAll(java.util.Collection)

iterator

public Iterator iterator()

Specified by:

iterator in interface Iterable

Specified by:

iterator in interface Collection

Specified by:

iterator in interface Set

Since:

5.3

See Also:

Set.iterator()

toArray

public Object[] toArray()

Specified by:

toArray in interface Collection

Specified by:

toArray in interface Set

Since:

5.3

See Also:

Set.toArray()

toArray

public Object[] toArray(Object[] objects)

Specified by:

toArray in interface Collection

Specified by:

toArray in interface Set

Throws:

NullPointerException - for a == null

Since:

5.3

See Also:

Set.toArray()

add

public boolean add(Object o)

Operation not supported

Specified by:

add in interface Collection

Specified by:

add in interface Set

Throws:

UnsupportedOperationException

Since:

5.3

See Also:

Set.add(E)

remove

public boolean remove(Object o)

Operation not supported

Specified by:

remove in interface Collection

Specified by:

remove in interface Set

Throws:

UnsupportedOperationException

Since:

5.3

See Also:

Set.remove(java.lang.Object)

addAll

public boolean addAll(Collection c)

Operation not supported

Specified by:

addAll in interface Collection

Specified by:

addAll in interface Set

Throws:

UnsupportedOperationException

Since:

5.3

See Also:

Set.addAll(java.util.Collection)

retainAll

public boolean retainAll(Collection c)

Operation not supported

Specified by:

retainAll in interface Collection

Specified by:

retainAll in interface Set

Throws:

UnsupportedOperationException

Since:

5.3

See Also:

Set.retainAll(java.util.Collection)

removeAll

public boolean removeAll(Collection c)

Operation not supported

Specified by:

removeAll in interface Collection

Specified by:

removeAll in interface Set

Throws:

UnsupportedOperationException

Since:

5.3

See Also:

Set.removeAll(java.util.Collection)

clear

public void clear()

Operation not supported

Specified by:

clear in interface Collection

Specified by:

clear in interface Set

Throws:

UnsupportedOperationException

Since:

5.3

See Also:

Set.clear()