Max 5 API Reference
00001 00002 #ifndef __ATOMARRAY_H__ 00003 #define __ATOMARRAY_H__ 00004 00005 #if C74_PRAGMA_STRUCT_PACKPUSH 00006 #pragma pack(push, 2) 00007 #elif C74_PRAGMA_STRUCT_PACK 00008 #pragma pack(2) 00009 #endif 00010 00011 00012 /** The atomarray object. This struct is provided for debugging convenience, 00013 but should be considered opaque and is subject to change without notice. 00014 00015 @ingroup atomarray 00016 */ 00017 typedef struct _atomarray 00018 { 00019 t_object ob; 00020 long ac; 00021 t_atom *av; 00022 } t_atomarray; 00023 00024 00025 #if C74_PRAGMA_STRUCT_PACKPUSH 00026 #pragma pack(pop) 00027 #elif C74_PRAGMA_STRUCT_PACK 00028 #pragma pack() 00029 #endif 00030 00031 #ifdef __cplusplus 00032 extern "C" { 00033 #endif // __cplusplus 00034 00035 00036 /** 00037 Create a new atomarray object. 00038 Note that atoms provided to this function will be <em>copied</em>. The copies stored internally to the atomarray instance. 00039 You can free the atomarray by calling object_free(). 00040 00041 @ingroup atomarray 00042 @param ac The number of atoms to be initially contained in the atomarray. 00043 @param av A pointer to the first of an array of atoms to initially copy into the atomarray. 00044 @return Pointer to the new atomarray object. 00045 00046 @remark Note that due to the unusual prototype of this method that you cannot instantiate this object using the 00047 object_new_typed() function. If you wish to use the dynamically bound creator to instantiate the object, 00048 you should instead should use object_new() as demonstrated below. The primary reason that you might choose 00049 to instantiate an atomarray using object_new() instead of atomarray_new() is for using the atomarray object 00050 in code that is also intended to run in Max 4. 00051 @code 00052 object_new(CLASS_NOBOX, gensym("atomarray"), argc, argv); 00053 @endcode 00054 00055 @see atomarray_duplicate() 00056 */ 00057 t_atomarray *atomarray_new(long ac, t_atom *av); 00058 00059 00060 /** 00061 Replace the existing array contents with a new set of atoms 00062 Note that atoms provided to this function will be <em>copied</em>. The copies stored internally to the atomarray instance. 00063 00064 @ingroup atomarray 00065 00066 @param x The atomarray instance. 00067 @param ac The number of atoms to be initially contained in the atomarray. 00068 @param av A pointer to the first of an array of atoms to initially copy into the atomarray. 00069 @return A Max error code. 00070 */ 00071 t_max_err atomarray_setatoms(t_atomarray *x, long ac, t_atom *av); 00072 00073 00074 /** 00075 Retrieve a pointer to the first atom in the internal array of atoms. 00076 This method does not copy the atoms, btu simply provides access to them. 00077 To retrieve a copy of the atoms use atomarray_copyatoms(). 00078 00079 @ingroup atomarray 00080 00081 @param x The atomarray instance. 00082 @param ac The address of a long where the number of atoms will be set. 00083 @param av The address of a #t_atom pointer where the address of the first atom of the array will be set. 00084 @return A Max error code. 00085 00086 @see atomarray_copyatoms() 00087 */ 00088 t_max_err atomarray_getatoms(t_atomarray *x, long *ac, t_atom **av); 00089 00090 00091 /** 00092 Retrieve a copy of the atoms in the array. 00093 This method does not copy the atoms, btu simply provides access to them. 00094 To retrieve a copy of the atoms use atomarray_copyatoms(). 00095 00096 @ingroup atomarray 00097 00098 @param x The atomarray instance. 00099 @param ac The address of a long where the number of atoms will be set. 00100 @param av The address of a #t_atom pointer where the atoms will be allocated and copied. 00101 @return A Max error code. 00102 00103 @remark You are responsible for freeing memory allocated for the copy of the atoms returned. 00104 @code 00105 long ac = 0; 00106 t_atom *av = NULL; 00107 00108 atomarray_copyatoms(anAtomarray, &ac, &av); 00109 if(ac && av){ 00110 // do something with ac and av here... 00111 sysmem_freeptr(av); 00112 } 00113 @endcode 00114 00115 @see atomarray_getatoms() 00116 */ 00117 t_max_err atomarray_copyatoms(t_atomarray *x, long *ac, t_atom **av); 00118 00119 00120 /** 00121 Return the number of atoms in the array. 00122 00123 @ingroup atomarray 00124 @param x The atomarray instance. 00125 @return The number of atoms in the array. 00126 */ 00127 long atomarray_getsize(t_atomarray *x); 00128 00129 00130 /** 00131 Copy an a specific atom from the array. 00132 00133 @ingroup atomarray 00134 @param x The atomarray instance. 00135 @param index The zero-based index into the array from which to retrieve an atom pointer. 00136 @param av The address of an atom to contain the copy. 00137 @return A Max error code. 00138 00139 @remark Example: 00140 @code 00141 { 00142 t_atom a; 00143 00144 // fetch a copy of the second atom in a previously existing array 00145 atomarray_getindex(anAtomarray, 1, &a); 00146 // do something with the atom here... 00147 } 00148 @endcode 00149 */ 00150 t_max_err atomarray_getindex(t_atomarray *x, long index, t_atom *av); 00151 00152 00153 /** 00154 Create a new atomarray object which is a copy of another atomarray object. 00155 00156 @ingroup atomarray 00157 @param x The atomarray instance which is to be copied. 00158 @return A new atomarray which is copied from x. 00159 00160 @see atomarray_new() 00161 */ 00162 void *atomarray_duplicate(t_atomarray *x); 00163 00164 00165 /** 00166 Copy a new atom onto the end of the array. 00167 00168 @ingroup atomarray 00169 @param x The atomarray instance. 00170 @param a A pointer to the new atom to append to the end of the array. 00171 00172 @see atomarray_appendatoms() 00173 @see atomarray_setatoms() 00174 */ 00175 void atomarray_appendatom(t_atomarray *x, t_atom *a); 00176 00177 00178 /** 00179 Copy multiple new atoms onto the end of the array. 00180 00181 @ingroup atomarray 00182 @param x The atomarray instance. 00183 @param ac The number of new atoms to be appended to the array. 00184 @param av A pointer to the first of the new atoms to append to the end of the array. 00185 00186 @see atomarray_appendatom() 00187 @see atomarray_setatoms() 00188 */ 00189 void atomarray_appendatoms(t_atomarray *x, long ac, t_atom *av); 00190 00191 00192 /** 00193 Remove an atom from any location within the array. 00194 The array will be resized and collapsed to fill in the gap. 00195 00196 @ingroup atomarray 00197 @param x The atomarray instance. 00198 @param index The zero-based index of the atom to remove from the array. 00199 */ 00200 void atomarray_chuckindex(t_atomarray *x, long index); 00201 00202 00203 /** 00204 Clear the array. Frees all of the atoms and sets the size to zero. 00205 This function does not perform a 'deep' free, meaning that any #A_OBJ atoms will not have their object's freed. 00206 Only the references to those objects contained in the atomarray will be freed. 00207 00208 @ingroup atomarray 00209 @param x The atomarray instance. 00210 @return The number of atoms in the array. 00211 */ 00212 void atomarray_clear(t_atomarray *x); 00213 00214 00215 /** 00216 Call the specified function for every item in the atom array. 00217 00218 @ingroup atomarray 00219 @param x The atomarray instance. 00220 @param fun The function to call, specified as function pointer cast to a Max #method. 00221 @param arg An argument that you would like to pass to the function being called. 00222 @return A max error code. 00223 00224 @remark The atomarray_funall() method will call your function for every item in the list. 00225 It will pass both a pointer to the item in the list, and any argument that you 00226 provide. The following example shows a function that could be called by hashtab_funall(). 00227 @code 00228 void myFun(t_atom *a, void *myArg) 00229 { 00230 // do something with a and myArg here 00231 // a is the atom in the atom array 00232 } 00233 @endcode 00234 00235 @see linklist_funall() 00236 @see hashtab_funall() 00237 */ 00238 void atomarray_funall(t_atomarray *x, method fun, void *arg); 00239 00240 00241 #ifdef __cplusplus 00242 } 00243 #endif // __cplusplus 00244 00245 #endif // __ATOMARRAY_H__
Copyright © 2008, Cycling '74