WebObjects 5.4.2

com.webobjects.foundation
Class NSSet

java.lang.Object
  extended by 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()

Last updated June 2008

Copyright © 2000-2008 Apple Inc.