Plank DynamicArray class

A dynamic array. More...

Typedefs
typedef struct PlankDynamicArray *	PlankDynamicArrayRef
	An opaque reference to the Plank DynamicArray object.
typedef PlankB(*	PlankDynamicArrayCompareFunction )(PlankP, PlankP)
	Compare function.
Functions
PlankDynamicArrayRef	pl_DynamicArray_CreateAndInit ()
	Creates and intialises a Plank DynamicArray object and return an oqaque reference to it.
PlankDynamicArrayRef	pl_DynamicArray_Create ()
	Create a Plank DynamicArray object and return an oqaque reference to it.
PlankResult	pl_DynamicArray_Init (PlankDynamicArrayRef p)
	Initialise the array.
PlankResult	pl_DynamicArray_InitWithItemSize (PlankDynamicArrayRef p, const PlankL itemSize)
	Initialise the array.
PlankResult	pl_DynamicArray_InitWithItemSizeAndCapacity (PlankDynamicArrayRef p, const PlankL itemSize, const PlankL initialCapacity)
	Initialise the array with specified capacity.
PlankResult	pl_DynamicArray_DeInit (PlankDynamicArrayRef p)
	Denitialise the array.
PlankResult	pl_DynamicArray_Destroy (PlankDynamicArrayRef p)
	Destroy a Plank DynamicArray object.
PlankB	pl_DynamicArray_IsIndexInRange (PlankDynamicArrayRef p, const PlankL index)
	Determines if an index is in range for this array.
PlankL	pl_DynamicArray_GetSize (PlankDynamicArrayRef p)
	Get the number of items stored in the array.
PlankL	pl_DynamicArray_GetItemSize (PlankDynamicArrayRef p)
	Get the size of a single item stored in the array.
PlankP	pl_DynamicArray_GetArray (PlankDynamicArrayRef p)
	Get the raw array.
PlankResult	pl_DynamicArray_AddItem (PlankDynamicArrayRef p, const PlankP item)
	Add an item to the array.
PlankResult	pl_DynamicArray_SetItem (PlankDynamicArrayRef p, const PlankL index, const PlankP item)
	Copies an item to the specified index.
PlankResult	pl_DynamicArray_InsertItem (PlankDynamicArrayRef p, const PlankL index, const PlankP item)
	Inserts an item into the specified index.
PlankResult	pl_DynamicArray_GetItem (PlankDynamicArrayRef p, const PlankL index, PlankP item)
	Retrieves an item at the specified index.
PlankResult	pl_DynamicArray_RemoveItem (PlankDynamicArrayRef p, const PlankL index)
	Removes an item from the specified index.
PlankResult	pl_DynamicArray_EnsureSize (PlankDynamicArrayRef p, const PlankL capacity)
	Ensures that the array is sufficient to hold a certain number of items.
PlankResult	pl_DynamicArray_Grow (PlankDynamicArrayRef p, const int amount)
	Inreases the array's capcity by a spefcified number of items.
PlankResult	pl_DynamicArray_Purge (PlankDynamicArrayRef p)
	Reduces the amount of memory the array uses to the minimum.

---

Detailed Description

A dynamic array.

---

Typedef Documentation

typedef PlankB(* PlankDynamicArrayCompareFunction)(PlankP, PlankP)

Compare function.

This should return PLANK_TRUE if the first argument should be placed after the second argument in a sorted array.

typedef struct PlankDynamicArray* PlankDynamicArrayRef

An opaque reference to the Plank DynamicArray object.

---

Function Documentation

PlankResult pl_DynamicArray_AddItem	(	PlankDynamicArrayRef	p,
		const PlankP	item
	)

Add an item to the array.

This copies the bytes from one memory location to the array data based on the item size set during initialisation.

Parameters:

p	The Plank DynamicArray object.
item	The item to add to the array.

Returns:

A result code which will be PlankResult_OK if the operation was completely successful.

PlankDynamicArrayRef pl_DynamicArray_Create

(

)

Create a Plank DynamicArray object and return an oqaque reference to it.

Returns:

A Plank DynamicArray object as an opaque reference or PLANK_NULL.

PlankDynamicArrayRef pl_DynamicArray_CreateAndInit

(

)

Creates and intialises a Plank DynamicArray object and return an oqaque reference to it.

Returns:

A Plank DynamicArray object as an opaque reference or PLANK_NULL.

PlankResult pl_DynamicArray_DeInit

(

PlankDynamicArrayRef

p

)

Denitialise the array.

Parameters:

p	The Plank DynamicArray object.

Returns:

A result code which will be PlankResult_OK if the operation was completely successful.

PlankResult pl_DynamicArray_Destroy

