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

Name Description

newCapacity The new capacity for the array.

Name	Description
`newCapacity`	The 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

Name Description

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

Name	Description
`index`	The 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

Name Description

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.

Name	Description
`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.

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

Name Description

capacity The initial capacity of the new instance of OSArray.

Name	Description
`capacity`	The initial capacity of the new instance of OSArray.

Result: Returns a true if initialization succeeded or false if not.

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

Name Description

count The number of objects to 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'.

Name	Description
`count`	The number of objects to 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'.

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

Name Description

anArray The array object being compared against the receiver.

Name	Description
`anArray`	The 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

Name Description

anObject The object to be compared against the receiver.

Name	Description
`anObject`	The 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

Name Description

otherArray The array whose contents will be appended to the reveiving array.

Name	Description
`otherArray`	The 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

Name Description

index The index of the object to be removed.

Name	Description
`index`	The 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

Name Description

index The index into the array at which the new object will be placed.

anObject The object to be placed into the array.

Name	Description
`index`	The index into the array at which the new object will be placed.
`anObject`	The object to be placed into the array.

serialize

Abstract: A member function which archives the receiver.

public:

virtual bool serialize(OSSerialize *s) const;

Parameters

Name Description

s The OSSerialize object.

Name	Description
`s`	The 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

Name Description

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

Name	Description
`anObject`	The 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

Name Description

index The index in the array to insert the object.

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

Name	Description
`index`	The index in the array to insert the object.
`anObject`	The 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

Name Description

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.

Name	Description
`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.

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

Name Description

capacity The initial capacity (number of refernces) of the OSArray instance.

Name	Description
`capacity`	The 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

Name Description

objects A static array of references to OSObject 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.

Name	Description
`objects`	A static array of references to OSObject 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.

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