WebObjects 5.2

com.webobjects.foundation
Class NSSet

java.lang.Object
  |
  +--com.webobjects.foundation.NSSet
All Implemented Interfaces:
Cloneable, NSCoding, Serializable
Direct Known Subclasses:
NSMutableSet

public class NSSet
extends Object
implements Cloneable, Serializable, NSCoding

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
MethodDescription
countreturns the number of members in the set
member returns the object in the set that is equal to the specified object
objectsNoCopyreturns 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, count(), allObjects(), member(java.lang.Object), intersectsSet(com.webobjects.foundation.NSSet), Serialized Form

Inner classes inherited from class com.webobjects.foundation.NSCoding
NSCoding.Support
 
Field Summary
static NSSet EmptySet
          A shared NSSet instance containing no members.
 
Constructor Summary
NSSet()
          Creates an empty NSSet.
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(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.
 
Method Summary
 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.
 Object clone()
          Since NSSets are immutable, there's no need to make an actual copy.
 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.
 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.
 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 isEqualToSet(NSSet otherSet)
          Provided for backward compatibility.
 boolean isSubsetOfSet(NSSet otherSet)
          Determines whether every member of this NSSet is a member of otherSet.
 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.
 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.
 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.
Constructor Detail

NSSet

public NSSet()
Creates an empty NSSet. To improve performance, use the EmptySet constant.
See Also:
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:
immutableClone(), mutableClone(), clone()
Method Detail

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:
anyObject(), objectEnumerator()

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:
allObjects(), objectEnumerator()

classForCoder

public Class classForCoder()
Conformance with NSCoding.
Specified by:
classForCoder in interface NSCoding
Returns:
NSSet.class
See Also:
NSCoding

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(), immutableClone(), mutableClone()

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:
member(java.lang.Object)

count

public int count()
Returns:
number of members in this NSSet.

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
Following copied from interface: com.webobjects.foundation.NSCoding
Parameters:
coder - an NSCoder object that will be used to encode object of classes that implement this interface
See Also:
NSCoder

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.
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), intersectsSet(com.webobjects.foundation.NSSet), isSubsetOfSet(com.webobjects.foundation.NSSet)

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.
Overrides:
hashCode in class Object
Returns:
this NSSet's hash code.
See Also:
Object.hashCode()

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:
mutableClone(), Object.clone()

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:
isSubsetOfSet(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:
equals(java.lang.Object)

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:
intersectsSet(com.webobjects.foundation.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)

mutableClone

public NSMutableSet mutableClone()
This method creates a duplicate NSMutableSet with the same objects.
Returns:
a mutable copy of this NSSet
See Also:
immutableClone(), Object.clone()

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:
allObjects(), Enumeration

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.

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:
intersectsSet(com.webobjects.foundation.NSSet), isSubsetOfSet(com.webobjects.foundation.NSSet), setBySubtractingSet(com.webobjects.foundation.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:
intersectsSet(com.webobjects.foundation.NSSet), isSubsetOfSet(com.webobjects.foundation.NSSet), setByIntersectingSet(com.webobjects.foundation.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:
intersectsSet(com.webobjects.foundation.NSSet), isSubsetOfSet(com.webobjects.foundation.NSSet), setByIntersectingSet(com.webobjects.foundation.NSSet), setBySubtractingSet(com.webobjects.foundation.NSSet)

toString

public String toString()
The string has the form "(object1, object2, ...)".
Overrides:
toString in class Object
Returns:
a string representation of this NSSet

Last updated Fri Feb 21 13:15:00 PST 2003.

Copyright © 2003 Apple Computer, Inc.