(

PlankDynamicArrayRef

p

)

Destroy a Plank DynamicArray object.

Parameters:

p	The Plank DynamicArray object.

Returns:

A result code which will be PlankResult_OK if the operation was completely successful.

PlankResult pl_DynamicArray_EnsureSize	(	PlankDynamicArrayRef	p,
		const PlankL	capacity
	)

Ensures that the array is sufficient to hold a certain number of items.

This will resize the array if necessary to hold the specified capacity. This only resizes the avauilable capacity pl_DynamicArray_GetSize() will still return the number of items used.

Parameters:

p	The Plank DynamicArray object.
capacity	The number of items the array should be set to hold.

Returns:

A result code which will be PlankResult_OK if the operation was completely successful.

PlankP pl_DynamicArray_GetArray

(

PlankDynamicArrayRef

p

)

Get the raw array.

PlankResult pl_DynamicArray_GetItem	(	PlankDynamicArrayRef	p,
		const PlankL	index,
		PlankP	item
	)

Retrieves an item at the specified index.

Parameters:

p	The Plank DynamicArray object.
index	The desired index. This must be between 0 and one less that the current size.
item	The destination to copy the specified item. This must point to memory of sufficient size to hold the item.

Returns:

A result code which will be PlankResult_OK if the operation was completely successful.

PlankL pl_DynamicArray_GetItemSize

(

PlankDynamicArrayRef

p

)

Get the size of a single item stored in the array.

PlankL pl_DynamicArray_GetSize

(

PlankDynamicArrayRef

p

)

Get the number of items stored in the array.

PlankResult pl_DynamicArray_Grow	(	PlankDynamicArrayRef	p,
		const int	amount
	)

Inreases the array's capcity by a spefcified number of items.

Parameters:

p	The Plank DynamicArray object.
amount	The number of additional items the array should be set to hold.

Returns:

A result code which will be PlankResult_OK if the operation was completely successful.

PlankResult pl_DynamicArray_Init

(

PlankDynamicArrayRef

p

)

Initialise the array.

Parameters:

p	The Plank DynamicArray object.

Returns:

A result code which will be PlankResult_OK if the operation was completely successful.

PlankResult pl_DynamicArray_InitWithItemSize	(	PlankDynamicArrayRef	p,
		const PlankL	itemSize
	)

Initialise the array.

Parameters:

p	The Plank DynamicArray object.

Returns:

A result code which will be PlankResult_OK if the operation was completely successful.

PlankResult pl_DynamicArray_InitWithItemSizeAndCapacity	(	PlankDynamicArrayRef	p,
		const PlankL	itemSize,
		const PlankL	initialCapacity
	)

Initialise the array with specified capacity.

Parameters:

p	The Plank DynamicArray object.

Returns:

A result code which will be PlankResult_OK if the operation was completely successful.

PlankResult pl_DynamicArray_InsertItem	(	PlankDynamicArrayRef	p,
		const PlankL	index,
		const PlankP	item
	)

Inserts an item into the specified index.

This copies the bytes from one memory location to the array data based on the item size set during initialisation. Items above the specified index will be moved one index higher.

Parameters:

p	The Plank DynamicArray object.
index	The desired index. This should be 0 or greater. If this is beyond the size of the array the item will be added to the end.
item	The item to add to the array.

Returns:

A result code which will be PlankResult_OK if the operation was completely successful.

PlankB pl_DynamicArray_IsIndexInRange	(	PlankDynamicArrayRef	p,
		const PlankL	index
	)

Determines if an index is in range for this array.

PlankResult pl_DynamicArray_Purge

(

PlankDynamicArrayRef

p

)

Reduces the amount of memory the array uses to the minimum.

This sets the allocated size to the number of items used. During this operation the array may temporarily require more memory.

Parameters:

p	The Plank DynamicArray object.

Returns:

A result code which will be PlankResult_OK if the operation was completely successful.

PlankResult pl_DynamicArray_RemoveItem	(	PlankDynamicArrayRef	p,
		const PlankL	index
	)

Removes an item from the specified index.

Parameters:

p	The Plank DynamicArray object.
index	The desired index to remove. This must be between 0 and one less that the current size.

Returns:

A result code which will be PlankResult_OK if the operation was completely successful.

PlankResult pl_DynamicArray_SetItem	(	PlankDynamicArrayRef	p,
		const PlankL	index,
		const PlankP	item
	)

Copies an item to the specified index.

This copies the bytes from one memory location to the array data based on the item size set during initialisation.

Parameters:

p	The Plank DynamicArray object.
index	The desired index. This must be between 0 and one less that the current size.
item	The item to add to the array.

Returns:

A result code which will be PlankResult_OK if the operation was completely successful.