OSSet

Inherits from
OSCollection
Availability
Available in OS X v10.0 and later.
Declared in
OSSet.h

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 Libkern-based 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

Instance Methods

containsObject

Checks the set for the presence of an object.

virtual bool containsObject( const OSMetaClassBase *anObject) const;
Parameters
anObject

The OSMetaClassBase-derived 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.

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.

ensureCapacity

Ensures the set has enough space to store the requested number of distinct objects.

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

virtual void flushCollection();
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.

virtual void free();
Discussion

This function should not be called directly; use release instead.

getAnyObject

Returns an arbitrary (not random) object from the set.

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.

getCapacity

Returns the number of objects the set can store without reallocating.

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 and ensureCapacity.

getCapacityIncrement

Returns the storage increment of the set.

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.

getCount

Returns the current number of objects within the set.

virtual unsigned int getCount() const;
Return Value

The current number of objects within the set.

initWithArray

Initializes a new OSSet populated with the contents of an OSArray.

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; otherwise capacity must be greater than or equal to the number of objects in array.

Return Value

true on success, false on failure.

Discussion

Not for general use. Use the static instance creation method withArray instead.

array must be non-NULL. If capacity is nonzero, it must be greater than or equal to count. The new array will grow as needed to accommodate more key-object 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.

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

initWithObjects

Initializes a new OSSet populated with objects provided.

virtual bool initWithObjects( const OSObject *objects[], unsigned int count, unsigned int capacity = 0);
Parameters
objects

A C array of OSObject-derived 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 to count.

Return Value

true on success, false on failure.

Discussion

Not for general use. Use the static instance creation method withObjects instead.

objects must be non-NULL, 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 key-object 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.

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; otherwise capacity must be greater than or equal to the number of objects in set.

Return Value

true on success, false on failure.

Discussion

Not for general use. Use the static instance creation method withSet instead.

set must be non-NULL. If capacity is nonzero, it must be greater than or equal to count. The new set will grow as needed to accommodate more key-object 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.

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.

isEqualTo(const OSSet *)

Tests the equality of two OSSet objects.

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.

member

Checks the set for the presence of an object.

virtual bool member( const OSMetaClassBase *anObject) const;
Parameters
anObject

The OSMetaClassBase-derived 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.

virtual bool merge( const OSArray *array);
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.

virtual bool merge( const OSSet *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.

virtual void removeObject( const OSMetaClassBase *anObject);
Parameters
anObject

The OSMetaClassBase-derived 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.

virtual bool serialize( OSSerialize *serializer) const;
Parameters
serializer

The OSSerialize object.

Return Value

true if serialization succeeds, false if not.

setCapacityIncrement

Sets the storage increment of the set.

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.

setObject

Adds an object to the OSSet if it is not already present.

virtual bool setObject( const OSMetaClassBase *anObject);
Parameters
anObject

The OSMetaClassBase-derived 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.

virtual unsigned setOptions( unsigned options, unsigned mask, 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.

withArray

Creates and initializes an OSSet populated with the contents of an OSArray.

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; otherwise capacity must be greater than or equal to the number of objects in array.

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 non-NULL. If capacity is nonzero, it must be greater than or equal to count. The new OSSet will grow as needed to accommodate more key-object 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.

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

withObjects

Creates and initializes an OSSet populated with objects provided.

static OSSet * withObjects( const OSObject *objects[], unsigned int count, unsigned int capacity = 0);
Parameters
objects

A C array of OSMetaClassBase-derived 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 to count.

Return Value

An instance of OSSet containing the objects provided, with a retain count of 1; NULL on failure.

Discussion

objects must be non-NULL, 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.

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; otherwise capacity must be greater than or equal to the number of objects in array.

Return Value

An instance of OSArray containing the objects of set, with a retain count of 1; NULL on failure.

Discussion

set must be non-NULL. If capacity is nonzero, it must be greater than or equal to count. The array will grow as needed to accommodate more key-object 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.