Class: NSSet

Inherits:
NSObject show all

Overview

The NSSet, NSMutableSet, and NSCountedSet classes declare the programmatic interface to an unordered collection of objects.

Direct Known Subclasses

NSMutableSet

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods inherited from NSObject

#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, #init, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version

Constructor Details

This class inherits a constructor from NSObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class NSObject

Class Method Details

+ (Object) set

Creates and returns an empty set. This method is declared primarily for the use of mutable subclasses of NSSet.

Returns:

  • (Object) —

    A new empty set.

+ (Object) setWithArray(array)

Creates and returns a set containing a uniqued collection of the objects contained in a given array.

Parameters:

  • array (Array) —

    An array containing the objects to add to the new set. If the same object appears more than once in array, it is added only once to the returned set. Each object receives a retain message as it is added to the set.

Returns:

  • (Object) —

    A new set containing a uniqued collection of the objects contained in array.

+ (Object) setWithObject(object)

Creates and returns a set that contains a single given object.

Parameters:

  • object (Object) —

    The object to add to the new set. object receives a retain message after being added to the set.

Returns:

  • (Object) —

    A new set that contains a single member, object.

+ (Object) setWithObjects(firstObj, ...)

Creates and returns a set containing the objects in a given argument list. As an example, the following code excerpt creates a set containing three different types of elements (assuming aPath exits):

Parameters:

  • firstObj —

    The first object to add to the new set.

  • firstObj, —

    ... A comma-separated list of objects, ending with nil, to add to the new set. If the same object appears more than once in the list of objects, it is added only once to the returned set. Each object receives a retain message as it is added to the set.

Returns:

  • (Object) —

    A new set containing the objects in the argument list.

+ (Object) setWithObjects(objects, count:cnt)

Creates and returns a set containing a specified number of objects from a given C array of objects.

Parameters:

  • objects (Object) —

    A C array of objects to add to the new set. If the same object appears more than once in objects, it is added only once to the returned set. Each object receives a retain message as it is added to the set.

  • cnt (Integer) —

    The number of objects from objects to add to the new set.

Returns:

  • (Object) —

    A new set containing cnt objects from the list of objects specified by objects.

+ (Object) setWithSet(set)

Creates and returns a set containing the objects from another set.

Parameters:

  • set (NSSet) —

    A set containing the objects to add to the new set. Each object receives a retain message as it is added to the new set.

Returns:

  • (Object) —

    A new set containing the objects from set.

Instance Method Details

- (Object) addObserver(observer, forKeyPath:keyPath, options:options, context:context)

Raises an exception.

Parameters:

  • observer (NSObject) —

    The object to register for KVO notifications. The observer must implement the key-value observing method observeValueForKeyPath:ofObject:change:context:.

  • keyPath (String) —

    The key path, relative to the set, of the property to observe. This value must not be nil.

  • options (NSKeyValueObservingOptions) —

    A combination of the NSKeyValueObservingOptions values that specifies what is included in observation notifications. For possible values, see NSKeyValueObservingOptions.

  • context (Object) —

    Arbitrary data that is passed to observer in observeValueForKeyPath:ofObject:change:context:.

Returns:

- (Array) allObjects

Returns an array containing the set’s members, or an empty array if the set has no members.

Returns:

  • (Array) —

    An array containing the set’s members, or an empty array if the set has no members. The order of the objects in the array isn’t defined.

- (Object) anyObject

Returns one of the objects in the set, or nil if the set contains no objects.

Returns:

  • (Object) —

    One of the objects in the set, or nil if the set contains no objects. The object returned is chosen at the set’s convenience—the selection is not guaranteed to be random.

- (Boolean) containsObject(anObject)

Returns a Boolean value that indicates whether a given object is present in the set.

Parameters:

  • anObject (Object) —

    The object for which to test membership of the set.

Returns:

  • (Boolean) —

    YES if anObject is present in the set, otherwise NO.

- (Integer) count

Returns the number of members in the set.

Returns:

  • (Integer) —

    The number of members in the set.

- (String) description

Returns a string that represents the contents of the set, formatted as a property list.

Returns:

  • (String) —

    A string that represents the contents of the set, formatted as a property list.

- (String) descriptionWithLocale(locale)

Returns a string that represents the contents of the set, formatted as a property list. This method sends each of the set’s members descriptionWithLocale: with locale passed as the sole parameter. If the set’s members do not respond to descriptionWithLocale:, this method sends description instead.

Parameters:

  • locale (Object) —

    On iOS and OS X v10.5 and later, either an instance of NSDictionary or an NSLocale object may be used for locale.On OS X v10.4 and earlier it must be an instance of NSDictionary.

Returns:

  • (String) —

    A string that represents the contents of the set, formatted as a property list.

- (Object) enumerateObjectsUsingBlock(block)

Executes a given Block using each object in the set.

Parameters:

  • block —

    The Block to apply to elements in the set.The Block takes two arguments:objThe element in the set.stopA reference to a Boolean value. The block can set the value to YES to stop further processing of the set. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.The Block returns a Boolean value that indicates whether obj passed the test.

  • obj —

    The element in the set.

  • stop —

    A reference to a Boolean value. The block can set the value to YES to stop further processing of the set. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

