OSSet
Overview
OSSet provides an unordered set store of objects.
OSSet is a container for Libkern C++ objects (those derived from OSMetaClassBase, in particular OSObject). Storage and access follow basic set logic: you can add or remove an object, and test whether the set contains a particular object. A given object is only stored in the set once, and there is no ordering of objects in the set. A subclass OSOrderedSet, provides for ordered set logic.
As with all Libkern collection classes, OSSet retains objects added to it, and releases objects removed from it. An OSSet also grows as necessary to accommodate new objects, unlike Core Foundation collections (it does not, however, shrink).
Use Restrictions
With very few exceptions in the I/O Kit, all Libkernbased C++ classes, functions, and macros are unsafe to use in a primary interrupt context. Consult the I/O Kit documentation related to primary interrupts for more information.
OSSet provides no concurrency protection; it's up to the usage context to provide any protection necessary. Some portions of the I/O Kit, such as IORegistryEntry, handle synchronization via defined member functions for setting properties.
Tasks
Miscellaneous

containsObject

copyCollection

ensureCapacity

flushCollection

free

getAnyObject

getCapacity

getCapacityIncrement

getCount

initWithArray

initWithCapacity

initWithObjects

initWithSet

isEqualTo(const OSMetaClassBase *)

isEqualTo(const OSSet *)

member

merge(const OSArray *)

merge(const OSSet *)

removeObject

serialize

setCapacityIncrement

setObject

setOptions

withArray

withCapacity

withObjects

withSet
Instance Methods
containsObject
Checks the set for the presence of an object.
Parameters
 anObject
The OSMetaClassBasederived object to check for in the set.
Return Value
true
if anObject
is present within the set, false
otherwise.
Discussion
Pointer equality is used. This function returns false
if passed NULL
.
copyCollection
Creates a deep copy of this set and its child collections.
Parameters
 cycleDict
A dictionary of all of the collections that have been copied so far, which is used to track circular references. To start the copy at the top level, pass
NULL
.
Return Value
The newly copied set, with a retain count of 1, or NULL
if there is insufficient memory to do the copy.
Discussion
The receiving set, and any collections it contains, recursively, are copied. Objects that are not derived from OSCollection are retained rather than copied.
ensureCapacity
Ensures the set has enough space to store the requested number of distinct objects.
Parameters
 newCapacity
The total number of distinct objects the set should be able to store.
Return Value
The new capacity of the set, which may be different from the number requested (if smaller, reallocation of storage failed).
Discussion
This function immediately resizes the set, if necessary, to accommodate at least newCapacity
distinct objects. If newCapacity
is not greater than the current capacity, or if an allocation error occurs, the original capacity is returned.
There is no way to reduce the capacity of an OSSet.
flushCollection
Removes and releases all objects within the set.
Discussion
The set's capacity (and therefore direct memory consumption) is not reduced by this function.
free
Deallocates or releases any resources used by the OSSet instance.
Discussion
This function should not be called directly; use release
instead.
getAnyObject
Returns an arbitrary (not random) object from the set.
Return Value
An arbitrary (not random) object if one exists within the set.
Discussion
The returned object will be released if removed from the set; if you plan to store the reference, you should call retain
on that object.
getCapacity
Returns the number of objects the set can store without reallocating.
Return Value
The number objects the set can store without reallocating.
Discussion
OSSet objects grow when full to accommodate additional objects. See getCapacityIncrement
and ensureCapacity
.
getCapacityIncrement
Returns the storage increment of the set.
Return Value
The storage increment of the set.
Discussion
An OSSet allocates storage for objects in multiples of the capacity increment.
getCount
Returns the current number of objects within the set.
Return Value
The current number of objects within the set.
initWithArray
Initializes a new OSSet populated with the contents of an OSArray.
Parameters
 array
An OSAray whose contents will be placed in the new instance.
 capacity
