Documentation Archive Developer
Search
PATH Documentation > WebObjects

Table of Contents

NSSet


Inherits from:
Object
Implements:
Cloneable
java.io.Serializable
NSCoding
Package:
com.webobjects.foundation


Class Description


The NSSet and NSMutableSet classes declare the programmatic interface to an object that manages a set of objects. NSSet provides support for the mathematical concept of a set. A set, both in its mathematical sense and in the implementation of NSSet, is an unordered collection of distinct elements. The NSMutableSet class is provided for sets whose contents may be altered.

NSSet declares the programmatic interface for static sets of objects. You establish a static set's entries when it's created, and thereafter the entries can't be modified. NSMutableSet, on the other hand, declares a programmatic interface for dynamic sets of objects. A dynamic-or mutable-set allows the addition and deletion of entries at any time, automatically allocating memory as needed.

Use sets as an alternative to arrays when the order of elements isn't important and performance in testing whether an object is contained in the set is a consideration-while arrays are ordered, testing for membership is slower than with sets. When testing for set membership, the equals method is invoked only once.

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 you expect your members to change for any reason, you should make copies of them and add the copies to the set.

Table 0-13 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 your subclass's inherited methods operate properly.


Table 0-13 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.




Constants


NSSet provides the following constant as a convenience; you can use it when you need an empty set.


Constant Type Description
EmptySet NSSet A shared NSSet instance containing no members.



Interfaces Implemented


Cloneable
clone
java.io.Serializable
NSCoding
classForCoder
decodeObject
encodeWithCoder


Method Types


Constructors
NSSet
Counting entries
count
Accessing the members
allObjects
anyObject
containsObject
member
objectEnumerator
objectsNoCopy
Comparing sets
intersectsSet
isEqualToSet
isSubsetOfSet
Joining sets
setByIntersectingSet
setBySubtractingSet
setByUnioningSet
Methods inherited from Object
equals
hashCode
toString
Copying sets
immutableClone
mutableClone


Constructors



NSSet

public NSSet()

Creates an empty NSSet. To improve performance, use the EmptySet shared instance. See Constants.

public NSSet(NSArray anArray)

Creates an NSSet containing the objects in anArray.
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.

public NSSet(NSSet aSet)

Creates an NSSet containing the objects in aSet.

public NSSet(Object object)

Creates an NSSet containing the single object 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.

public NSSet(Object[] objects[])

Creates an NSSet containing the objects in the objects language array.
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.




Static Methods



decodeObject

public static Object decodeObject(NSCoder coder)

Creates an NSSet from the data in coder.

See Also: NSCoding




Instance Methods



allObjects

public NSArray allObjects()

Returns an array containing the receiver's members, or an empty array if the receiver has no members. The order of the objects in the array isn't defined.

See Also: anyObject, objectEnumerator



anyObject

public Object anyObject()

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

See Also: allObjects, objectEnumerator



classForCoder

public Class classForCoder()

Conformance with NSCoding. Please see the method description of classForCoder in the interface specification for NSCoding.

clone

public Object clone()

Returns a copy (a NSSet object) of the receiver. Since NSSets are immutable, there's no need to make an actual copy.

containsObject

public boolean containsObject(Object anObject)

Returns true if anObject is present in the set, false otherwise.

See Also: member



count

public int count()

Returns the number of members in the set.

encodeWithCoder

public void encodeWithCoder(NSCoder aNSCoder)

Conformance with NSCoding. Please see the method description of encodeWithCoder in the interface specification for NSCoding.

equals

public boolean equals(Object anObject)

Compares the receiving set to anObject. If anObject is an NSSet and the contents of anObject are equal to the contents of the receiver, this method returns true. If not, it returns false.

hashCode

public int hashCode()

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

immutableClone

public NSSet immutableClone()

Returns an immutable copy (an NSSet) of the receiver. Since the NSSets are immutable, there's no need to make an actual copy.

intersectsSet

public boolean intersectsSet(NSSet otherSet)

Returns true if at least one object in the receiver is also present in otherSet, false otherwise. The result of this method corresponds to the mathematical concept of disjoint sets: if the sets are not disjoint, intersectsSet returns true, otherwise it returns false.

See Also: isEqualToSet, isSubsetOfSet



isEqualToSet

public boolean isEqualToSet(NSSet otherSet)

Compares the receiving set to otherSet. If the contents of otherSet are equal to the contents of the receiver, this method returns true. If not, it returns false.

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).

See Also: intersectsSet, isSubsetOfSet



isSubsetOfSet

public boolean isSubsetOfSet(NSSet otherSet)

Returns true if every object in the receiver is also present in otherSet, false otherwise.

See Also: intersectsSet, isEqualToSet



member

public Object member(Object anObject)

If anObject is present in the set (as determined by equals), the object in the set is returned. Otherwise returns null.

mutableClone

public NSMutableSet mutableClone()

Returns a mutable set (an NSMutableSet) with the same members as the receiver.

objectEnumerator

public java.util.Enumeration objectEnumerator()

Returns an enumerator object that lets you access each object in the set


java.util.Enumeration enumerator = mySet.objectEnumerator();

while (enumerator.hasMoreElements()) {{
    Object anObject = enumerator.nextElement(); 
    /* code to act on each element */
}

When this method is used 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 the set's members. Enumerate the snapshot, but make your modifications to the original set.



objectsNoCopy

protected Object[] objectsNoCopy()

Returns the actual array of objects contained in the set.

setByIntersectingSet

public NSSet setByIntersectingSet(NSSet otherSet)

Returns a set of objects that are in both the receiver and otherSet.

See Also: intersectsSet, isSubsetOfSet, isEqualToSet, setBySubtractingSet, setByUnioningSet



setBySubtractingSet

public NSSet setBySubtractingSet(NSSet otherSet)

Returns a set of objects that are in the receiver but not in otherSet.

See Also: intersectsSet, isSubsetOfSet, isEqualToSet, setByIntersectingSet, setByUnioningSet



setByUnioningSet

public NSSet setByUnioningSet(NSSet otherSet)

Returns a set of objects that are either in the receiver or in otherSet or both. If an object is in both, the resulting set contains it only once.

See Also: intersectsSet, isSubsetOfSet, isEqualToSet, setByIntersectingSet, setBySubtractingSet



toString

public String toString()

Returns a string representation of the receiver. The string has the form "(object1, object2, ...)".

© 2001 Apple Computer, Inc. (Last Published April 17, 2001)


Table of Contents