NSMutableOrderedSet Class Reference

Inherits from
NSOrderedSet : NSObject
Conforms to
NSCopying (NSOrderedSet)
NSMutableCopying (NSOrderedSet)
NSFastEnumeration (NSOrderedSet)
NSSecureCoding (NSOrderedSet)
NSObject (NSObject)
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.7 and later.
Declared in
NSOrderedSet.h

Overview

NSMutableOrderedSet class declares the programmatic interface to a mutable, ordered collection of distinct objects.

NSMutableOrderedSet objects are not like C arrays. That is, even though you may specify a size when you create a mutable ordered set, the specified size is regarded as a “hint”; the actual size of the set is still 0. This means that you cannot insert an object at an index greater than the current count of an set. For example, if a set contains two objects, its size is 2, so you can add objects at indices 0, 1, or 2. Index 3 is illegal and out of bounds; if you try to add an object at index 3 (when the size of the array is 2), NSMutableOrderedSet raises an exception.

Tasks

Creating a Mutable Ordered Set

Adding, Removing, and Reordering Entries

Sorting Entries

Combining and Recombining Entries

Class Methods

orderedSetWithCapacity:

Creates and returns an mutable ordered set with a given initial capacity.

+ (id)orderedSetWithCapacity:(NSUInteger)numItems
Parameters
numItems

The initial capacity of the new ordered set.

Return Value

A mutable ordered set with initial capacity to hold numItems members.

Discussion

Mutable ordered sets allocate additional memory as needed, so numItems simply establishes the set’s initial capacity.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

Instance Methods

addObject:

Appends a given object to the mutable ordered set, if it is not already a member.

- (void)addObject:(id)object
Parameters
object

The object to add to the set.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

addObjects:count:

Appends the given number of objects from a given C array.

- (void)addObjects:(const id[])objects count:(NSUInteger)count
Parameters
objects

A C array of objects.

count

The number of values from the objects C array to append to the mutable ordered set. This number will be the count of the new array—it must not be negative or greater than the number of elements in objects.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

addObjectsFromArray:

Appends to the mutable ordered set each object contained in a given array that is not already a member.

- (void)addObjectsFromArray:(NSArray *)array
Parameters
array

An array of objects to add to the set.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

exchangeObjectAtIndex:withObjectAtIndex:

Exchanges the object at the specified index with the object at the other index.

- (void)exchangeObjectAtIndex:(NSUInteger)idx1 withObjectAtIndex:(NSUInteger)idx2
Parameters
idx1

The index of the first object.

Important: Raises an NSRangeException if index is beyond the end of the mutable ordered set.

idx2

The index of the second object.

Important: Raises an NSRangeException if index is beyond the end of the mutable ordered set.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

initWithCapacity:

Returns an initialized mutable ordered set with a given initial capacity.

- (id)initWithCapacity:(NSUInteger)numItems
Parameters
numItems

The initial capacity of the new ordered set.

Return Value

An initialized mutable ordered set with initial capacity to hold numItems members.

Discussion

Mutable ordered sets allocate additional memory as needed, so numItems simply establishes the set’s initial capacity.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

insertObject:atIndex:

Inserts the given object at the specified index of the mutable ordered set.

- (void)insertObject:(id)object atIndex:(NSUInteger)idx
Parameters
object

The object to insert into to the set’s content. This value must not be nil.

Important: Important: Raises an NSInvalidArgumentException if object is nil.

idx

The index in the mutable ordered set at which to insert object. This value must not be greater than the count of elements in the array.

Important: Important: Raises an NSRangeException if idx is greater than the number of elements in the mutable ordered set.

Discussion

If the index is already occupied, the objects at index and beyond are shifted by adding 1 to their indices to make room.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

insertObjects:atIndexes:

Inserts the objects in the array at the specified indexes.

- (void)insertObjects:(NSArray *)objects atIndexes:(NSIndexSet *)indexes
Parameters
objects

An array of objects to insert into the mutable ordered set.

indexes

The indexes at which the objects in objects should be inserted. The count of locations in indexes must equal the count of objects.

Discussion

Each object in objects is inserted into the receiving mutable ordered set in turn at the corresponding location specified in indexes after earlier insertions have been made.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

intersectOrderedSet:

Removes from the receiving ordered set each object that isn’t a member of another ordered set.

- (void)intersectOrderedSet:(NSOrderedSet *)other
Parameters
other

The ordered set with which to perform the intersection.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

intersectSet:

Removes from the receiving ordered set each object that isn’t a member of another set.

- (void)intersectSet:(NSSet *)other
Parameters
other

The set with which to perform the intersection.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

minusOrderedSet:

Removes each object in another given ordered set from the receiving mutable ordered set, if present.

- (void)minusOrderedSet:(NSOrderedSet *)other
Parameters
other

The ordered set of objects to remove from the receiving set.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

minusSet:

Removes each object in another given set from the receiving mutable ordered set, if present.

- (void)minusSet:(NSSet *)other
Parameters
other

The set of objects to remove from the receiving set.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

moveObjectsAtIndexes:toIndex:

Moves the object at the specified indexes to the new location.

- (void)moveObjectsAtIndexes:(NSIndexSet *)indexes toIndex:(NSUInteger)idx
Parameters
indexes

The indexes of the objects to move.

idx

The index in the mutable ordered array at which to insert the objects.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

removeAllObjects

Removes all the objects from the mutable ordered set.

- (void)removeAllObjects
Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

removeObject:

Removes a given object from the mutable ordered set.

- (void)removeObject:(id)object
Parameters
object

The object to remove from the mutable ordered set.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

removeObjectAtIndex:

Removes a the object at the specified index from the mutable ordered set.

- (void)removeObjectAtIndex:(NSUInteger)idx
Parameters
idx

