Max 5 API Reference

Atoms
[Data Types]

Collaboration diagram for Atoms:

Data Structures

union  word
 Union for packing any of the datum defined in e_max_atomtypes. More...
struct  t_atom
 An atom is a typed datum. More...

Defines

#define ATOM_MAX_STRLEN   (32768)
 Defines the largest possible string size for an atom.

Enumerations

enum  e_max_atomtypes {
  A_NOTHING = 0,
  A_LONG,
  A_FLOAT,
  A_SYM,
  A_OBJ,
  A_DEFLONG,
  A_DEFFLOAT,
  A_DEFSYM,
  A_GIMME,
  A_CANT,
  A_SEMI,
  A_COMMA,
  A_DOLLAR,
  A_DOLLSYM,
  A_GIMMEBACK,
  A_DEFER = 0x41,
  A_USURP = 0x42,
  A_DEFER_LOW = 0x43,
  A_USURP_LOW = 0x44
}
 

the list of officially recognized types, including pseudotypes for commas and semicolons.

More...
enum  e_max_atom_gettext_flags {
  OBEX_UTIL_ATOM_GETTEXT_DEFAULT = 0x00000000,
  OBEX_UTIL_ATOM_GETTEXT_TRUNCATE_ZEROS = 0x00000001,
  OBEX_UTIL_ATOM_GETTEXT_SYM_NO_QUOTE = 0x00000002,
  OBEX_UTIL_ATOM_GETTEXT_SYM_FORCE_QUOTE = 0x00000004,
  OBEX_UTIL_ATOM_GETTEXT_COMMA_DELIM = 0x00000008,
  OBEX_UTIL_ATOM_GETTEXT_FORCE_ZEROS = 0x00000010,
  OBEX_UTIL_ATOM_GETTEXT_NUM_HI_RES = 0x00000020
}
 

Flags that determine how functions convert atoms into text (C-strings).

More...

Functions

t_max_err atom_setlong (t_atom *a, long b)
 Inserts an integer into a t_atom and change the t_atom's type to A_LONG.
t_max_err atom_setfloat (t_atom *a, double b)
 Inserts a floating point number into a t_atom and change the t_atom's type to A_FLOAT.
t_max_err atom_setsym (t_atom *a, t_symbol *b)
 Inserts a t_symbol * into a t_atom and change the t_atom's type to A_SYM.
t_max_err atom_setobj (t_atom *a, void *b)
 Inserts a generic pointer value into a t_atom and change the t_atom's type to A_OBJ.
long atom_getlong (t_atom *a)
 Retrieves a long integer value from a t_atom.
float atom_getfloat (t_atom *a)
 Retrieves a floating point value from a t_atom.
t_symbolatom_getsym (t_atom *a)
 Retrieves a t_symbol * value from a t_atom.
void * atom_getobj (t_atom *a)
 Retrieves a generic pointer value from a t_atom.
long atom_getcharfix (t_atom *a)
 Retrieves an unsigned integer value between 0 and 255 from a t_atom.
long atom_gettype (t_atom *a)
 Retrieves type from a t_atom.
long atom_arg_getlong (long *c, long idx, long ac, t_atom *av)
 Retrieves the integer value of a particular t_atom from an atom list, if the atom exists.
long atom_arg_getfloat (float *c, long idx, long ac, t_atom *av)
 Retrieves the floating point value of a particular t_atom from an atom list, if the atom exists.
long atom_arg_getdouble (double *c, long idx, long ac, t_atom *av)
 Retrieves the floating point value, as a double, of a particular t_atom from an atom list, if the atom exists.
long atom_arg_getsym (t_symbol **c, long idx, long ac, t_atom *av)
 Retrieves the t_symbol * value of a particular t_atom from an atom list, if the atom exists.
t_max_err atom_alloc (long *ac, t_atom **av, char *alloc)
 Allocate a single atom.
t_max_err atom_alloc_array (long minsize, long *ac, t_atom **av, char *alloc)
 Allocate an array of atoms.
t_max_err atom_setchar_array (long ac, t_atom *av, long count, unsigned char *vals)
 Assign an array of char values to an array of atoms.
t_max_err atom_setlong_array (long ac, t_atom *av, long count, long *vals)
 Assign an array of long integer values to an array of atoms.