The initial storage capacity of the new set object. If 0, the capacity is set to the number of objects in
array
; otherwisecapacity
must be greater than or equal to the number of objects inarray
.
Return Value
true
on success, false
on failure.
Discussion
Not for general use. Use the static instance creation method withArray
instead.
array
must be nonNULL
. If capacity
is nonzero, it must be greater than or equal to count
. The new array will grow as needed to accommodate more keyobject pairs (unlike CFMutableSet, for which the initial capacity is a hard limit).
The objects in array
are retained for storage in the new set, not copied.
initWithCapacity
Initializes a new instance of OSSet.
Parameters
 capacity
The initial storage capacity of the new set object.
Return Value
true
on success, false
on failure.
Discussion
Not for general use. Use the static instance creation method withCapacity
instead.
capacity
must be nonzero. The new set will grow as needed to accommodate more key/object pairs (unlike CFMutableSet, for which the initial capacity is a hard limit).
initWithObjects
Initializes a new OSSet populated with objects provided.
Parameters
 objects
A C array of OSObjectderived objects.
 count
The number of objects to be placed into the set.
 capacity
The initial storage capacity of the new set object. If 0,
count
is used; otherwise this value must be greater than or equal tocount
.
Return Value
true
on success, false
on failure.
Discussion
Not for general use. Use the static instance creation method withObjects
instead.
objects
must be nonNULL
, and count
must be nonzero. If capacity
is nonzero, it must be greater than or equal to count
. The new array will grow as needed to accommodate more keyobject pairs (unlike CFMutableSet, for which the initial capacity is a hard limit).
The objects in objects
are retained for storage in the new set, not copied.
initWithSet
Initializes a new OSSet populated with the contents of another OSSet.
Parameters
 set
A set whose contents will be placed in the new instance.
 capacity
The initial storage capacity of the new set object. If 0, the capacity is set to the number of objects in
set
; otherwisecapacity
must be greater than or equal to the number of objects inset
.
Return Value
true
on success, false
on failure.
Discussion
Not for general use. Use the static instance creation method withSet
instead.
set
must be nonNULL
. If capacity
is nonzero, it must be greater than or equal to count
. The new set will grow as needed to accommodate more keyobject pairs (unlike CFMutableSet, for which the initial capacity is a hard limit).
The objects in set
are retained for storage in the new set, not copied.
isEqualTo(const OSMetaClassBase *)
Tests the equality of an OSSet against an arbitrary object.
Parameters
 anObject
The object being compared against the receiver.
Return Value
true
if the two objects are equivalent, false
otherwise.
Discussion
An OSSet object is considered equal to another object if the other object is derived from OSSet and compares equal as a set.
isEqualTo(const OSSet *)
Tests the equality of two OSSet objects.
Parameters
 aSet
The set object being compared against the receiver.
Return Value
true
if the two sets are equivalent, false
otherwise.
Discussion
Two OSSet objects are considered equal if they have same count and the same object pointer values.
member
Checks the set for the presence of an object.
Parameters
 anObject
The OSMetaClassBasederived object to check for in the set.
Return Value
true
if anObject
is present within the set, false
otherwise.
Discussion
Pointer equality is used. This function returns false
if passed NULL
.
containsObject
checks for NULL
first, and is therefore more efficient than this function.
merge(const OSArray *)
Adds the contents of an OSArray to the set.
Parameters
 array
The OSArray object containing the objects to be added.
Return Value
true
if all objects from array
are successfully added the receiver (or were already present), false
otherwise.
Discussion
This functions adds to the receiving set all objects from array
that are not already in the receiving set. Objects added to the receiver are retained.
In releases prior to 10.7, this function would return false
if an object from array
was already present in the set, or if array
was empty. This is no longer the case, so this function correctly returns true
when the semantic of merging is met.
merge(const OSSet *)
Adds the contents of an OSet to the set.
Parameters
 set
The OSSet object containing the objects to be added.
Return Value
true
if any object from set
are successfully added the receiver (or were already present), false
otherwise.
Discussion
This functions adds to the receiving set all objects from set
that are not already in the receiving set. Objects added to the receiver are retained.
In releases prior to 10.7, this function would return false
if an object from set
was already present in the set, or if set
was empty. This is no longer the case, so this function correctly returns true
when the semantic of merging is met.
removeObject
Removes an object from the set.
Parameters
 anObject