Returns:

- (Object) enumerateObjectsWithOptions(opts, usingBlock:block)

Executes a given Block using each object in the set, using the specified enumeration options.

Parameters:

  • opts —

    A bitmask that specifies the options for the enumeration.

  • block —

    The Block to apply to elements in the set.The Block takes two arguments:objThe element in the set.stopA reference to a Boolean value. The block can set the value to YES to stop further processing of the set. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.The Block returns a Boolean value that indicates whether obj passed the test.

  • obj —

    The element in the set.

  • stop —

    A reference to a Boolean value. The block can set the value to YES to stop further processing of the set. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

Returns:

- (NSSet) filteredSetUsingPredicate(predicate)

Evaluates a given predicate against each object in the receiving set and returns a new set containing the objects for which the predicate returns true. The following example illustrates the use of this method.

Parameters:

Returns:

  • (NSSet) —

    A new set containing the objects in the receiving set for which predicate returns true.

- (Object) initWithArray(array)

Initializes a newly allocated set with the objects that are contained in a given array.

Parameters:

  • array (Array) —

    An array of objects to add to the new set. If the same object appears more than once in array, it is represented only once in the returned set. Each object receives a retain message as it is added to the set.

Returns:

  • (Object) —

    An initialized set with the contents of array. The returned set might be different than the original receiver.

- (Object) initWithObjects(firstObj, ...)

Initializes a newly allocated set with members taken from the specified list of objects.

Parameters:

  • firstObj —

    The first object to add to the new set.

  • firstObj, —

    ... A comma-separated list of objects, ending with nil, to add to the new set. If the same object appears more than once in the list, it is represented only once in the returned set. Each object receives a retain message as it is added to the set

Returns:

  • (Object) —

    An initialized set containing the objects specified in the parameter list. The returned set might be different than the original receiver.

- (Object) initWithObjects(objects, count:cnt)

Initializes a newly allocated set with a specified number of objects from a given C array of objects. This method is the designated initializer for NSSet.

Parameters:

  • objects (Object) —

    A C array of objects to add to the new set. If the same object appears more than once in objects, it is added only once to the returned set. Each object receives a retain message as it is added to the set.

  • cnt (Integer) —

    The number of objects from objects to add to the new set.

Returns:

  • (Object) —

    An initialized set containing cnt objects from the list of objects specified by objects. The returned set might be different than the original receiver.

- (Object) initWithSet(set)

Initializes a newly allocated set and adds to it objects from another given set.

Parameters:

  • set (NSSet) —

    A set containing objects to add to the receiving set. Each object is retained as it is added.

Returns:

  • (Object) —

    An initialized objects set containing the objects from set. The returned set might be different than the original receiver.

- (Object) initWithSet(set, copyItems:flag)

Initializes a newly allocated set and adds to it members of another given set. After an immutable s has been initialized in this way, it cannot be modified.The copyWithZone: method performs a shallow copy. If you have a collection of arbitrary depth, passing YES for the flag parameter will perform an immutable copy of the first level below the surface. If you pass NO the mutability of the first level is unaffected. In either case, the mutability of all deeper levels is unaffected.

Parameters:

  • set (NSSet) —

    A set containing objects to add to the new set.

  • flag (Boolean) —

    If YES, each object in set receives a copyWithZone: message to create a copy of the object—objects must conform to the NSCopying protocol. In a managed memory environment, this is instead of the retain message the object would otherwise receive. The object copy is then added to the returned set.If NO, then in a managed memory environment each object in set simply receives a retain message when it is added to the returned set.

Returns:

  • (Object) —

    An initialized set that contains the members of set. The returned set might be different than the original receiver.

- (Boolean) intersectsSet(otherSet)

Returns a Boolean value that indicates whether at least one object in the receiving set is also present in another given set.

Parameters:

  • otherSet (NSSet) —

    The set with which to compare the receiving set.

Returns:

  • (Boolean) —

    YES if at least one object in the receiving set is also present in otherSet, otherwise NO.

- (Boolean) isEqualToSet(otherSet)

Compares the receiving set to another set. Two sets have equal contents if they each have the same number of members and if each member of one set is present in the other.

Parameters:

  • otherSet (NSSet) —

    The set with which to compare the receiving set.

Returns:

  • (Boolean) —

    YES if the contents of otherSet are equal to the contents of the receiving set, otherwise NO.

- (Boolean) isSubsetOfSet(otherSet)

Returns a Boolean value that indicates whether every object in the receiving set is also present in another given set.

Parameters:

  • otherSet (NSSet) —

    The set with which to compare the receiving set.

Returns:

  • (Boolean) —

    YES if every object in the receiving set is also present in otherSet, otherwise NO.

- (Object) makeObjectsPerformSelector(aSelector)

Sends a message specified by a given selector to each object in the set. The message specified by aSelector is sent once to each member of the set. This method raises an NSInvalidArgumentException if aSelector is NULL.