t_max_err atom_setfloat_array (long ac, t_atom *av, long count, float *vals)
 Assign an array of 32bit float values to an array of atoms.
t_max_err atom_setdouble_array (long ac, t_atom *av, long count, double *vals)
 Assign an array of 64bit float values to an array of atoms.
t_max_err atom_setsym_array (long ac, t_atom *av, long count, t_symbol **vals)
 Assign an array of t_symbol* values to an array of atoms.
t_max_err atom_setatom_array (long ac, t_atom *av, long count, t_atom *vals)
 Assign an array of t_atom values to an array of atoms.
t_max_err atom_setobj_array (long ac, t_atom *av, long count, t_object **vals)
 Assign an array of t_object* values to an array of atoms.
t_max_err atom_setparse (long *ac, t_atom **av, char *parsestr)
 Parse a C-string into an array of atoms.
t_max_err atom_setformat (long *ac, t_atom **av, char *fmt,...)
 Create an array of atoms populated with values using sprintf-like syntax.
t_max_err atom_getformat (long ac, t_atom *av, char *fmt,...)
 Retrieve values from an array of atoms using sscanf-like syntax.
t_max_err atom_gettext (long ac, t_atom *av, long *textsize, char **text, long flags)
 Convert an array of atoms into a C-string.
t_max_err atom_getchar_array (long ac, t_atom *av, long count, unsigned char *vals)
 Fetch an array of char values from an array of atoms.
t_max_err atom_getlong_array (long ac, t_atom *av, long count, long *vals)
 Fetch an array of long integer values from an array of atoms.
t_max_err atom_getfloat_array (long ac, t_atom *av, long count, float *vals)
 Fetch an array of 32bit float values from an array of atoms.
t_max_err atom_getdouble_array (long ac, t_atom *av, long count, double *vals)
 Fetch an array of 64bit float values from an array of atoms.
t_max_err atom_getsym_array (long ac, t_atom *av, long count, t_symbol **vals)
 Fetch an array of t_symbol* values from an array of atoms.
t_max_err atom_getatom_array (long ac, t_atom *av, long count, t_atom *vals)
 Fetch an array of t_atom values from an array of atoms.
t_max_err atom_getobj_array (long ac, t_atom *av, long count, t_object **vals)
 Fetch an array of t_object* values from an array of atoms.
long atomisstring (t_atom *a)
 Determines whether or not an atom represents a t_string object.
long atomisatomarray (t_atom *a)
 Determines whether or not an atom represents a t_atomarray object.
long atomisdictionary (t_atom *a)
 Determines whether or not an atom represents a t_dictionary object.
BEGIN_USING_C_LINKAGE void atom_copy (short argc1, t_atom *argv1, t_atom *argv2)
 Copy an array of atoms.
void postargs (short argc, t_atom *argv)
 Print the contents of an array of atoms to the Max window.
t_max_err atom_arg_getobjclass (t_object **x, long idx, long argc, t_atom *argv, t_symbol *cls)
 Return a pointer to an object contained in an atom if it is of the specified class.
void * atom_getobjclass (t_atom *av, t_symbol *cls)
 Return a pointer to an object contained in an atom if it is of the specified class.

Enumeration Type Documentation

Flags that determine how functions convert atoms into text (C-strings).

Enumerator:
OBEX_UTIL_ATOM_GETTEXT_DEFAULT 

default translation rules for getting text from atoms

OBEX_UTIL_ATOM_GETTEXT_TRUNCATE_ZEROS 

eliminate redundant zeros for floating point numbers (default used)

OBEX_UTIL_ATOM_GETTEXT_SYM_NO_QUOTE 

don't introduce quotes around symbols with spaces

OBEX_UTIL_ATOM_GETTEXT_SYM_FORCE_QUOTE 

always introduce quotes around symbols (useful for JSON)

OBEX_UTIL_ATOM_GETTEXT_COMMA_DELIM 

separate atoms with commas (useful for JSON)

OBEX_UTIL_ATOM_GETTEXT_FORCE_ZEROS 

always print the zeros

OBEX_UTIL_ATOM_GETTEXT_NUM_HI_RES 

print more decimal places

the list of officially recognized types, including pseudotypes for commas and semicolons.

