OSArray |
Inherits from: | |
Declared In: |
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.
Creates a deep copy of an array and its child collections.
Ensures the array has enough space to store the requested number of objects.
Removes and releases all objects within the array.
Deallocates or releases any resources used by the OSArray instance.
Returns the number of objects the array can store without reallocating.
Returns the storage increment of the array.
Returns the current number of objects within the array.
Returns the last object in the array.
Scans the array for the next instance of a specific object at or beyond a given index.
Return the object stored at a given index.
Initializes a new OSArray populated with the contents of another array.
Initializes a new instance of OSArray.
Initializes a new OSArray populated with objects provided.
Tests the equality of two OSArray objects.
Tests the equality of an OSArray to an arbitrary object.
Appends the contents of an array onto the receiving array.
Removes an object from the array.
Replaces an object in an array at a given index.
Archives the receiver into the provided OSSerialize object.
Sets the storage increment of the array.
Appends an object onto the end of the array, increasing storage if necessary.
Inserts or appends an object into the array at a particular index.
Recursively sets option bits in an array and all child collections.
Creates and initializes an OSArray populated with the contents of another array.
Creates and initializes an empty OSArray.
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);
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
.
The newly copied array, with a retain count of 1,
or NULL
if there is insufficient memory to do the copy.
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);
newCapacity
The total number of objects the array should be able to store.
The new capacity of the array, which may be different from the number requested (if smaller, reallocation of storage failed).
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();
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.
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;
The number objects the array can store without reallocating.
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;
The storage increment of the array.
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;
The current number of objects within the array.
getLastObject |
Returns the last object in the array.
public
virtual OSObject * getLastObject() const;
The last object in the array,
or NULL
if the array is empty.
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;
anObject
The object to scan for.
index
The index at which to begin the scan.
The next index of anObject
in the array or (-1)
if none is found.
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;
index
The index of the object to be returned to caller.
The object stored at index
,
or NULL
if index
lies past the end of the array.
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);
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
.
true
on success, false
on failure.
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);
capacity
The initial storage capacity of the array object.
true
on success, false
on failure.
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);
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
.
true
on success, false
on failure.
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;
anArray
The array object being compared against the receiver.
true
if the two arrays are equivalent,
false
otherwise.
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;
anObject
The object to be compared against the receiver.
true
if the two objects are equivalent,
false
otherwise.
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);
otherArray
The array whose contents will be appended to the receiving array.
true
if merging was successful, false
otherwise.
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);
index
The index of the object to be removed.
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);
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.
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;
serializer
The OSSerialize object.
true
if serialization succeeds, false
if not.
setCapacityIncrement |
Sets the storage increment of the array.
public
virtual unsigned int setCapacityIncrement( unsigned increment);
The new storage increment of the array, which may be different from the number requested.
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);
anObject
The object to add to the OSArray instance.
true
if the addition of anObject
was successful,
false
if not.
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);
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.
true
if the addition of anObject
was successful, false
if not.
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);
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.
The options bitfield as it was before the set operation.
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.
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
.
An instance of OSArray containing the objects of array
,
with a retain count of 1;
NULL
on failure.
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);
capacity
The initial storage capacity of the array object.
An empty instance of OSArray with a retain count of 1;
NULL
on failure.
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);
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
.
An instance of OSArray containing the objects provided,
with a retain count of 1;
NULL
on failure.
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).
Last Updated: 2010-07-29