OSArray



Member Functions

ensureCapacity

Abstract: A member function which will expand the size of the collection to a given storage capacity.
public:

virtual unsigned int ensureCapacity(unsigned int newCapacity);

Parameters

NameDescription
newCapacityThe new capacity for the array.
Result: Returns the new capacity of the array or the previous capacity upon error.

flushCollection

Abstract: A member function which removes all items within the array.
public:

virtual void flushCollection();


free

Abstract: Deallocates and releases all resources used by the OSArray instance. Normally, this is not called directly.
public:

virtual void free();

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


getCapacity

Abstract: A member function which returns the storage capacity of the OSArray object.
public:

virtual unsigned int getCapacity() const;

Result: Returns the storage capacity of the OSArray object.

getCapacityIncrement

Abstract: A member function which returns the size by which the array will grow.
public:

virtual unsigned int getCapacityIncrement() const;

Result: Returns the size by which the array will grow.

getCount

Abstract: A member function which returns the number of references contained within the OSArray object.
public:

virtual unsigned int getCount() const;

Result: Returns the number of items within the OSArray object.

getObject

Abstract: A member function wich returns a reference to an object located within the array at a given index. The caller should not release the returned object.
public:

virtual OSObject *getObject(unsigned int index) const;

Parameters

NameDescription
indexThe index into the array from which the reference to an object is taken.
Result: Returns a reference to an object or 0 if the index is beyond the bounds of the array.

initWithArray

Abstract: A member function which 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

NameDescription
anArrayAn instance of OSArray containing the references to objects which will be copied to the new instances of OSArray.
capacityThe 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.
Result: Returns a true if initialization succeeded or false if not.

initWithCapacity

Abstract: A member function which initializes an instance of OSArray.
public:

virtual bool initWithCapacity(unsigned int capacity);

Parameters

NameDescription
capacityThe initial capacity of the new instance of OSArray.
Result: Returns a true if initialization succeeded or false if not.

initWithObjects

Abstract: A member function which initializes an instance of OSArray and populates it with the given list of objects. #param objects A static array containing references to OSObject derived objects.
public:

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

Parameters

NameDescription
countThe number of objects to added to the array.
capacityThe 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'.
Result: Returns a true if initialization succeeded or false if not.

isEqualTo

Abstract: A member function which tests the equality of two OSArray objects.
public:

virtual bool isEqualTo(OSArray *anArray) const;

Parameters

NameDescription
anArrayThe array object being compared against the receiver.
Result: Returns true if the two arrays are equivalent or false otherwise.

isEqualTo

Abstract: A member function which compares the equality of the array to an arbitrary object.
public:

virtual bool isEqualTo(const OSObject *anObject) const;

Parameters

NameDescription
anObjectThe object to be compared against the receiver.
Result: 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.

lastObject

Abstract: A member function which returns a reference to the last object in the array. The caller should not release the returned object.
public:

virtual OSObject *lastObject() const;

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

merge

Abstract: A member function which appends the contents of an array onto the receiving array.
public:

virtual bool merge(const OSArray *otherArray);

Parameters

NameDescription
otherArrayThe array whose contents will be appended to the reveiving array.
Result: Returns true when merging was successful, false otherwise.

removeObject

Abstract: A member function which removes an object from the array.
public:

virtual void removeObject(unsigned int index);

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.

Parameters

NameDescription
indexThe index of the object to be removed.

replaceObject

Abstract: A member function which will replace an object in an array at a given index. The original object will be released and the new object will be retained.
public:

virtual void replaceObject(unsigned int index, OSObject *anObject);

Parameters

NameDescription
indexThe index into the array at which the new object will be placed.
anObjectThe object to be placed into the array.

serialize

Abstract: A member function which archives the receiver.
public:

virtual bool serialize(OSSerialize *s) const;

Parameters

NameDescription
sThe OSSerialize object.
Result: Returns true if serialization was successful, false if not.

setCapacityIncrement

Abstract: A member function which sets the growth size of the array.
public:

virtual unsigned int setCapacityIncrement(unsigned increment);

Result: Returns the new growth size.

setObject

Abstract: A member function which appends an object onto the end of the array.
public:

virtual bool setObject(OSObject *anObject);

Parameters

NameDescription
anObjectThe object to add to the OSArray instance. The object will be retained automatically.
Result: Returns a true if the addition of 'anObject' was successful, false if not.

setObject

Abstract: A member function which inserts an object into the array at a particular index.
public:

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

Parameters

NameDescription
indexThe index in the array to insert the object.
anObjectThe object to add to the OSArray instance. The object will be retained automatically.
Result: Returns true if the addition of 'anObject' was successful, false if not.

withArray

Abstract: A static constructor function to create and initialize an instance of OSArray of a given capacity and populate it with the contents of the supplied OSArray object.
public:

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

Parameters

NameDescription
arrayAn instance of OSArray from which the new instance will aquire its contents.
capacityThe 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.
Result: Returns a reference to an new instance of OSArray or 0 if an error occurred.

withCapacity

Abstract: A static constructor function to create and initialize a new instance of OSArray with a given capacity.
public:

static OSArray *withCapacity(unsigned int capacity);

Parameters

NameDescription
capacityThe initial capacity (number of refernces) of the OSArray instance.
Result: Returns a reference to an instance of OSArray or 0 if an error occurred.

withObjects

Abstract: A static constructor function to create and initialize a new instance of OSArray an populates it with a list of objects provided.
public:

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

Parameters

NameDescription
objectsA static array of references to OSObject derived objects.
countThe number of objects provided.
capacityThe 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.
Result: Returns a reference to an new instance of OSArray or 0 if an error occurred.

© 2000 Apple Computer, Inc. — (Last Updated 2/23/2000)