ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

OSArray

Inherits from:	OSCollection
Declared In:	OSArray.h

Overview

A collection class whose instances maintain a list of object references.

Discussion

An instance of an OSArray is a mutable collection which maintains a list of references to OSMetaClassBase-derived objects. Objects are referenced by index, where the index is an integer with a value of 0 to N-1 where N is the number of objects contained within the array.

Objects placed into an array are automatically retained and objects removed or replaced are automatically released. All objects are released when the array is freed.

Functions

ensureCapacity: Expands the size of the collection to a given storage capacity.
flushCollection: Removes and releases all items within the array (a member function).
free: Deallocates and releases all resources used by the OSArray instance.
getCapacity: Returns the storage capacity of the OSArray object.
getCapacityIncrement: Returns the size by which the array will grow.
getCount: Returns the number of references contained within the OSArray object.
getLastObject: Returns a reference to the last object in the array.
getNextIndexOfObject: Searches the array for the next instance of a specific object, at or beyond the supplied index.
getObject: Returns a reference to an object located within the array at a given index.
initWithArray: Initializes an instance of OSArray and populates it with the contents of the supplied OSArray object.
initWithCapacity: Initializes an instance of OSArray.
initWithObjects: Initializes an instance of OSArray and populates it with the given list of objects.
isEqualTo(const OSArray *): Tests the equality of the values of two OSArray objects.
isEqualTo(const OSMetaClassBase *): Compares the equality of the values of a receiving array 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.
setCapacityIncrement: Sets the growth size of the array.
setObject(const OSMetaClassBase *): Appends an object onto the end of the array.
setObject(unsigned int, const OSMetaClassBase *): Inserts an object into the array at a particular index.
withArray: Creates and initializes an instance of OSArray of a given capacity and populates it with the contents of the supplied OSArray object.
withCapacity: Creates and initializes a new instance of OSArray with a given capacity.
withObjects: Creates and initializes a new instance of OSArray and populates it with a list of objects provided.

ensureCapacity

Expands the size of the collection to a given storage capacity.

public

virtual unsigned int ensureCapacity(
    unsigned int newCapacity);

Parameters

newCapacity: The new capacity for the array.

Return Value

Returns the new capacity of the array or the previous capacity upon error.

flushCollection

Removes and releases all items within the array (a member function).

public

virtual void flushCollection();

free

Deallocates and releases all resources used by the OSArray instance.

public

virtual void free();

Discussion

This function should not be called directly, use release() instead.

getCapacity

Returns the storage capacity of the OSArray object.

public

virtual unsigned int getCapacity() const;

Return Value

Returns the storage capacity of the OSArray object.

getCapacityIncrement

Returns the size by which the array will grow.

public

virtual unsigned int getCapacityIncrement() const;

Return Value

Returns the size by which the array will grow.

getCount

Returns the number of references contained within the OSArray object.

public

virtual unsigned int getCount() const;

Return Value

Returns the number of items within the OSArray object.

getLastObject

Returns a reference to the last object in the array.

public

virtual OSObject *getLastObject() const;

Return Value

Returns a reference to the last object in the array or 0 if the array is empty.

Discussion

Note that the caller should not release the returned object.

getNextIndexOfObject

Searches the array for the next instance of a specific object, at or beyond the supplied index.

public

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

Return Value

Returns the next index of the object in the array or -1 if none is found.

getObject

Returns a reference to an object located within the array at a given index.

public

virtual OSObject *getObject(
    unsigned int index) const;

Parameters

index: The index into the array from which the reference to an object is taken.

Return Value

Returns a reference to an object or 0 if the index is beyond the bounds of the array.

Discussion

Note that the caller should not release the returned object.

initWithArray

Initializes an instance of OSArray and populates it with the contents of the supplied OSArray object.

public

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

Parameters

anArray: An instance of OSArray containing the references to objects which will be copied to the new instances of OSArray.
capacity: The initial capacity of the new instance of OSArray. If 0, the capacity will be set to the number of elements in the array, else the capacity must be greater than or equal to the number of elements in the array.

