OSSet
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.

Checks the set for the presence of an object.
Declaration
virtual bool containsObject( const OSMetaClassBase *
anObject
) const;Parameters
anObject
The OSMetaClassBasederived object to check for in the set.
Return Value
true
ifanObject
is present within the set,false
otherwise.Discussion
Pointer equality is used. This function returns
false
if passedNULL
. 
Creates a deep copy of this set and its child collections.
Declaration
OSCollection *copyCollection( OSDictionary *cycleDict = 0);
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.

Ensures the set has enough space to store the requested number of distinct objects.
Declaration
virtual unsigned int ensureCapacity( unsigned int
newCapacity
);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. IfnewCapacity
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.

Removes and releases all objects within the set.
Declaration
virtual void flushCollection();
Discussion
The set's capacity (and therefore direct memory consumption) is not reduced by this function.

Deallocates or releases any resources used by the OSSet instance.
Declaration
virtual void free();
Discussion
This function should not be called directly; use
release
instead. 
Returns an arbitrary (not random) object from the set.
Declaration
virtual OSObject * getAnyObject() const;
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. 
Returns the number of objects the set can store without reallocating.
Declaration
virtual unsigned int getCapacity() const;
Return Value
The number objects the set can store without reallocating.
Discussion
OSSet objects grow when full to accommodate additional objects. See
getCapacityIncrement
andensureCapacity
. 
Returns the storage increment of the set.
Declaration
virtual unsigned int getCapacityIncrement() const;
Return Value
The storage increment of the set.
Discussion
An OSSet allocates storage for objects in multiples of the capacity increment.

Returns the current number of objects within the set.
Declaration
virtual unsigned int getCount() const;
Return Value
The current number of objects within the set.

Initializes a new OSSet populated with the contents of an OSArray.
Declaration
virtual bool initWithArray( const OSArray *
array
, unsigned int capacity = 0);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
. Ifcapacity
is nonzero, it must be greater than or equal tocount
. 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. 
Initializes a new instance of OSSet.
Declaration
virtual bool initWithCapacity( unsigned int
capacity
);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). 
Initializes a new OSSet populated with objects provided.
Declaration
virtual bool initWithObjects( const OSObject *objects[], unsigned int
count
, unsigned int capacity = 0);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
, andcount
must be nonzero. Ifcapacity
is nonzero, it must be greater than or equal tocount
. 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. 
Initializes a new OSSet populated with the contents of another OSSet.
Declaration
virtual bool initWithSet( const OSSet *
set
, unsigned int capacity = 0);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
. Ifcapacity
is nonzero, it must be greater than or equal tocount
. 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. 
Tests the equality of an OSSet against an arbitrary object.
Declaration
virtual bool isEqualTo( const OSMetaClassBase *
anObject
) const;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.

Tests the equality of two OSSet objects.
Declaration
virtual bool isEqualTo( const OSSet *
aSet
) const;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.

Checks the set for the presence of an object.
Declaration
virtual bool member( const OSMetaClassBase *
anObject
) const;Parameters
anObject
The OSMetaClassBasederived object to check for in the set.
Return Value
true
ifanObject
is present within the set,false
otherwise.Discussion
Pointer equality is used. This function returns
false
if passedNULL
.containsObject
checks forNULL
first, and is therefore more efficient than this function. 
Adds the contents of an OSArray to the set.
Declaration
virtual bool merge( const OSArray *
array
);Parameters
array
The OSArray object containing the objects to be added.
Return Value
true
if all objects fromarray
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 fromarray
was already present in the set, or ifarray
was empty. This is no longer the case, so this function correctly returnstrue
when the semantic of merging is met. 
Adds the contents of an OSet to the set.
Declaration
virtual bool merge( const OSSet *
set
);Parameters
set
The OSSet object containing the objects to be added.
Return Value
true
if any object fromset
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 fromset
was already present in the set, or ifset
was empty. This is no longer the case, so this function correctly returnstrue
when the semantic of merging is met. 
Removes an object from the set.
Declaration
virtual void removeObject( const OSMetaClassBase *
anObject
);Parameters
anObject
The OSMetaClassBasederived object to be removed from the set.
Discussion
The object removed from the set is released.

Archives the receiver into the provided OSSerialize object.
Declaration
virtual bool serialize( OSSerialize *
serializer
) const;Parameters
serializer
The OSSerialize object.
Return Value
true
if serialization succeeds,false
if not. 
Sets the storage increment of the set.
Declaration
virtual unsigned int setCapacityIncrement( unsigned
increment
);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.

Adds an object to the OSSet if it is not already present.
Declaration
virtual bool setObject( const OSMetaClassBase *
anObject
);Parameters
anObject
The OSMetaClassBasederived object to be added to the set.
Return Value
true
ifanObject
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 thatanObject
is already present in the set, or that a memory allocation failure occurred. If you need to know whether the object is already present, usecontainsObject
. 
Recursively sets option bits in the set and all child collections.
Declaration
virtual unsigned setOptions( unsigned
options
, unsignedmask
, void *context = 0);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.

Creates and initializes an OSSet populated with the contents of an OSArray.
Declaration
static OSSet * withArray( const OSArray *
array
, unsigned int capacity = 0);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
. Ifcapacity
is nonzero, it must be greater than or equal tocount
. 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. 
Creates and initializes an empty OSSet.
Declaration
static OSSet * withCapacity( unsigned int
capacity
);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). 
Creates and initializes an OSSet populated with objects provided.
Declaration
static OSSet * withObjects( const OSObject *objects[], unsigned int
count
, unsigned int capacity = 0);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
, andcount
must be nonzero. Ifcapacity
is nonzero, it must be greater than or equal tocount
. 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. 
Creates and initializes an OSSet populated with the contents of another OSSet.
Declaration
static OSSet * withSet( const OSSet *
set
, unsigned int capacity = 0);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
. Ifcapacity
is nonzero, it must be greater than or equal tocount
. 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 © 2015 Apple Inc. All rights reserved. Terms of Use  Privacy Policy  Updated: 20131022