Atom Array

Max's atomarray object is a container for an array of atoms with an interface for manipulating that array. More...

Data Structures
struct	t_atomarray
	The atomarray object. More...

Macros
#define	ATOMARRAY_FLAG_FREECHILDREN
	The atomarray flags. More...

Functions
BEGIN_USING_C_LINKAGE t_atomarray *	atomarray_new (long ac, t_atom *av)
	Create a new atomarray object. More...
void	atomarray_flags (t_atomarray *x, long flags)
	Set the atomarray flags. More...
long	atomarray_getflags (t_atomarray *x)
	Get the atomarray flags. More...
t_max_err	atomarray_setatoms (t_atomarray *x, long ac, t_atom *av)
	Replace the existing array contents with a new set of atoms Note that atoms provided to this function will be copied. More...
t_max_err	atomarray_getatoms (t_atomarray *x, long *ac, t_atom **av)
	Retrieve a pointer to the first atom in the internal array of atoms. More...
t_max_err	atomarray_copyatoms (t_atomarray *x, long *ac, t_atom **av)
	Retrieve a copy of the atoms in the array. More...
t_atom_long	atomarray_getsize (t_atomarray *x)
	Return the number of atoms in the array. More...
t_max_err	atomarray_getindex (t_atomarray *x, long index, t_atom *av)
	Copy an a specific atom from the array. More...
void *	atomarray_duplicate (t_atomarray *x)
	Create a new atomarray object which is a copy of another atomarray object. More...
void *	atomarray_clone (t_atomarray *x)
	Create a new atomarray object which is a full clone of another atomarray object. More...
void	atomarray_appendatom (t_atomarray *x, t_atom *a)
	Copy a new atom onto the end of the array. More...
void	atomarray_appendatoms (t_atomarray *x, long ac, t_atom *av)
	Copy multiple new atoms onto the end of the array. More...
void	atomarray_chuckindex (t_atomarray *x, long index)
	Remove an atom from any location within the array. More...
void	atomarray_clear (t_atomarray *x)
	Clear the array. More...
void	atomarray_funall (t_atomarray *x, method fun, void *arg)
	Call the specified function for every item in the atom array. More...

Detailed Description

Max's atomarray object is a container for an array of atoms with an interface for manipulating that array.

It can be useful for passing lists as a single atom, such as for the return value of an A_GIMMEBACK method. It also used frequently in when working with Max's t_dictionary object.

See also

Dictionary

Macro Definition Documentation

ATOMARRAY_FLAG_FREECHILDREN

#define ATOMARRAY_FLAG_FREECHILDREN

The atomarray flags.

Currently the only flag is ATOMARRAY_FLAG_FREECHILDREN. If set via atomarray_flags() the atomarray will free any contained A_OBJ atoms when the atomarray is freed.

Function Documentation

atomarray_appendatom()

void atomarray_appendatom	(	t_atomarray *	x,
		t_atom *	a
	)

Copy a new atom onto the end of the array.

Parameters

x	The atomarray instance.
a	A pointer to the new atom to append to the end of the array.

See also

atomarray_appendatoms()

atomarray_setatoms()

atomarray_appendatoms()

void atomarray_appendatoms	(	t_atomarray *	x,
		long	ac,
		t_atom *	av
	)

Copy multiple new atoms onto the end of the array.

Parameters

x	The atomarray instance.
ac	The number of new atoms to be appended to the array.
av	A pointer to the first of the new atoms to append to the end of the array.

See also

atomarray_appendatom()

atomarray_setatoms()

atomarray_chuckindex()

void atomarray_chuckindex	(	t_atomarray *	x,
		long	index
	)

Remove an atom from any location within the array.

The array will be resized and collapsed to fill in the gap.

Parameters

x	The atomarray instance.
index	The zero-based index of the atom to remove from the array.

atomarray_clear()

void atomarray_clear

(

t_atomarray *

x

)

Clear the array.

Frees all of the atoms and sets the size to zero. This function does not perform a 'deep' free, meaning that any A_OBJ atoms will not have their object's freed. Only the references to those objects contained in the atomarray will be freed.

Parameters

x	The atomarray instance.

Returns

The number of atoms in the array.

atomarray_clone()

void* atomarray_clone

(

t_atomarray *

x

)

Create a new atomarray object which is a full clone of another atomarray object.

Parameters

x	The atomarray instance which is to be copied.

Returns

A new atomarray which is copied from x.

See also

atomarray_new()

atomarray_copyatoms()

t_max_err atomarray_copyatoms	(	t_atomarray *	x,
		long *	ac,
		t_atom **	av
	)

Retrieve a copy of the atoms in the array.

