ChunkArrayGetCountHandles()

word	ChunkArrayGetCountHandles(
        MemHandle		mh,				/* Handle of LMem heap's block */
        ChunkHandle		ch);				/* Handle of chunk array */

This routine is just like ChunkArrayGetCount() , except that the chunk array is specified by its global and local handles (instead of with an optr).

Include: chunkarr.h

ChunkArrayGetElement()

void	ChunkArrayGetElement(
        optr	array,					/* optr to chunk array */
        word	elementNumber,					/* Index of element to copy */
        void *	buffer);					/* Address to copy element to */

This routine copies an element in a chunk array into the passed buffer. It is your responsibility to make sure the buffer is large enough to hold the element.

Include: chunkarr.h

Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed). Make sure the buffer is large enough to hold the element.

See Also: ChunkArrayPtrToElement(), ChunkArrayElementToPtr().

ChunkArrayGetElementHandles()

void	ChunkArrayGetElementHandles(
        Memhandle		mh,					/* Handle of LMem heap's block */
        ChunkHandle		array,					/* Handle of chunk array */
        word		elementNumber,					/* Index of element to copy */
        void *		buffer);					/* Address to copy element to */

This routine is just like ChunkArrayGetElement() , except that the chunk array is specified by its global and chunk handles (instead of with an optr).

Include: chunkarr.h

Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed). Make sure the buffer is large enough to hold the element.

See Also: ChunkArrayPtrToElement(), ChunkArrayElementToPtr().

ChunkArrayInsertAt()

void *	ChunkArrayInsertAt(
        optr		array,				/* Handle of chunk array */
        void *		insertPointer,				/* Address at which to insert
							 * element */

        word		elementSize);				/* Size of new element (ignored
							 * if elements are uniform-sized) */

This routine inserts a new element in a chunk array. You specify the location by passing a pointer to an element. A new element will be allocated at that location; thus, the element which was pointed to will be shifted, so it ends up immediately after the new element. The new element will be zero-initialized.

The routine is passed three arguments: the optr of the array, the address where the new element should be inserted, and the size of the new element. (If the array is of uniform-size elements, the size argument will be ignored.)

Include: chunkarr.h

Tips and Tricks: Only the chunk-handle portion of the optr is significant; the memory block is implicit in the pointer to the element.

Be Sure To: Lock the block on the global heap (if it is not fixed).

Warnings: If the address passed is not the address of an element already in the chunk array, results are undefined. The routine may cause heap compaction or resizing; all pointers within the block are invalidated.

See Also: ChunkArrayAppend(), ChunkArrayDelete().

ChunkArrayInsertAtHandle()

void *	ChunkArrayInsertAtHandle(
        ChunkHandle		chunk,				/* Handle of chunk array */
        void *		insertPointer,				/* Address at which to insert
							 * element */

        word		elementSize);				/* Size of new element (ignored
							 * if elements are uniform-sized) */

This routine is just like ChunkArrayInsertAt() , except that the chunk array is specified by its chunk handle. (The global block is implicit in the pointer passed.)

Include: chunkarr.h

ChunkArrayPtrToElement()

word	ChunkArrayPtrToElement(
        optr	array,						/* Handle of chunk array */
        void *	element);						/* Address of element */

This routine takes the address of an element in a chunk array, as well as an optr to the array. It returns the element's zero-based index.

Include: chunkarr.h

Tips and Tricks: Only the chunk-handle portion of the optr is significant; the memory block is implicit in the pointer to the element.

Be Sure To: Lock the block on the global heap (unless it is fixed).

Warnings: If the address passed is not the address of the beginning of an element, results are unpredictable.

See Also: ChunkArrayElementToPtr().

ChunkArrayPtrToElementHandle()

word 	ChunkArrayPtrToElementHandle(
        ChunkHandle		array,			/* chunk handle of chunk array */
        void *		element);			/* Pointer to element to delete */

This routine is exactly like ChunkArrayPtrToElement() , except that the chunk array is indicated by its chunk handle. (The global block is implicit in the pointer passed.)