Return Value

Returns true if initialization succeeded or false if not.

initWithCapacity

Initializes an instance of OSArray.

public

virtual bool initWithCapacity(
    unsigned int capacity);

Parameters

capacity: The initial capacity of the new instance of OSArray.

Return Value

Returns true if initialization succeeded or false if not.

initWithObjects

Initializes an instance of OSArray and populates it with the given list of objects.

public

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

Parameters

objects: A static array containing references to OSMetaClassBase-derived objects.
count: The number of objects to be added to the array.
capacity: The initial capacity of the new instance of OSArray. If 0, the capacity will be set to the same value as the 'count' parameter, else capacity must be greater than or equal to the value of 'count'.

Return Value

Returns true if initialization succeeded or false if not.

isEqualTo(const OSArray *)

Tests the equality of the values of two OSArray objects.

public

virtual bool isEqualTo(
    const OSArray *anArray) const;

Parameters

anArray: The array object being compared against the receiver.

Return Value

Returns true if the two arrays are equivalent or false otherwise.

isEqualTo(const OSMetaClassBase *)

Compares the equality of the values of a receiving array to an arbitrary object.

public

virtual bool isEqualTo(
    const OSMetaClassBase *anObject) const;

Parameters

anObject: The object to be compared against the receiver.

Return Value

Returns true if the two objects are equivalent (that is, they are either the same object or they are both arrays containing the same or equivalent objects) or false otherwise.

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

Returns true when merging was successful, false otherwise.

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 removes an object from the array which is located at a given index. Once removed the contents of the array will shift to fill in the vacated spot. The removed object is automatically 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 into the array at which the new object will be placed.
anObject: The object to be placed into the array.

Discussion

Note that the original object will be released and the new object will be retained.

serialize

Archives the receiver.

public

virtual bool serialize(
    OSSerialize *s) const;

Parameters

s: The OSSerialize object.

Return Value

Returns true if serialization was successful, false if not.

setCapacityIncrement

Sets the growth size of the array.

public

virtual unsigned int setCapacityIncrement(
    unsigned increment);

Return Value

Returns the new growth size.

setObject(const OSMetaClassBase *)

Appends an object onto the end of the array.

public

virtual bool setObject(
    const OSMetaClassBase *anObject);

Parameters

anObject: The object to add to the OSArray instance. The object will be retained automatically.

Return Value

Returns true if the addition of 'anObject' was successful, false if not; failure usually results from failing to allocate the necessary memory.

setObject(unsigned int, const OSMetaClassBase *)

Inserts an object into the array at a particular index.

public

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

Parameters

index: The index into the array to insert the object.
anObject: The object to add to the OSArray instance. The object will be retained automatically.

Return Value

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

withArray

Creates and initializes an instance of OSArray of a given capacity and populates it with the contents of the supplied OSArray object.

public

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

Parameters

array: An instance of OSArray from which the new instance will aquire its contents.
capacity: The capacity of the new OSArray. If 0, the capacity will be set to the number of elements in the array, else the capacity must be greater than or equal to the number of elements in the array.

Return Value

Returns a reference to a new instance of OSArray or 0 if an error occurred.

withCapacity

Creates and initializes a new instance of OSArray with a given capacity.

public

static OSArray *withCapacity(
    unsigned int capacity);

Parameters

capacity: The initial capacity (number of references) of the OSArray instance.

Return Value

Returns a reference to an instance of OSArray or 0 if an error occurred.

withObjects

Creates and initializes a new instance of OSArray and populates it with a list of objects provided.

public

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

Parameters

objects: A static array of references to OSMetaClassBase-derived objects.
count: The number of objects provided.
capacity: The initial storage size of the OSArray instance. If 0, the capacity will be set to the size of count, else the capacity must be greater than or equal to count.

Return Value

Returns a reference to a new instance of OSArray or 0 if an error occurred.

Member Data

reserved

protected

ExpansionData *reserved;

Discussion

Reserved for future use. (Internal use only)

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-12-19