Description | Resizable array |
Header file | LArray.h |
Author | Irene Finocchi |
Created | Dec 12, 2001 |
Last updated | Sep 7, 2002 |
The component LArray provides support for maintaining an array whose size is not known until run time. Items in the array must have all the same size and entries are indexed by numbers in the range [0,n-1], where n is the number of entries in the array. Member functions allow it to add new items, remove existing items, and browse the array by index, retrieving items, and accessing directly the chunk of memory containing the items.
Constants |
|
LArray_ID LArray_OUT_OF_MEMORY LArray_INVALID_SIZE LArray_OUT_OF_RANGE |
Types |
|
struct LArray |
Functions |
|
LArray* LArray_New (ui4 inItemSize) LArray* LArray_NewFromData (ui4 inItemSize, void** inDataA, ui4 inDataSize) void LArray_Delete (LArray** ThisA) void LArray_InsertItemAt (LArray* This, const void* inItem, ui4 inIndex) void LArray_RemoveItemAt (LArray* This, ui4 inIndex) ui4 LArray_AppendItem (LArray* This, const void* inItem) void LArray_ResizeBy (LArray* This, i4 inDeltaItems) void LArray_RemoveLastItem (LArray* This) void LArray_RemoveAllItems (LArray* This) void* LArray_ItemAt (LArray* This, ui4 inIndex) void* LArray_LastItem (LArray* This) Bool LArray_FetchItemAt (LArray* This, ui4 inIndex, void* outItem) void* LArray_GetData (LArray* This) ui4 LArray_GetDataSize (LArray* This) ui4 LArray_GetItemsCount (LArray* This) void LArray_Dump (LArray* This) ui4 LArray_GetUsedMem (LArray* This) void LArray_InstallSyncPtr (LArray* This, void** thruDataPtr) ui4 LArray_GetItemSize (LArray* This); |
Function | Arguments | Description | Returns | Throws |
New | ui4 inItemSize | Create object containing an empty array. The size of each array item is set to inItemSize. Caller is responsible of dellocating the created object using LArray_Delete. |
LArray* pointer to newly created object |
INVALID_SIZE if inItemSize==0. |
NewFromData
|
ui4 inItemSize |
Create object with data segment *inDataA of size inDataSize. The entry size is inItemSize. The LArray object becomes responsible of deallocating the segment *inDataA, which should not be deallocated by caller. Caller is responsible of dellocating the created object using LArray_Delete. *inDataA is set to NULL. |
LArray* pointer to newly created object |
INVALID_SIZE if inItemSize==0 or if inDataSize modulo inItemSize is non-zero. |
void** inDataA | ||||
ui4 inDataSize | ||||
Delete | LArray** ThisA | Release object *ThisA. *ThisA is set to NULL. | void | - |
ResizeBy | LArray* This | Expand (if inDeltaItems>0) or shrink (if inDeltaItems<0) the array by inDeltaItems items. IfinDeltaItems==0 the operation has no effect. | void | OUT_OF_MEMORY if memory allocation fails. |
i4 inDeltaItems | ||||
AppendItem | LArray* This | Expand the array by 1 entry and copy item inItem to the new entry. |
ui4 Index of the newly inserted item. |
OUT_OF_MEMORY if memory allocation fails. |
const void* inItem | ||||
RemoveLastItem | LArray* This | Remove the last entry in the array. Do nothing if the array is empty. | void | - |
RemoveAllItems | LArray* This | Remove all entries in the array. Do nothing if the array is already empty. After the operation GetItemsCount() returns zero. | void | - |
ItemAt | LArray* This | - |
void* Pointer to the item with index inIndex in the range [0..GetItemsCount()-1]. |
OUT_OF_RANGE if inIndex is out of range. |
ui4 inIndex | ||||
LastItem | LArray* This | - |
void* Pointer to the last item, with index GetItemsCount()-1. |
OUT_OF_RANGE if the array is empty. |
FetchItemAt | LArray* This | Copy to outItem the content of the array entry with index inIndex in the range [0..GetItemsCount()-1]. Caller must make sure that outItem points a buffer large enough to hold the item. |
Bool TRUE if a valid entry exists at inIndex (and sets outItem). |
- |
ui4 inIndex | ||||
void* outItem | ||||
GetData | LArray* This |
Give external access to the data segment. If A is an LArray object whose items have type T, then LArray_ItemAt(A,i)==((T*)LArray_GetData(A))+i.The LArray object is still responsible of deallocating the data segment, which should never be deallocated by caller. The returned pointer might be no longer valid if an insertion/deletion is performed on the LArray object This. See also InstallSyncPtr to maintain a safe pointer to the data segment. |
void* Pointer to the current data segment of the array This (might be NULL if GetItemsCount() is zero). |
- |
GetDataSize | LArray* This | - |
ui4 Size in bytes of the data segment in the array This. |
- |
GetItemsCount | LArray* This | - |
ui4 Number of valid entries in the array This. |
- |
GetUsedMem | LArray* This | Compute the total number of bytes internally used by the object This |
ui4 Bytes used by object |
- |
InstallSyncPtr | LArray* This | Used to maintains a safe external pointer to the data segment. It installs the address thruDataPtr of a pointer variable and makes it always contain the correct address of the data segment of object This. This way, even if the array might be reallocated due to some operation, the variable pointed to by thruDataPtr will be always contain the correct address of the data segment.This allows a faster external access to array items, while still supporting dynamic array resizing. | void | - |
void** thruDataPtr | ||||
GetItemSize | LArray* This | Returns the size in bytes of each item in array This. |
ui4 Bytes used by each item in the object |
- |
Dump | LArray* This | Sends to the debugging console information about LArray object This. (Debug Mode) | void | - |