OSArray

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

Overview

OSArray provides an indexed store of objects.

OSArray is a container for Libkern C++ objects (those derived from OSMetaClassBase, in particular OSObject). Storage and access are by array index.

You must generally cast retrieved objects from OSObject to the desired class using OSDynamicCast. This macro returns the object cast to the desired class, or NULL if the object isn't derived from that class.

As with all Libkern collection classes, OSArray retains objects added to it, and releases objects removed from it (or replaced). An OSArray 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.

OSArray 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

copyCollection

Creates a deep copy of an array 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 array, with a retain count of 1, or NULL if there is insufficient memory to do the copy.

Discussion

The receiving array, and any collections it contains, recursively, are copied. Objects that are not derived from OSCollection are retained rather than copied.

ensureCapacity

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

virtual unsigned int ensureCapacity( unsigned int newCapacity);
Parameters
newCapacity

The total number of objects the array should be able to store.

Return Value

The new capacity of the array, which may be different from the number requested (if smaller, reallocation of storage failed).

Discussion

This function immediately resizes the array, if necessary, to accommodate at least newCapacity 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 OSArray.

flushCollection

Removes and releases all objects within the array.

virtual void flushCollection();
Discussion

The array's capacity (and therefore direct memory consumption) is not reduced by this function.

free

Deallocates or releases any resources used by the OSArray instance.

virtual void free();
Discussion

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

getCapacity

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

virtual unsigned int getCapacity() const;
Return Value

The number objects the array can store without reallocating.

Discussion

OSArray objects grow when full to accommodate additional objects. See getCapacityIncrement and ensureCapacity.

getCapacityIncrement

Returns the storage increment of the array.

virtual unsigned int getCapacityIncrement() const;
Return Value

The storage increment of the array.

Discussion

An OSArray allocates storage for objects in multiples of the capacity increment.

getCount

Returns the current number of objects within the array.

virtual unsigned int getCount() const;
Return Value

The current number of objects within the array.

getLastObject

Returns the last object in the array.

virtual OSObject * getLastObject() const;
Return Value

The last object in the array, or NULL if the array is empty.

Discussion

The returned object will be released if removed from the array; if you plan to store the reference, you should call retain on that object.

getNextIndexOfObject

Scans the array for the next instance of a specific object at or beyond a given index.

virtual unsigned int getNextIndexOfObject( const OSMetaClassBase *anObject, unsigned int index) const;
Parameters
anObject

The object to scan for.

index

The index at which to begin the scan.

Return Value

The next index of anObject in the array or (-1) if none is found.

Discussion

This function uses pointer equivalence, and does not use isEqualTo.

getObject

Return the object stored at a given index.

virtual OSObject * getObject( unsigned int index) const;
Parameters
index

The index of the object to be returned to caller.

Return Value

The object stored at index, or NULL if index lies past the end of the array.

Discussion

The returned object will be released if removed from the array; if you plan to store the reference, you should call retain on that object.

initWithArray

Initializes a new OSArray populated with the contents of another array.

virtual bool initWithArray( const OSArray *anArray, unsigned int capacity = 0);
Parameters
anArray

The array whose contents will be placed in the new instance.

capacity

The initial storage capacity of the array 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 objects (unlike CFMutableArray, for which the initial capacity is a hard limit).

The objects in array are retained for storage in the new OSArray, not copied.

initWithCapacity

Initializes a new instance of OSArray.

virtual bool initWithCapacity( unsigned int capacity);
Parameters
capacity

The initial storage capacity of the array 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 array will grow as needed to accommodate more objects (unlike CFMutableArray, for which the initial capacity is a hard limit).

initWithObjects

Initializes a new OSArray 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 array.

capacity

The initial storage capacity of the array 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 objects (unlike CFMutableArray, for which the initial capacity is a hard limit).

isEqualTo(const OSArray *)

Tests the equality of two OSArray objects.

virtual bool isEqualTo( const OSArray *anArray) const;
Parameters
anArray

The array object being compared against the receiver.

Return Value