Used in two places: 1. the reader, when it reads a string, returns long, float, sym, comma, semi, or dollar; and 2. each object method comes with an array of them saying what types it needs, from among long, float, sym, obj, gimme, and cant.

Remarks:
While these values are defined in an enum, you should use a long to represent the value. Using the enum type creates ambiguity in struct size and is subject to various inconsistent compiler settings.
Enumerator:
A_NOTHING 

no type, thus no atom

A_LONG 

long integer

A_FLOAT 

32-bit float

A_SYM 

t_symbol pointer

A_OBJ 

t_object pointer (for argtype lists; passes the value of sym)

A_DEFLONG 

long but defaults to zero

A_DEFFLOAT 

float, but defaults to zero

A_DEFSYM 

symbol, defaults to ""

A_GIMME 

request that args be passed as an array, the routine will check the types itself.

A_CANT 

cannot typecheck args

A_SEMI 

semicolon

A_COMMA 

comma

A_DOLLAR 

dollar

A_DOLLSYM 

dollar

A_GIMMEBACK 

request that args be passed as an array, the routine will check the types itself. can return atom value in final atom ptr arg. function returns long error code 0 = no err. see gimmeback_meth typedef

A_DEFER 

A special signature for declaring methods. This is like A_GIMME, but the call is deferred.

A_USURP 

A special signature for declaring methods. This is like A_GIMME, but the call is deferred and multiple calls within one servicing of the queue are filtered down to one call.

A_DEFER_LOW 

A special signature for declaring methods. This is like A_GIMME, but the call is deferref to the back of the queue.

A_USURP_LOW 

A special signature for declaring methods. This is like A_GIMME, but the call is deferred to the back of the queue and multiple calls within one servicing of the queue are filtered down to one call.


Function Documentation

t_max_err atom_alloc ( long *  ac,
t_atom **  av,
char *  alloc 
)

Allocate a single atom.

If ac and av are both zero then memory is allocated. Otherwise it is presumed that memory is already allocated and nothing will happen.

Parameters:
ac The address of a variable that will contain the number of atoms allocated (1).
av The address of a pointer that will be set with the new allocated memory for the atom.
alloc Address of a variable that will be set true is memory is allocated, otherwise false.
Returns:
A Max error code.
t_max_err atom_alloc_array ( long  minsize,
long *  ac,
t_atom **  av,
char *  alloc 
)

Allocate an array of atoms.

If ac and av are both zero then memory is allocated. Otherwise it is presumed that memory is already allocated and nothing will happen.

Parameters:
minsize The minimum number of atoms that this array will need to contain. This determines the amount of memory allocated.
ac The address of a variable that will contain the number of atoms allocated.
av The address of a pointer that will be set with the new allocated memory for the atoms.
alloc Address of a variable that will be set true is memory is allocated, otherwise false.
Returns:
A Max error code.
long atom_arg_getdouble ( double *  c,
long  idx,
long  ac,
t_atom av 
)

Retrieves the floating point value, as a double, of a particular t_atom from an atom list, if the atom exists.

Parameters:
c Pointer to a double variable to receive the atom's data if the function is successful. Otherwise the value is left unchanged.
idx Offset into the atom list of the atom of interest, starting from 0. For instance, if you want data from the 3rd atom in the atom list, idx should be set to 2.
ac Count of av.
av Pointer to the first t_atom of an atom list.
Returns:
This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.
long atom_arg_getfloat ( float *  c,
long  idx,
long  ac,
t_atom av 
)

Retrieves the floating point value of a particular t_atom from an atom list, if the atom exists.

Parameters:
c Pointer to a float variable to receive the atom's data if the function is successful. Otherwise, the value is left unchanged.
idx Offset into the atom list of the atom of interest, starting from 0. For instance, if you want data from the 3rd atom in the atom list, idx should be set to 2.
ac Count of av.
av Pointer to the first t_atom of an atom list.
Returns:
This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.
long atom_arg_getlong ( long *  c,
long  idx,
long  ac,
t_atom av 
)

Retrieves the integer value of a particular t_atom from an atom list, if the atom exists.

