Mac OS X Reference Library Apple Developer
Search

OSArray

Inherits from:
Declared In:

Overview

OSArray provides an indexed store of objects.

Discussion

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.



Functions

copyCollection

Creates a deep copy of an array and its child collections.

ensureCapacity

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

flushCollection

Removes and releases all objects within the array.

free

Deallocates or releases any resources used by the OSArray instance.

getCapacity

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

getCapacityIncrement

Returns the storage increment of the array.

getCount

Returns the current number of objects within the array.

getLastObject

Returns the last object in the array.

getNextIndexOfObject

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

getObject

Return the object stored at a given index.

initWithArray

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

initWithCapacity

Initializes a new instance of OSArray.

initWithObjects

Initializes a new OSArray populated with objects provided.

isEqualTo(const OSArray *)

Tests the equality of two OSArray objects.

isEqualTo(const OSMetaClassBase *)

Tests the equality of an OSArray to an arbitrary object.

merge

Appends the contents of an array onto the receiving array.

removeObject

Removes an object from the array.

replaceObject

Replaces an object in an array at a given index.

serialize

Archives the receiver into the provided OSSerialize object.

setCapacityIncrement

Sets the storage increment of the array.

setObject(const OSMetaClassBase *)

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

setObject(unsigned int, const OSMetaClassBase *)

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

setOptions

Recursively sets option bits in an array and all child collections.

withArray

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

withCapacity

Creates and initializes an empty OSArray.

withObjects

Creates and initializes an OSArray populated with objects provided.


copyCollection


Creates a deep copy of an array and its child collections.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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.

public

virtual unsigned int getCount() const;
Return Value

The current number of objects within the array.


getLastObject


Returns the last object in the array.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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.

public

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

 

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

Last Updated: 2010-07-29