com.webobjects.foundation
Class NSMutableSet

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

All Implemented Interfaces:

NSCoding, Serializable, Cloneable, Iterable, Collection, Set

public class NSMutableSet
extends NSSet

NSMutableSet provides support for the mathematical concept of a set which, unlike its parent NSSet, may have members added or removed after its creation.

The following table describes the NSMutableSet methods that provide the basis for all NSMutableSet's other methods; that is, all other methods are implemented in terms of these five. If you create a subclass of NSMutableSet, 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.

NSMutableSet'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.
removeAllObjects	Empties the set of all its members.
removeObject	Removes the specified object from the set.

Objects are removed from an NSMutableSet using any of the methods intersectSet, removeAllObjects, removeObject or subtractSet.

Objects are added to an NSMutableSet with addObject, which adds a single object to the set; addObjectsFromArray, which adds all objects from a specified array to the set; or with unionSet, which adds all the objects from another set.

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 guarentee that the members do not change with respect to either the equals or hashCode methods.

See Also:

Set, HashSet, NSMutableSet.addObject(java.lang.Object), NSMutableSet.removeObject(java.lang.Object), NSMutableSet.removeAllObjects(), NSMutableSet.unionSet(com.webobjects.foundation.NSSet), NSMutableSet.intersectSet(com.webobjects.foundation.NSSet), NSMutableSet.subtractSet(com.webobjects.foundation.NSSet), NSMutableSet.addObjectsFromArray(com.webobjects.foundation.NSArray), Serialized Form

Nested Class Summary

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

NSCoding.Support

Field Summary

Fields inherited from class com.webobjects.foundation.NSSet

CheckForNull, EmptySet, IgnoreNull

Constructor Summary

NSMutableSet()
Creates an empty NSMutableSet.

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

NSMutableSet(Object object)
Creates an NSMutableSet containing a single object object.

NSMutableSet(Object[] objects)
Creates an NSMutableSet containing the all the elements in objects.

NSMutableSet(int capacity)
Creates an empty NSMutableSet prepared to hold at least capacity members.

NSMutableSet(NSArray objects)
Creates an NSMutableSet containing the all the elements in objects.

NSMutableSet(NSSet otherSet)
Creates an NSMutableSet containing all the members in otherSet.

Method Summary

boolean	add(Object element) Operation not supported
boolean	addAll(Collection collection) Operation not supported
void	addObject(Object object) Adds the specified object to this set if it is not already a member.
void	addObjectsFromArray(NSArray array) Adds each object contained in array to this set, if the object is not already a member.
void	clear() Operation not supported
Object	clone() Creates a clone of the receiver.
NSSet	immutableClone() Creates a new NSSet which has the same members as this set.
void	intersectSet(NSSet otherSet) Removes from this set each object that is not a member of otherSet.
NSMutableSet	mutableClone() Creates a new NSMutableSet which has the same members as this set.
boolean	remove(Object element) Operation not supported
boolean	removeAll(Collection collection) Operation not supported
void	removeAllObjects() Empties the set of all its members.
Object	removeObject(Object object) Removes object from the set.
boolean	retainAll(Collection collection) Operation not supported
void	setSet(NSSet otherSet) Makes this set contain exactly the same members as otherSet The current members in this set are discarded.
void	subtractSet(NSSet otherSet) Removes from this set each object contained in otherSet that is also currently a member of this set.
void	unionSet(NSSet otherSet) Adds each object contained in otherSet to this set, if that object is not already a member.

Methods inherited from class com.webobjects.foundation.NSSet

allObjects, anyObject, classForCoder, contains, containsAll, containsObject, count, decodeObject, emptySet, encodeWithCoder, equals, hashCode, hashSet, intersectsSet, isEmpty, isEqualToSet, isSubsetOfSet, iterator, member, objectEnumerator, objectsNoCopy, setByIntersectingSet, setBySubtractingSet, setByUnioningSet, size, toArray, toArray, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

NSMutableSet

public NSMutableSet()

Creates an empty NSMutableSet.

For better performance, one should use NSMutableSet(int capacity) instead.

See Also:

NSMutableSet.NSMutableSet(int capacity)

NSMutableSet

public NSMutableSet(int capacity)

Creates an empty NSMutableSet prepared to hold at least capacity members. NSMutableSets grow as necessary, so this is a recommended performance enhancement.

Parameters:

capacity - a size hint for the expected number of members

NSMutableSet

public NSMutableSet(Object object)

Creates an NSMutableSet containing a single object object.

Note: NSMutableSet 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 - the single member object contained in the set

NSMutableSet

public NSMutableSet(Object[] objects)

Creates an NSMutableSet containing the all the elements in objects.

Note: NSMutableSet 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:

objects - an array of initial members for the new set

NSMutableSet

public NSMutableSet(NSArray objects)

Creates an NSMutableSet containing the all the elements in objects.

Note: NSMutableSet 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:

objects - an array of initial members for the new set

NSMutableSet

public NSMutableSet(NSSet otherSet)

Creates an NSMutableSet containing all the members in otherSet. One should use mutableClone instead.

Parameters:

otherSet - the set to duplicate

See Also:

NSMutableSet.mutableClone()

NSMutableSet

public NSMutableSet(Collection collection)

Creates an NSMutableSet containing all the elements in collection

Parameters:

collection - object that implements java.util.Collection

Throws:

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

Since:

5.4

See Also:

Set

Method Detail