Parameters:
c Pointer to a long variable to receive the atom's data if the function is successful.
idx Offset into the atom list of the atom of interest, starting from 0. For instance, if you want data from the 3rd atom in the atom list, idx should be set to 2.
ac Count of av.
av Pointer to the first t_atom of an atom list.
Returns:
This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.
Remarks:
The atom_arg_getlong() function only changes the value of c if the function is successful. For instance, the following code snippet illustrates a simple, but typical use:
    void myobject_mymessage(t_myobject *x, t_symbol *s, long ac, t_atom *av)
    {
        long var = -1;

        // here, we are expecting a value of 0 or greater
        atom_arg_getlong(&var, 0, ac, av);
        if (val == -1) // i.e. unchanged
            post("it is likely that the user did not provide a valid argument");
        else {
            ...
        }
    }
t_max_err atom_arg_getobjclass ( t_object **  x,
long  idx,
long  argc,
t_atom argv,
t_symbol cls 
)

Return a pointer to an object contained in an atom if it is of the specified class.

Parameters:
x The address of a pointer to the object contained in av if it is of the specified class upon return. Otherwise NULL upon return.
idx The index of the atom in the array from which to get the object pointer.
argc The count of atoms in argv.
argv The address to the first of an array of atoms.
cls A symbol containing the class name of which the object should be an instance.
Returns:
A Max error code.
long atom_arg_getsym ( t_symbol **  c,
long  idx,
long  ac,
t_atom av 
)

Retrieves the t_symbol * value of a particular t_atom from an atom list, if the atom exists.

Parameters:
c Pointer to a t_symbol * variable to receive the atom's data if the function is successful. Otherwise, the value is left unchanged.
idx Offset into the atom list of the atom of interest, starting from 0. For instance, if you want data from the 3rd atom in the atom list, idx should be set to 2.
ac Count of av.
av Pointer to the first t_atom of an atom list.
Returns:
This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.
Remarks:
The atom_arg_getsym() function only changes the value of c if the function is successful. For instance, the following code snippet illustrates a simple, but typical use:
    void myobject_open(t_myobject *x, t_symbol *s, long ac, t_atom *av)
    {
        t_symbol *filename = _sym_nothing;

        // here, we are expecting a file name.
        // if we don't get it, open a dialog box 
        atom_arg_getsym(&filename, 0, ac, av);
        if (filename == _sym_nothing) { // i.e. unchanged
            // open the file dialog box,
            // get a value for filename
        }
        // do something with the filename
    }
BEGIN_USING_C_LINKAGE void atom_copy ( short  argc1,
t_atom argv1,
t_atom argv2 
)

Copy an array of atoms.

Parameters:
argc1 The count of atoms in argv1.
argv1 The address to the first of an array of atoms that is the source for the copy.
argv2 The address to the first of an array of atoms that is the destination for the copy. Note that this array must already by allocated using sysmem_newptr() or atom_alloc().
t_max_err atom_getatom_array ( long  ac,
t_atom av,
long  count,
t_atom vals 
)

Fetch an array of t_atom values from an array of atoms.

Parameters:
ac The number of atoms allocated in the av parameter.
av The address to the first of an array of allocated atoms.
count The number of values to fetch from the array specified by vals.
vals The address of the array to which is copied the values from av.
Returns:
A Max error code.
t_max_err atom_getchar_array ( long  ac,
t_atom av,
long  count,
unsigned char *  vals 
)

Fetch an array of char values from an array of atoms.

Parameters:
ac The number of atoms allocated in the av parameter.
av The address to the first of an array of allocated atoms.
count The number of values to fetch from the array specified by vals.
vals The address of the array to which is copied the values from av.
Returns:
A Max error code.
long atom_getcharfix ( t_atom a  ) 

Retrieves an unsigned integer value between 0 and 255 from a t_atom.

Parameters:
a Pointer to a t_atom whose value is of interest
Returns:
This function returns the value of the specified t_atom as an integer between 0 and 255, if possible. Otherwise, it returns 0.
Remarks:
If the t_atom is typed A_LONG, but the data falls outside of the range 0-255, the data is truncated to that range before output.
If the t_atom is typed A_FLOAT, the floating point value is multiplied by 255. and truncated to the range 0-255 before output. For example, the floating point value 0.5 would be output from atom_getcharfix as 127 (0.5 * 255. = 127.5).
No attempt is also made to coerce t_symbol data.
t_max_err atom_getdouble_array ( long  ac,
t_atom av,
long  count,
double *  vals 
)

