IBM Visualization Data Explorer Programmer's Reference

DXAddArrayData

Function Adds items to an Array.

Syntax

#include <dx/dx.h>
Array DXAddArrayData(Array a, int start, int n, Pointer data)

Functional Details Adds n items to Array a, starting at the numbered item specified by start. The additions may replace or supplement items already defined. If data is not NULL, the routine copies the data into the Array; otherwise, it increases the number of items in the Array by n, but leaves them uninitialized.

To avoid having memory allocated every time, DXAddArrayData may allocate more than is needed for the requested number of items. If Array a is part of a Field, any extra space will be freed when DXEndField is called. If it is not part of a Field, DXTrim can be called to free the extra space, though this is not required.

To allocate space "up front" for an Array of known size, use DXAddArrayData(0, n, NULL), which is the preferred means for preallocating space for the data.

DXAllocateArray(0, n, NULL) also preallocates space, but the number of items in the Array will be 0. If DXAllocateArray is called, DXTrim can be called to resize the Array to the space required for the actual number of items.

Allocating more space for an Array may result in its being copied to a new location in memory. If you call DXGetArrayData to obtain a pointer for an Array and then allocate more space for it, you must call DXGetArrayData again because the pointer may no longer be valid.

There are four ways to add data to irregular Arrays:

• Add items one at a time: DXAddArrayData(a, i, 1,item).
• Add items in batches: DXAddArrayData(a, i, n, items).
• Add multiple items all at one time: DXAddArrayData(a, 0, n, items).
• Allocate the memory: call DXAddArrayData(a, 0, n, NULL); get a pointer to global memory with DXGetArrayData(a); and put the items directly into global memory "by hand."

Return Value Returns a or returns NULL and sets an error code.

See Also DXAllocateArray, DXEndField, DXGetArrayData, DXTrim ,

"Irregular Arrays".

[Data Explorer Home Page | Contact Data Explorer | Same document on Data Explorer Home Page ]