The OSMetaClassBasederived object to be removed from the set.
Discussion
The object removed from the set is released.
serialize
Archives the receiver into the provided OSSerialize object.
Parameters
 serializer
The OSSerialize object.
Return Value
true
if serialization succeeds, false
if not.
setCapacityIncrement
Sets the storage increment of the set.
Return Value
The new storage increment of the set, which may be different from the number requested.
Discussion
An OSSet allocates storage for objects in multiples of the capacity increment. Calling this function does not immediately reallocate storage.
setObject
Adds an object to the OSSet if it is not already present.
Parameters
 anObject
The OSMetaClassBasederived object to be added to the set.
Return Value
true
if anObject
was successfully added to the set, false
otherwise (including if it was already in the set).
Discussion
The set adds storage to accomodate the new object, if necessary. If successfully added, the object is retained.
A false
return value can mean either that anObject
is already present in the set, or that a memory allocation failure occurred. If you need to know whether the object is already present, use containsObject
.
setOptions
Recursively sets option bits in the set and all child collections.
Parameters
 options
A bitfield whose values turn the options on (1) or off (0).
 mask
A mask indicating which bits in
options
to change. Pass 0 to get the whole current options bitfield without changing any settings. context
Unused.
Return Value
The options bitfield as it was before the set operation.
Discussion
Kernel extensions should not call this function.
Child collections' options are changed only if the receiving set's options actually change.
withArray
Creates and initializes an OSSet populated with the contents of an OSArray.
Parameters
 array
An array whose objects will be stored in the new OSSet.
 capacity
The initial storage capacity of the new set object. If 0, the capacity is set to the number of objects in
array
; otherwisecapacity
must be greater than or equal to the number of objects inarray
.
Return Value
An instance of OSSet containing the objects of array
, with a retain count of 1; NULL
on failure.
Discussion
Each distinct object in array
is added to the new set.
array
must be nonNULL
. If capacity
is nonzero, it must be greater than or equal to count
. The new OSSet will grow as needed to accommodate more keyobject pairs (unlike CFMutableSet, for which the initial capacity is a hard limit).
The objects in array
are retained for storage in the new set, not copied.
withCapacity
Creates and initializes an empty OSSet.
Parameters
 capacity
The initial storage capacity of the new set object.
Return Value
An empty instance of OSSet with a retain count of 1; NULL
on failure.
Discussion
capacity
must be nonzero. The new OSSet will grow as needed to accommodate more key/object pairs (unlike CFMutableSet, for which the initial capacity is a hard limit).
withObjects
Creates and initializes an OSSet populated with objects provided.
Parameters
 objects
A C array of OSMetaClassBasederived objects.
 count
The number of objects to be placed into the set.
 capacity
The initial storage capacity of the new set object. If 0,
count
is used; otherwise this value must be greater than or equal tocount
.
Return Value
An instance of OSSet containing the objects provided, with a retain count of 1; NULL
on failure.
Discussion
objects
must be nonNULL
, and count
must be nonzero. If capacity
is nonzero, it must be greater than or equal to count
. The new OSSet will grow as needed to accommodate more objects (unlike CFMutableSet, for which the initial capacity is a hard limit).
The objects in objects
are retained for storage in the new set, not copied.
withSet
Creates and initializes an OSSet populated with the contents of another OSSet.
Parameters
 set
An OSSet whose contents will be stored in the new instance.
 capacity
The initial storage capacity of the set object. If 0, the capacity is set to the number of objects in
set
; otherwisecapacity
must be greater than or equal to the number of objects inarray
.
Return Value
An instance of OSArray containing the objects of set
, with a retain count of 1; NULL
on failure.
Discussion
set
must be nonNULL
. If capacity
is nonzero, it must be greater than or equal to count
. The array will grow as needed to accommodate more keyobject pairs (unlike CFMutableSet, for which the initial capacity is a hard limit).
The objects in set
are retained for storage in the new set, not copied.
Copyright © 2013 Apple Inc. All Rights Reserved. Terms of Use  Privacy Policy  Updated: 20131022