Fetch an array of 64bit float values from an array of atoms.

Parameters:
ac The number of atoms allocated in the av parameter.
av The address to the first of an array of allocated atoms.
count The number of values to fetch from the array specified by vals.
vals The address of the array to which is copied the values from av.
Returns:
A Max error code.
float atom_getfloat ( t_atom a  ) 

Retrieves a floating point value from a t_atom.

Parameters:
a Pointer to a t_atom whose value is of interest
Returns:
This function returns the value of the specified t_atom as a floating point number, if possible. Otherwise, it returns 0.
Remarks:
If the t_atom is not of the type specified by the function, the function will attempt to coerce a valid value from the t_atom. For instance, if the t_atom at is set to type A_LONG with a value of 5, the atom_getfloat() function will return the value of at as a float, or 5.0. An attempt is also made to coerce t_symbol data.
t_max_err atom_getfloat_array ( long  ac,
t_atom av,
long  count,
float *  vals 
)

Fetch an array of 32bit float values from an array of atoms.

Parameters:
ac The number of atoms allocated in the av parameter.
av The address to the first of an array of allocated atoms.
count The number of values to fetch from the array specified by vals.
vals The address of the array to which is copied the values from av.
Returns:
A Max error code.
t_max_err atom_getformat ( long  ac,
t_atom av,
char *  fmt,
  ... 
)

Retrieve values from an array of atoms using sscanf-like syntax.

atom_getformat() supports clfdsoaCLFDSOA tokens (primitive type scalars and arrays respectively for the char, long, float, double, t_symbol*, t_object*, t_atom*). It does not support vbp@ the tokens found in atom_setformat().

Parameters:
ac The number of atoms to parse in av.
av The address of the first t_atom pointer in an array to parse.
fmt An sscanf-style format string specifying types for the atoms.
... One or more arguments which are address of variables to be set according to the fmt string.
Returns:
A Max error code.
See also:
atom_setformat()
long atom_getlong ( t_atom a  ) 

Retrieves a long integer value from a t_atom.

Parameters:
a Pointer to a t_atom whose value is of interest
Returns:
This function returns the value of the specified t_atom as an integer, if possible. Otherwise, it returns 0.
Remarks:
If the t_atom is not of the type specified by the function, the function will attempt to coerce a valid value from the t_atom. For instance, if the t_atom at is set to type A_FLOAT with a value of 3.7, the atom_getlong() function will return the truncated integer value of at, or 3. An attempt is also made to coerce t_symbol data.
t_max_err atom_getlong_array ( long  ac,
t_atom av,
long  count,
long *  vals 
)

Fetch an array of long integer values from an array of atoms.

Parameters:
ac The number of atoms allocated in the av parameter.
av The address to the first of an array of allocated atoms.
count The number of values to fetch from the array specified by vals.
vals The address of the array to which is copied the values from av.
Returns:
A Max error code.
void* atom_getobj ( t_atom a  ) 

Retrieves a generic pointer value from a t_atom.

Parameters:
a Pointer to a t_atom whose value is of interest
Returns:
This function returns the value of the specified A_OBJ-typed t_atom, if possible. Otherwise, it returns NULL.
t_max_err atom_getobj_array ( long  ac,
t_atom av,
long  count,
t_object **  vals 
)

Fetch an array of t_object* values from an array of atoms.

Parameters:
ac The number of atoms allocated in the av parameter.
av The address to the first of an array of allocated atoms.
count The number of values to fetch from the array specified by vals.
vals The address of the array to which is copied the values from av.
Returns:
A Max error code.
void* atom_getobjclass ( t_atom av,
t_symbol cls 
)

Return a pointer to an object contained in an atom if it is of the specified class.

Parameters:
av A pointer to the atom from which to get the t_object.
cls A symbol containing the class name of which the object should be an instance.
Returns:
A pointer to the object contained in av if it is of the specified class, otherwise NULL.
t_symbol* atom_getsym ( t_atom a  ) 

Retrieves a t_symbol * value from a t_atom.