The index of the object to remove from the mutable ordered set. The value must not exceed the bounds of the set.

Important: Raises an NSRangeException if index is beyond the end of the mutable ordered set.

Discussion

To fill the gap, all elements beyond index are moved by subtracting 1 from their index.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

removeObjectsAtIndexes:

Removes the objects at the specified indexes from the mutable ordered set.

- (void)removeObjectsAtIndexes:(NSIndexSet *)indexes
Parameters
indexes

The indexes of the objects to remove from the mutable ordered set. The locations specified by indexes must lie within the bounds of the mutable ordered .

Discussion

This method is similar to removeObjectAtIndex:, but allows you to efficiently remove multiple objects with a single operation.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

removeObjectsInArray:

Removes the objects in the array from the mutable ordered set.

- (void)removeObjectsInArray:(NSArray *)array
Parameters
array

An array containing the objects to be removed from the receiving mutable ordered set.

Discussion

This method is similar to removeObject:, but allows you to efficiently remove large sets of objects with a single operation. If the receiving mutable ordered set does not contain objects in array, the method has no effect (although it does incur the overhead of searching the contents).

This method assumes that all elements in array respond to hash and isEqual:.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

removeObjectsInRange:

Removes from the mutable ordered set each of the objects within a given range.

- (void)removeObjectsInRange:(NSRange)range
Parameters
range

The range of the objects to remove from the mutable ordered set.

Discussion

The objects are removed using removeObjectAtIndex:.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

replaceObjectAtIndex:withObject:

Replaces the object at the specified index with the new object.

- (void)replaceObjectAtIndex:(NSUInteger)idx withObject:(id)object
Parameters
idx

The index of the object to be replaced. This value must not exceed the bounds of the mutable ordered set.

Important: Raises an NSRangeException if index is beyond the end of the mutable ordered set.

object

The object with which to replace the object at the index in the ordered set specified by idx. This value must not be nil.

Important: Raises an NSInvalidArgumentException if object is nil.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

replaceObjectsAtIndexes:withObjects:

Replaces the objects at the specified indexes with the new objects.

- (void)replaceObjectsAtIndexes:(NSIndexSet *)indexes withObjects:(NSArray *)objects
Parameters
indexes

The indexes of the objects to be replaced.

objects

The objects with which to replace the objects in the receiving mutable ordered set at the indexes specified by indexes.

The count of locations in indexes must equal the count of objects.

Discussion

The indexes in indexes are used in the same order as the objects in objects.

If objects or indexes is nil, this method raises an exception.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

replaceObjectsInRange:withObjects:count:

Replaces the objects in the receiving mutable ordered set at the range with the specified number of objects from a given C array.

- (void)replaceObjectsInRange:(NSRange)range withObjects:(const id[])objects count:(NSUInteger)count
Parameters
range

The range of the objects to replace.

objects

A C array of objects.

count

The number of values from the objects C array to insert in place of the objects in range. This number will be the count of the new array—it must not be negative or greater than the number of elements in objects.

Discussion

Elements are added to the new array in the same order they appear in objects, up to but not including index count.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

setObject:atIndex:

Appends or replaces the object at the specified index.

- (void)setObject:(id)obj atIndex:(NSUInteger)idx
Parameters
obj

The object to insert or append.

idx

The index. If the index is equal to the length of the collection, then it inserts the object at that index, otherwise it replaces the object at that index with the given object.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSOrderedSet.h

setObject:atIndexedSubscript:

Inserts the given object at the specified index of the mutable ordered set.

- (void)setObject:(id)obj atIndexedSubscript:(NSUInteger)idx
Parameters
object

The object to insert into to the set’s content. This value must not be nil.

Important: Important: Raises an NSInvalidArgumentException if object is nil.

idx

The index in the mutable ordered set at which to insert object. This value must not be greater than the count of elements in the array.

Important: Important: Raises an NSRangeException if idx is greater than the number of elements in the mutable ordered set.

Discussion

If the index is already occupied, the objects at index and beyond are shifted by adding 1 to their indices to make room.

This method is identical to insertObject:atIndex:.

Availability
  • Available in OS X v10.8 and later.
See Also
Declared In
NSOrderedSet.h

sortRange:options:usingComparator:

Sorts the specified range of the mutable ordered set using the specified options and the comparison method specified by a given comparator block.

- (void)sortRange:(NSRange)range options:(NSSortOptions)opts usingComparator:(NSComparator)cmptr
Parameters
range

The range to sort.

opts

A bitmask that specifies the options for the sort (whether it should be performed concurrently and whether it should be performed stably).

cmptr

A comparator block.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

sortUsingComparator:

Sorts the mutable ordered set using the comparison method specified by the comparator block.

- (void)sortUsingComparator:(NSComparator)cmptr
Parameters
cmptr

A comparator block.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

sortWithOptions:usingComparator:

Sorts the mutable ordered set using the specified options and the comparison method specified by a given comparator block.

- (void)sortWithOptions:(NSSortOptions)opts usingComparator:(NSComparator)cmptr
Parameters
opts

A bitmask that specifies the options for the sort (whether it should be performed concurrently and whether it should be performed stably).

cmptr

A comparator block.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

unionOrderedSet:

Adds each object in another given ordered set to the receiving mutable ordered set, if not present.

- (void)unionOrderedSet:(NSOrderedSet *)other
Parameters
other

The set of objects to add to the receiving mutable ordered set.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h

unionSet:

Adds each object in another given set to the receiving mutable ordered set, if not present.

- (void)unionSet:(NSSet *)other
Parameters
other

The set of objects to add to the receiving mutable ordered set.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSOrderedSet.h


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)

Did this document help you? Yes It's good, but... Not helpful...