NameArrayAdd()

word	NameArrayAdd(
        optr 		arr,				/* optr of name array */
        const char		* nameToAdd,				/* Name of new element */
        word		nameLength,				/* Length of name; pass zero if
						 * name string is null-terminated */

        NameArrayAddFlags		flags,				/* Described below */
        const	void	* data);				/* Copy this data to new element */

This routine creates a new element in a name array, copying the passed name and data into the new element. If no element with the passed name exists, NameArrayAdd() will create the element and return its token. If an element with the same name already exists, the existing element's reference count will be incremented and its token will be returned. The routine takes the following arguments:

array: The optr of the name array.
nameToAdd: The name of the new element. This string may contain nulls.
nameLength: The length of the name string, in bytes. If you pass zero, NameArrayAdd() will assume the string is null-terminated.
flags: A record of NameArrayAddFlags , described below.
data: The data to copy into the new element.

Structures: The argument is passed a set of NameArrayAddFlags . Only one flag is currently defined:

NAAF_SET_DATA_ON_REPLACE: If an element with the specified name exists and this flag is set, the data passed will be copied into the data area of the existing element. If this flag is not set, the existing element will not be changed.

Warnings: This routine may resize the name array; therefore, all pointers to the LMem heap are invalidated.

Include: chunkarr.h

NameArrayAddHandles()

dword	NameArrayAddHandles(
        MemHandle 		mh,				/* Handle of LMem heap */
        ChunkHandle 		arr,				/* Chunk handle of name array */
        const char * 		nameToAdd,				/* Name of new element */
        word		nameLength,				/* Length of name; pass zero if
						 * name string is null-terminated */

        NameArrayAddFlags		flags,				/* Described below */
        const	void *	data);				/* Copy this data to new element */

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

Warnings: This routine may resize the name array; therefore, all pointers to within the LMem heap are invalidated.

Include: chunkarr.h

NameArrayChangeName()

void	NameArrayChangeName(
        optr 		array,			/* optr of name array */
        word		token,			/* Token of element to be changed */
        const char * 		newName,			/* New name for element */
        word		nameLength);				/* Length of name in bytes; pass
						 * zero if name string is
						 * null-terminated */

This routine changes the name of an element in a name array.

Warnings: If the new name is longer than the old, the chunk will be resized, invalidating all pointers to within the LMem heap.

Include: chunkarr.h

NameArrayChangeNameHandles()

dword	NameArrayChangeNameHandles(
        MemHandle 		mh,				/* Handle of LMem heap */
        ChunkHandle 		array,				/* Chunk handle of name array */
        word		token,				/* Token of element to be changed */
        const char * 		newName,				/* New name for element */
        word		nameLength);				/* Length of name in bytes; pass
						 * zero if name string is
						 * null-terminated */

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

Warnings: If the new name is longer than the old, the chunk will be resized, invalidating all pointers to within the LMem heap.

Include: chunkarr.h

NameArrayCreate()

ChunkHandle 	NameArrayCreate(
        MemHandle 		mh,				/* Global handle of LMem heap */
        word		dataSize,				/* Size of data section for
						 * each element */

        word		headerSize);				/* Size of header; pass
						 * zero for default header */

This routine creates a name array in the indicated LMem heap. It creates a NameArrayHeader structure at the head of a new chunk. If you want to leave extra space before the start of the array, you can pass a larger header size; if you want to use the standard header, pass a header size of zero.

You must specify the size of the data portion of each element when you create the array. The name portion will be variable sized.

Include: chunkarr.h

Tips and Tricks: If you want extra space after the NameArrayHeader , you may want to create your own header structure, the first element of which is a NameArrayHeader . You can pass the size of this header to NameArrayCreate() and access the data in your header via the structure fields.

Be Sure To: Lock the block on the global heap before calling this routine (unless it is fixed). If you pass a header size, make sure it is larger than sizeof(NameArrayHeader) .

Include: chunkarr.h

NameArrayCreateAt()

ChunkHandle 	NameArrayCreateAt(
        optr	array,	/* Turn this chunk into a name array */
        word	dataSize,	/* Size of data section of each element */
        word	headerSize); 	/* Size of header; pass zero for default header */

This routine is just like NameArrayCreate() above, except that the element array is created in a pre-existing chunk. The contents of that chunk will be destroyed.

Include: chunkarr.h

Warnings: If the chunk isn't large enough, it will be resized. This will invalidate all pointers to chunks in that block.

Include: chunkarr.h

NameArrayCreateAtHandles()

ChunkHandle 	NameArrayCreateAtHandles(
        MemHandle 		mh,				/* Global handle of LMem heap */
        ChunkHandle 		chunk,				/* the chunk for the array */
        word		dataSize,				/* Size of data for each element */
        word		headerSize);				/* Size of header; pass
						 * zero for default header */

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

Include: chunkarr.h

Warnings: If the chunk isn't large enough, it will be resized. This will invalidate all pointers to chunks in that block.

Include: chunkarr.h