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_symbol *	atom_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

enum e_max_atom_gettext_flags

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

Definition at line 1692 of file ext_obex_util.h.

enum e_max_atomtypes

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.

Definition at line 202 of file ext_mess.h.

---

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.

Referenced by db_open().

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.

Referenced by jit_qt_movie_read_typed().

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.

Referenced by db_open().

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.