Parameters:
a Pointer to a t_atom whose value is of interest
Returns:
This function returns the value of the specified A_SYM-typed t_atom, if possible. Otherwise, it returns an empty, but valid, t_symbol *, equivalent to gensym(""), or _sym_nothing.
Remarks:
No attempt is made to coerce non-matching data types.
t_max_err atom_getsym_array ( long  ac,
t_atom av,
long  count,
t_symbol **  vals 
)

Fetch an array of t_symbol* values from an array of atoms.

Parameters:
ac The number of atoms allocated in the av parameter.
av The address to the first of an array of allocated atoms.
count The number of values to fetch from the array specified by vals.
vals The address of the array to which is copied the values from av.
Returns:
A Max error code.
t_max_err atom_gettext ( long  ac,
t_atom av,
long *  textsize,
char **  text,
long  flags 
)

Convert an array of atoms into a C-string.

Parameters:
ac The number of atoms to fetch in av.
av The address of the first t_atom pointer in an array to retrieve.
textsize The size of the string to which the atoms will be formatted and copied.
text The address of the string to which the text will be written.
flags Determines the rules by which atoms will be translated into text. Values are bit mask as defined by e_max_atom_gettext_flags.
Returns:
A Max error code.
See also:
atom_setparse()
long atom_gettype ( t_atom a  ) 

Retrieves type from a t_atom.

Parameters:
a Pointer to a t_atom whose type is of interest
Returns:
This function returns the type of the specified t_atom as defined in e_max_atomtypes
t_max_err atom_setatom_array ( long  ac,
t_atom av,
long  count,
t_atom vals 
)

Assign an array of t_atom values to an array of atoms.

Parameters:
ac The number of atoms to try to fetch from the second array of atoms. You should have at least this number of atoms allocated in av.
av The address to the first of an array of allocated atoms.
count The number of values in the array specified by vals.
vals The array from which to copy the values into the array of atoms at av.
Returns:
A Max error code.
t_max_err atom_setchar_array ( long  ac,
t_atom av,
long  count,
unsigned char *  vals 
)

Assign an array of char values to an array of atoms.

Parameters:
ac The number of atoms to try to fetch from the array of chars. You should have at least this number of atoms allocated in av.
av The address to the first of an array of allocated atoms.
count The number of values in the array specified by vals.
vals The array from which to copy the values into the array of atoms at av.
Returns:
A Max error code.
t_max_err atom_setdouble_array ( long  ac,
t_atom av,
long  count,
double *  vals 
)

Assign an array of 64bit float values to an array of atoms.

Parameters:
ac The number of atoms to try to fetch from the array of doubles. You should have at least this number of atoms allocated in av.
av The address to the first of an array of allocated atoms.
count The number of values in the array specified by vals.
vals The array from which to copy the values into the array of atoms at av.
Returns:
A Max error code.
t_max_err atom_setfloat ( t_atom a,
double  b 
)

Inserts a floating point number into a t_atom and change the t_atom's type to A_FLOAT.

Parameters:
a Pointer to a t_atom whose value and type will be modified
b Floating point value to copy into the t_atom
Returns:
This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.
t_max_err atom_setfloat_array ( long  ac,
t_atom av,
long  count,
float *  vals 
)

Assign an array of 32bit float values to an array of atoms.

Parameters:
ac The number of atoms to try to fetch from the array of floats. You should have at least this number of atoms allocated in av.
av The address to the first of an array of allocated atoms.
count The number of values in the array specified by vals.
vals The array from which to copy the values into the array of atoms at av.
Returns:
A Max error code.
t_max_err atom_setformat ( long *  ac,
t_atom **  av,
char *  fmt,
  ... 
)

Create an array of atoms populated with values using sprintf-like syntax.

atom_setformat() supports clfdsoaCLFDSOA tokens (primitive type scalars and arrays respectively for the char, long, float, double, t_symbol*, t_object*, t_atom*). It also supports vbp@ tokens (obval, binbuf, parsestr, attribute).

This function allocates memory for the atoms if the ac and av parameters are NULL. Otherwise it will attempt to use any memory already allocated to av. Any allocated memory should be freed with sysmem_freeptr().

