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.

setBySubtractingSet

public NSSet setBySubtractingSet(NSSet otherSet)

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

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.

toString

public String toString()

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