Max 5 API Reference

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

Copyright © 2008, Cycling '74