addObject

public void addObject(Object object)

Adds the specified object to this set if it is not already a member.

If object is already present in the set, this method has no effect on either the set or on object.

Note: NSMutableSet 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 - the new member

See Also:

NSMutableSet.addObjectsFromArray(com.webobjects.foundation.NSArray), NSMutableSet.unionSet(com.webobjects.foundation.NSSet)

removeObject

public Object removeObject(Object object)

Removes object from the set.

Parameters:

object - object that is to be removed from the set

Returns:

the equivalent object removed from this set, or null if object was not a member

See Also:

NSMutableSet.removeAllObjects(), NSMutableSet.intersectSet(com.webobjects.foundation.NSSet), NSMutableSet.subtractSet(com.webobjects.foundation.NSSet)

removeAllObjects

public void removeAllObjects()

Empties the set of all its members.

See Also:

NSMutableSet.removeObject(java.lang.Object), NSMutableSet.intersectSet(com.webobjects.foundation.NSSet), NSMutableSet.subtractSet(com.webobjects.foundation.NSSet)

setSet

public void setSet(NSSet otherSet)

Makes this set contain exactly the same members as otherSet The current members in this set are discarded.

Parameters:

otherSet - the new members for this set

addObjectsFromArray

public void addObjectsFromArray(NSArray array)

Adds each object contained in array to this set, if the object is not already a member. If a given element of the array is already present in the set, this method has no effect on either the set or on the array element.

Note: NSMutableSet 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:

array - objects are contained in this

See Also:

NSMutableSet.addObject(java.lang.Object), NSMutableSet.unionSet(com.webobjects.foundation.NSSet)

intersectSet

public void intersectSet(NSSet otherSet)

Removes from this set each object that is not a member of otherSet.

Parameters:

otherSet - objects that are not members of otherSet are removed

See Also:

NSMutableSet.removeObject(java.lang.Object), NSMutableSet.removeAllObjects(), NSMutableSet.subtractSet(com.webobjects.foundation.NSSet)

subtractSet

public void subtractSet(NSSet otherSet)

Removes from this set each object contained in otherSet that is also currently a member of this set. If any member of otherSet is not present in this set, this method has no effect on that member.

Parameters:

otherSet - objects contained in otherSet are removed if they are also members of this set

See Also:

NSMutableSet.removeObject(java.lang.Object), NSMutableSet.removeAllObjects(), NSMutableSet.intersectSet(com.webobjects.foundation.NSSet)

unionSet

public void unionSet(NSSet otherSet)

Adds each object contained in otherSet to this set, if that object is not already a member. If any member of otherSet is already a member of this set, this method has no effect on that member.

Parameters:

otherSet - each object contained in otherSet are added to this set

See Also:

NSMutableSet.addObject(java.lang.Object), NSMutableSet.addObjectsFromArray(com.webobjects.foundation.NSArray)

clone

public Object clone()

Creates a clone of the receiver. NSMutableSet's implementation simply creates a new NSMutableSet with the same members as this set.

Overrides:

clone in class NSSet

Returns:

creates a clone of this NSMutableSet

See Also:

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

immutableClone

public NSSet immutableClone()

Creates a new NSSet which has the same members as this set.

Overrides:

immutableClone in class NSSet

Returns:

an immutable copy (an NSSet) of this set.

See Also:

Object.clone(), NSMutableSet.mutableClone()

mutableClone

public NSMutableSet mutableClone()

Creates a new NSMutableSet which has the same members as this set.

Overrides:

mutableClone in class NSSet

Returns:

an NSMutableSet which is a duplicate of this set

See Also:

Object.clone(), NSMutableSet.immutableClone()

remove

public boolean remove(Object element)

Description copied from class: NSSet

Operation not supported

Specified by:

remove in interface Collection

Specified by:

remove in interface Set

Overrides:

remove in class NSSet

Parameters:

element - to be removed from this list, if present.

Since:

5.4

See Also:

Collection.remove(java.lang.Object)

clear

public void clear()

Description copied from class: NSSet

Operation not supported

Specified by:

clear in interface Collection

Specified by:

clear in interface Set

Overrides:

clear in class NSSet

Since:

5.4

See Also:

Collection.clear(), NSMutableSet.removeAllObjects()

retainAll

public boolean retainAll(Collection collection)

Description copied from class: NSSet

Operation not supported

Specified by:

retainAll in interface Collection

Specified by:

retainAll in interface Set

Overrides:

retainAll in class NSSet

Since:

5.4

See Also:

Collection.retainAll(java.util.Collection)

removeAll

public boolean removeAll(Collection collection)

Description copied from class: NSSet

Operation not supported

Specified by:

removeAll in interface Collection

Specified by:

removeAll in interface Set

Overrides:

removeAll in class NSSet

Since:

5.4

See Also:

Collection.removeAll(java.util.Collection)

add

public boolean add(Object element)

Description copied from class: NSSet

Operation not supported

Specified by:

add in interface Collection

Specified by:

add in interface Set

Overrides:

add in class NSSet

Parameters:

element - - object to add

Since:

5.4

See Also:

Collection.add(E)

addAll

public boolean addAll(Collection collection)

Description copied from class: NSSet

Operation not supported

Specified by:

addAll in interface Collection

Specified by:

addAll in interface Set

Overrides:

addAll in class NSSet

Parameters:

collection - - collection to add

Since:

5.4

See Also:

Collection.addAll(java.util.Collection)