Parameters:
ac The address of a variable to hold the number of returned atoms.
av The address of a t_atom pointer to which memory may be allocated and atoms copied.
fmt An sprintf-style format string specifying values for the atoms.
... One or more arguments which are to be substituted into the format string.
Returns:
A Max error code.
See also:
atom_getformat()
atom_setparse()
t_max_err atom_setlong ( t_atom a,
long  b 
)

Inserts an integer into a t_atom and change the t_atom's type to A_LONG.

Parameters:
a Pointer to a t_atom whose value and type will be modified
b Integer value to copy into the t_atom
Returns:
This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.
t_max_err atom_setlong_array ( long  ac,
t_atom av,
long  count,
long *  vals 
)

Assign an array of long integer values to an array of atoms.

Parameters:
ac The number of atoms to try to fetch from the array of longs. You should have at least this number of atoms allocated in av.
av The address to the first of an array of allocated atoms.
count The number of values in the array specified by vals.
vals The array from which to copy the values into the array of atoms at av.
Returns:
A Max error code.
t_max_err atom_setobj ( t_atom a,
void *  b 
)

Inserts a generic pointer value into a t_atom and change the t_atom's type to A_OBJ.

Parameters:
a Pointer to a t_atom whose value and type will be modified
b Pointer value to copy into the t_atom
Returns:
This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.
t_max_err atom_setobj_array ( long  ac,
t_atom av,
long  count,
t_object **  vals 
)

Assign an array of t_object* values to an array of atoms.

Parameters:
ac The number of atoms to try to fetch from the array of objects. You should have at least this number of atoms allocated in av.
av The address to the first of an array of allocated atoms.
count The number of values in the array specified by vals.
vals The array from which to copy the values into the array of atoms at av.
Returns:
A Max error code.
t_max_err atom_setparse ( long *  ac,
t_atom **  av,
char *  parsestr 
)

Parse a C-string into an array of atoms.

This function allocates memory for the atoms if the ac and av parameters are NULL. Otherwise it will attempt to use any memory already allocated to av. Any allocated memory should be freed with sysmem_freeptr().

Parameters:
ac The address of a variable to hold the number of returned atoms.
av The address of a t_atom pointer to which memory may be allocated and atoms copied.
parsestr The C-string to parse.
Returns:
A Max error code.
Remarks:
The following example will parse the string "foo bar 1 2 3.0" into an array of 5 atoms. The atom types will be determined automatically as 2 A_SYM atoms, 2 A_LONG atoms, and 1 A_FLOAT atom.
    t_atom *av =  NULL;
    long ac = 0;
    t_max_err err = MAX_ERR_NONE;
    
    err = atom_setparse(&ac, &av, "foo bar 1 2 3.0");
t_max_err atom_setsym ( t_atom a,
t_symbol b 
)

Inserts a t_symbol * into a t_atom and change the t_atom's type to A_SYM.

Parameters:
a Pointer to a t_atom whose value and type will be modified
b Pointer to a t_symbol to copy into the t_atom
Returns:
This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined in e_max_errorcodes if unsuccessful.
t_max_err atom_setsym_array ( long  ac,
t_atom av,
long  count,
t_symbol **  vals 
)

Assign an array of t_symbol* values to an array of atoms.

Parameters:
ac The number of atoms to try to fetch from the array of symbols. You should have at least this number of atoms allocated in av.
av The address to the first of an array of allocated atoms.
count The number of values in the array specified by vals.
vals The array from which to copy the values into the array of atoms at av.
Returns:
A Max error code.
long atomisatomarray ( t_atom a  ) 

Determines whether or not an atom represents a t_atomarray object.

Parameters:
a The address of the atom to test.
Returns:
Returns true if the t_atom contains a valid t_atomarray object.
long atomisdictionary ( t_atom a  ) 

Determines whether or not an atom represents a t_dictionary object.

Parameters:
a The address of the atom to test.
Returns:
Returns true if the t_atom contains a valid t_dictionary object.
long atomisstring ( t_atom a  ) 

Determines whether or not an atom represents a t_string object.

Parameters:
a The address of the atom to test.
Returns:
Returns true if the t_atom contains a valid t_string object.
void postargs ( short  argc,
t_atom argv 
)

Print the contents of an array of atoms to the Max window.

Parameters:
argc The count of atoms in argv.
argv The address to the first of an array of atoms.

Copyright © 2008, Cycling '74