Parameters:

  • aSelector (Symbol) —

    A selector that specifies the message to send to the members of the set. The method must not take any arguments. It should not have the side effect of modifying the set. This value must not be NULL.

Returns:

- (Object) makeObjectsPerformSelector(aSelector, withObject:argument)

Sends a message specified by a given selector to each object in the set. The message specified by aSelector is sent, with argument as the argument, once to each member of the set. This method raises an NSInvalidArgumentException if aSelector is NULL.

Parameters:

  • aSelector (Symbol) —

    A selector that specifies the message to send to the set's members. The method must take a single argument of type id. The method should not, as a side effect, modify the set. The value must not be NULL.

  • argument (Object) —

    The object to pass as an argument to the method specified by aSelector.

Returns:

- (Object) member(object)

Determines whether the set contains an object equal to a given object, and returns that object if it is present. If you override isEqual:, you must also override the hash method for the member: method to work on a set of objects of your class.

Parameters:

  • object (Object) —

    The object for which to test for membership of the set.

Returns:

  • (Object) —

    If the set contains an object equal to object (as determined by isEqual:) then that object (typically this will be object), otherwise nil.

- (NSEnumerator) objectEnumerator

Returns an enumerator object that lets you access each object in the set. The following code fragment illustrates how you can use this method. 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.

Returns:

  • (NSEnumerator) —

    An enumerator object that lets you access each object in the set.

- (NSSet) objectsPassingTest(predicate)

Returns a set of object that pass a test in a given Block.

Parameters:

  • predicate —

    The block to apply to elements in the array.The block takes three arguments:objThe element in the set.stopA reference to a Boolean value. The block can set the value to YES to stop further processing of the set. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.The Block returns a Boolean value that indicates whether obj passed the test.

  • obj —

    The element in the set.

  • stop —

    A reference to a Boolean value. The block can set the value to YES to stop further processing of the set. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

Returns:

  • (NSSet) —

    An NSSet containing objects that pass the test.

- (NSSet) objectsWithOptions(opts, passingTest:predicate)

Returns a set of object that pass a test in a given Block, using the specified enumeration options.

Parameters:

  • opts —

    A bitmask that specifies the options for the enumeration.

  • predicate —

    The Block to apply to elements in the set.The Block takes two arguments:objThe element in the set.stopA reference to a Boolean value. The block can set the value to YES to stop further processing of the set. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.The Block returns a Boolean value that indicates whether obj passed the test.

  • obj —

    The element in the set.

  • stop —

    A reference to a Boolean value. The block can set the value to YES to stop further processing of the set. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

Returns:

  • (NSSet) —

    An NSSet containing objects that pass the test.

- (Object) removeObserver(observer, forKeyPath:keyPath)

Raises an exception.

Parameters:

  • observer —

    The object to remove as an observer.

  • keyPath —

    A key-path, relative to the set, for which observer is registered to receive KVO change notifications. This value must not be nil.

  • context —

    Arbitrary data that is passed to observer in observeValueForKeyPath:ofObject:change:context:.

Returns:

- (NSSet) setByAddingObject(anObject)

Returns a new set formed by adding a given object to the receiving set.

Parameters:

  • anObject (Object) —

    The object to add to the set.

Returns:

  • (NSSet) —

    A new set formed by adding anObject to the receiving set.

- (NSSet) setByAddingObjectsFromArray(other)

Returns a new set formed by adding the objects in a given array to the receiving set.

Parameters:

  • other (Array) —

    The array of objects to add to the set.

Returns:

  • (NSSet) —

    A new set formed by adding the objects in other to the receiving set.

- (NSSet) setByAddingObjectsFromSet(other)

Returns a new set formed by adding the objects in a given set to the receiving set.

Parameters:

  • other (NSSet) —

    The set of objects to add to the receiving set.

Returns:

  • (NSSet) —

    A new set formed by adding the objects in other to the receiving set.

- (Object) setValue(value, forKey:key)

Invokes setValue:forKey: on each of the set’s members.

Parameters:

  • value (Object) —

    The value for the property identified by key.

  • key (String) —

    The name of one of the properties of the set’s members.

Returns:

- (Array) sortedArrayUsingDescriptors(sortDescriptors)

Returns an array of the set’s content sorted as specified by a given array of sort descriptors. The first descriptor specifies the primary key path to be used in sorting the set’s contents. Any subsequent descriptors are used to further refine sorting of objects with duplicate values. See NSSortDescriptor for additional information.

Parameters:

Returns:

  • (Array) —

    An NSArray containing the set’s content sorted as specified by sortDescriptors.

- (Object) valueForKey(key)

Return a set containing the results of invoking valueForKey: on each of the receiving set’s members. The returned set might not have the same number of members as the receiving set. The returned set will not contain any elements corresponding to instances of valueForKey: returning nil (note that this is in contrast with NSArray’s implementation, which may put NSNull values in the arrays it returns).

Parameters:

  • key (String) —

    The name of one of the properties of the receiving set’s members.

Returns:

  • (Object) —

    A set containing the results of invoking valueForKey: (with the argument key) on each of the receiving set’s members.