true if the two arrays are equivalent, false otherwise.

Discussion

Two OSArray objects are considered equal if they have same count and if the objects at corresponding indices compare as equal using isEqualTo.

isEqualTo(const OSMetaClassBase *)

Tests the equality of an OSArray to an arbitrary object.

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

The object to be compared against the receiver.

Return Value

true if the two objects are equivalent, false otherwise.

Discussion

An OSArray is considered equal to another object if that object is derived from OSArray and contains the same or equivalent objects.

merge

Appends the contents of an array onto the receiving array.

virtual bool merge( const OSArray *otherArray);
Parameters
otherArray

The array whose contents will be appended to the receiving array.

Return Value

true if merging was successful, false otherwise.

Discussion

This function merely appends one array onto another. Duplicates are not avoided and no sorting is performed. Objects successfully added to the receiver are retained.

removeObject

Removes an object from the array.

virtual void removeObject( unsigned int index);
Parameters
index

The index of the object to be removed.

Discussion

This function moves existing objects to fill the vacated index so that there are no gaps. The object removed is released.

replaceObject

Replaces an object in an array at a given index.

virtual void replaceObject( unsigned int index, const OSMetaClassBase *anObject);
Parameters
index

The index of the object to be replaced. Must be less than the array's count.

anObject

The object to be placed into the array.

Discussion

The original object is released and the new object is retained.

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

virtual unsigned int setCapacityIncrement( unsigned increment);
Return Value

The new storage increment of the array, which may be different from the number requested.

Discussion

An OSArray allocates storage for objects in multiples of the capacity increment. Calling this function does not immediately reallocate storage.

setObject(const OSMetaClassBase *)

Appends an object onto the end of the array, increasing storage if necessary.

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

The object to add to the OSArray instance.

Return Value

true if the addition of anObject was successful, false if not.

Discussion

The array adds storage to accomodate the new object, if necessary. If successfully added, the object is retained.

setObject(unsigned int, const OSMetaClassBase *)

Inserts or appends an object into the array at a particular index.

virtual bool setObject( unsigned int index, const OSMetaClassBase *anObject);
Parameters
index

The index in the array at which to insert the object. Must be less than or equal to the array's count.

anObject

The object to add to the array.

Return Value

true if the addition of anObject was successful, false if not.

Discussion

This function moves existing objects from index on, in order to accommodate the new object; it does not replace an existing object at index. See replaceObject. If successfully added, the object is retained.

The array adds storage to accomodate the new object, if necessary. Note, however, that this function does not allow for arbirtrary growth of an array by specifying an index larger than the current count. If you need to immediately grow an array by an arbitrary amount, use ensureCapacity.

setOptions

Recursively sets option bits in an array 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 array's options actually change.

withArray

Creates and initializes an OSArray populated with the contents of another array.

static OSArray * withArray( const OSArray *array, unsigned int capacity = 0);
Parameters
array

An OSArray whose contents will be stored in the new instance.

capacity

The initial storage capacity of the array 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 OSArray containing the objects of array, with a retain count of 1; NULL on failure.

Discussion

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 objects (unlike CFMutableArray, for which the initial capacity is a hard limit).

The objects in array are retained for storage in the new OSArray, not copied.

withCapacity

Creates and initializes an empty OSArray.

static OSArray * withCapacity( unsigned int capacity);
Parameters
capacity

The initial storage capacity of the array object.

Return Value

An empty instance of OSArray with a retain count of 1; NULL on failure.

Discussion

capacity must be nonzero. The new array will grow as needed to accommodate more objects (unlike CFMutableArray, for which the initial capacity is a hard limit).

withObjects

Creates and initializes an OSArray populated with objects provided.

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

A C array of OSObject-derived instances.

count

The number of objects to be placed into the array.

capacity

The initial storage capacity of the array object. If 0, count is used; otherwise this value must be greater than or equal to count.

Return Value

An instance of OSArray 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 array will grow as needed to accommodate more objects (unlike CFMutableArray, for which the initial capacity is a hard limit).