To retrieve a pointer to the contained atoms use atomarray_getatoms().

Parameters

x	The atomarray instance.
ac	The address of a long where the number of atoms will be set.
av	The address of a t_atom pointer where the atoms will be allocated and copied.

Returns

A Max error code.

Remarks

You are responsible for freeing memory allocated for the copy of the atoms returned.

long    ac = 0;
t_atom *av = NULL;

atomarray_copyatoms(anAtomarray, &ac, &av);
if(ac && av){
    // do something with ac and av here...
    sysmem_freeptr(av);
}   

See also

atomarray_getatoms()

atomarray_duplicate()

void* atomarray_duplicate

(

t_atomarray *

x

)

Create a new atomarray object which is a copy of another atomarray object.

Parameters

x	The atomarray instance which is to be copied.

Returns

A new atomarray which is copied from x.

See also

atomarray_new()

atomarray_flags()

void atomarray_flags	(	t_atomarray *	x,
		long	flags
	)

Set the atomarray flags.

Parameters

x	The atomarray instance.
flags	The new value for the flags.

atomarray_funall()

void atomarray_funall	(	t_atomarray *	x,
		method	fun,
		void *	arg
	)

Call the specified function for every item in the atom array.

Parameters

x	The atomarray instance.
fun	The function to call, specified as function pointer cast to a Max method.
arg	An argument that you would like to pass to the function being called.

Returns

A max error code.

Remarks

The atomarray_funall() method will call your function for every item in the list. It will pass both a pointer to the item in the list, and any argument that you provide. The following example shows a function that could be called by hashtab_funall().

void myFun(t_atom *a, void *myArg)
{
    // do something with a and myArg here
    // a is the atom in the atom array
}

See also

linklist_funall()

hashtab_funall()

atomarray_getatoms()

t_max_err atomarray_getatoms	(	t_atomarray *	x,
		long *	ac,
		t_atom **	av
	)

Retrieve a pointer to the first atom in the internal array of atoms.

This method does not copy the atoms, btu simply provides access to them. To retrieve a copy of the atoms use atomarray_copyatoms().

Parameters

x	The atomarray instance.
ac	The address of a long where the number of atoms will be set.
av	The address of a t_atom pointer where the address of the first atom of the array will be set.

Returns

A Max error code.

See also

atomarray_copyatoms()

atomarray_getflags()

long atomarray_getflags

(

t_atomarray *

x

)

Get the atomarray flags.

Parameters

x	The atomarray instance.

Returns

The current value of the atomarray flags.

atomarray_getindex()

t_max_err atomarray_getindex	(	t_atomarray *	x,
		long	index,
		t_atom *	av
	)

Copy an a specific atom from the array.

Parameters

x	The atomarray instance.
index	The zero-based index into the array from which to retrieve an atom pointer.
av	The address of an atom to contain the copy.

Returns

A Max error code.

Remarks

Example:

{
    t_atom a;

    // fetch a copy of the second atom in a previously existing array
    atomarray_getindex(anAtomarray, 1, &a);
    // do something with the atom here...
}

atomarray_getsize()

t_atom_long atomarray_getsize

(

t_atomarray *

x

)

Return the number of atoms in the array.

Parameters

x	The atomarray instance.

Returns

The number of atoms in the array.

atomarray_new()

BEGIN_USING_C_LINKAGE t_atomarray* atomarray_new	(	long	ac,
		t_atom *	av
	)

Create a new atomarray object.

Note that atoms provided to this function will be copied. The copies stored internally to the atomarray instance. You can free the atomarray by calling object_free().

Parameters

ac	The number of atoms to be initially contained in the atomarray.
av	A pointer to the first of an array of atoms to initially copy into the atomarray.

Returns

Pointer to the new atomarray object.

Remarks

Note that due to the unusual prototype of this method that you cannot instantiate this object using the object_new_typed() function. If you wish to use the dynamically bound creator to instantiate the object, you should instead should use object_new() as demonstrated below. The primary reason that you might choose to instantiate an atomarray using object_new() instead of atomarray_new() is for using the atomarray object in code that is also intended to run in Max 4.

object_new(CLASS_NOBOX, gensym("atomarray"), argc, argv);

See also

atomarray_duplicate()

atomarray_setatoms()

t_max_err atomarray_setatoms	(	t_atomarray *	x,
		long	ac,
		t_atom *	av
	)

Replace the existing array contents with a new set of atoms Note that atoms provided to this function will be copied.

The copies stored internally to the atomarray instance.

Parameters

x	The atomarray instance.
ac	The number of atoms to be initially contained in the atomarray.
av	A pointer to the first of an array of atoms to initially copy into the atomarray.

Returns

A Max error code.