Atom Array
[Data Storage]

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

Collaboration diagram for Atom Array:

Data Structures
struct	t_atomarray
	The atomarray object. More...
Defines
#define	ATOMARRAY_FLAG_FREECHILDREN (1)
	The atomarray flags.
Functions
t_atomarray *	atomarray_new (long ac, t_atom *av)
	Create a new atomarray object.
void	atomarray_flags (t_atomarray *x, long flags)
	Set the atomarray flags.
long	atomarray_getflags (t_atomarray *x)
	Get the atomarray flags.
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.
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.
t_max_err	atomarray_copyatoms (t_atomarray x, long ac, t_atom **av)
	Retrieve a copy of the atoms in the array.
long	atomarray_getsize (t_atomarray *x)
	Return the number of atoms in the array.
t_max_err	atomarray_getindex (t_atomarray x, long index, t_atom av)
	Copy an a specific atom from the array.
void *	atomarray_duplicate (t_atomarray *x)
	Create a new atomarray object which is a copy of another atomarray object.
void	atomarray_appendatom (t_atomarray x, t_atom a)
	Copy a new atom onto the end of the array.
void	atomarray_appendatoms (t_atomarray x, long ac, t_atom av)
	Copy multiple new atoms onto the end of the array.
void	atomarray_chuckindex (t_atomarray *x, long index)
	Remove an atom from any location within the array.
void	atomarray_clear (t_atomarray *x)
	Clear the array.
void	atomarray_funall (t_atomarray x, method fun, void arg)
	Call the specified function for every item in the atom array.

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

Define Documentation

#define ATOMARRAY_FLAG_FREECHILDREN (1)

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

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

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

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.

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.

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

Retrieve a copy of the atoms in the array.

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

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

void atomarray_flags	(	t_atomarray *	x,
		long	flags
	)

Set the atomarray flags.

Parameters:

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

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

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

long atomarray_getflags ( t_atomarray * x )

Get the atomarray flags.

Parameters:

x

The atomarray instance.

Returns:: The current value of the atomarray flags.

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

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.

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

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.

Atom Array [Data Storage]

Data Structures

Defines

Functions

Detailed Description

Define Documentation

Function Documentation

Atom Array
[Data Storage]