LArray

Description Resizable array
Header file LArray.h
Author Irene Finocchi
Created Dec 12, 2001
Last updated Sep 7, 2002

 

Contents


Introduction

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.


Interface

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);


API Reference

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).
FALSE
if inIndex is out of range (and leaves outItem unchanged).

-
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 -


Revision history