Atom ユーティリティ

"ext_obex.c" はまた、t_atom の値の get や set のために使う、いくつかの新しい atom ユーティリティを提供しています。t_atom への直接のアクセスは引き続きサポートされますが、多くの開発者はこれらのユーティリティがより簡潔で、安全であることがわかるでしょう。

atom_setlong

     
  整数の値を t_atom に挿入し、t_atom の型を A_LONGに変更するために、atom_setlong 関数を使います。
   
  t_max_err atom_setlong(t_atom *a, long b);
     
  a 値と型を修正される t_atom へのポインタ
  b t_atom にコピーされる整数の値
     
 

このルーチンは、成功するとエラーコード MAX_ERR_NONE を返し、失敗した場合には“ext_obex.h”で定義される他のエラーコードの1つを返します。


atom_setfloat

     
  浮動小数点の値を t_atom に挿入し、t_atom の型を A_FLOATに変更するために、atom_setfloat 関数を使います。
   
  t_max_err atom_setfloat(t_atom *a, double b);
     
  a 値と型を修正される t_atom へのポインタ
  b t_atom にコピーされる浮動小数点の値
     
 

このルーチンは、成功するとエラーコード MAX_ERR_NONEを返し、失敗した場合には“ext_obex.h”で定義される他のエラーコードの1つを返します。


atom_setsym

     
  t_symbol *を t_atom に挿入し、t_atom の型を A_SYMに変更するために、atom_setsym 関数を使います。
   
  t_max_err atom_setsym(t_atom *a, t_symbol *b);
     
  a 値と型を修正される t_atom へのポインタ
  b t_atom にコピーされる t_symbol へのポインタ
     
 

このルーチンは、成功するとエラーコード MAX_ERR_NONEを返し、失敗した場合には“ext_obex.h”で定義される他のエラーコードの1つを返します。


atom_setobj

     
  汎用のポインタの値を t_atom に挿入し、t_atom の型を A_OBJに変更するために、atom_setobj 関数を使います。
   
  t_max_err atom_setobj(t_atom *a, void *b);
     
  a 値と型を修正される t_atom へのポインタ
  b t_atom にコピーされるポインタの値
     
 

このルーチンは、成功するとエラーコード MAX_ERR_NONEを返し、失敗した場合には“ext_obex.h”で定義される他のエラーコードの1つを返します。


atom_getlong

     
  t_atom から long 整数の値を取得するために、atom_getlong 関数を使います。
   
  long atom_getlong(t_atom *a);
     
  a 値を取得される t_atom へのポインタ
     
 

このルーチンは、可能であれば指定された t_atom の値を、整数として返します。そうでない場合、0を返します。

t_atom が、関数で指定された型でない場合、このルーチンは、t_atom からの有効な値を強制的に型変換しようとします。例えば、t_atom atの値が 3.7、型が A_FLOATにセットされている場合、atom_getlong 関数は、 at の小数点以下を切り捨てられた整数(int)の値 3 を返します。このルーチンは、t_symbol データも強制型変換しようとします。


atom_getfloat

     
  t_atom から 浮動小数点数の値を取得するために、atom_getfloat 関数を使います。
   
  float atom_getfloat(t_atom *a);
     
  a 値を取得される t_atom へのポインタ
     
 

このルーチンは、可能であれば指定された t_atom の値を、浮動小数点数として返します。そうでない場合、0を返します。t_atom が、関数で指定された型でない場合、このルーチンは、t_atom からの有効な値を強制的に型変換しようとします。例えば、t_atom atの値が 5、型 が A_LONGにセットされている場合、 atom_getfloat 関数は、at の値を 浮動小数点数 (float) として、または 5.0 を返します。このルーチンは、t_symbol データも強制的に型変換しようとします。


atom_getsym

     
  t_atom から t_symbol * の値を取得するために、atom_getsym 関数を使います。
   
  t_symbol *atom_getsym(t_atom *a);
     
  a 値を取得される t_atom へのポインタ
     
 

このルーチンは、可能であれば指定された A_SYM型 のt_atom の値を返します。そうでない場合、 gensym("") 、あるいは_sym_nothing と同じような、有効な t_symbol * として空の値を返します。データ型が合わない場合、強制的な型変換を行なおうとはしません。


atom_getobj

     
  t_atom から 一般的なポインタの値を取得するために、atom_getobj 関数を使います。
   
  void *atom_getobj(t_atom *a);
     
  a 値を取得される t_atom へのポインタ
     
 

このルーチンは、可能であれば指定された A_OBJ型 のt_atom の値を返します。そうでない場合、NULL を返します。データ型が合わない場合、強制的な型変換を行なおうとはしません。


atom_getcharfix

     
  t_atom から、 0〜255 の符号なし整数(unsigned integer)の値をを取得するために、atom_getcharfix 関数を使います。
   
  long atom_getcharfix(t_atom *a);
     
  a 値を取得される t_atom へのポインタ
     
 

このルーチンは、可能であれば、指定された t_atom の値を 0〜255 の間の整数値として返します。そうでない場合 0 を返します。t_atom が long 型で、そのデータが 0〜255 の範囲を超えてしまう場合には、データはこの範囲内に切り捨てられてから出力されます。t_atom が float 型の場合、浮動小数点数の値は255を掛けられ、その後、0〜255 の範囲に切り捨てられてから出力されます。例えば、浮動小数点数 0.5 は、127 ( 0.5* 255.) として、atom_getcharfix から出力されます。t_symbol データの場合は、強制的な型変換を行なおうとはしません。


atom_arg_getlong

     
  atom が存在する場合、atom リストから、特定の t_atom の整数値を取得するために atom_arg_getlong 関数を使います。
   
  t_max_err atom_arg_getlong(long *c, long idx, long ac, t_atom *av);
     
  c この関数が成功した場合に、atom のデータを取得するための long 変数へのポインタ。
  idx atom のリストの中での、対象となる atom のオフセット。0 から始まります。例えば、atom リストの3番目の atom からのデータが欲しい場合、idx は2にセットされなければなりません。
  ac avの数
  av atomリストの最初の t_atom へのポインタ
     
 

このルーチンは、成功するとエラーコード MAX_ERR_NONEを返し、失敗した場合には“ext_obex.h”で定義される他のエラーコードの1つを返します。

関数が成功した場合、atom_arg_getlong 関数は c の値を変更するだけです。例えば、次のコードの断片は、シンプルな、しかし典型的な使用の例を示しています。

void myobject_mymessage(t_myobject *x, t_symbol *s, long ac, t_atom *av) { long var = -1; // ここに, 0 またはそれ以上の値が期待されます 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 { ... } }


atom_arg_getfloat

     
  atom が存在する場合、atom リストから、特定の t_atom の浮動小数点数の値を取得するために atom_arg_getfloat 関数を使います。
   
  t_max_err atom_arg_getfloat(float *c, long idx, long ac, t_atom *av);
     
  c この関数が成功した場合に、atom のデータを取得するための float 変数へのポインタ。そうでない場合は、この値は変更されないままです。
  idx atom のリストの中での、対象となる atom のオフセット。0 から始まります。例えば、atom リストの3番目の atom からのデータが欲しい場合、idx は2にセットされなければなりません。
  ac avの数
  av atomリストの最初の t_atom へのポインタ
     
 

このルーチンは、成功するとエラーコード MAX_ERR_NONE を返し、失敗した場合には“ext_obex.h”で定義される他のエラーコードの1つを返します。


atom_arg_getdouble

     
  atom が存在する場合、atom リストから、特定の t_atom の浮動小数点数の値を double として取得するために atom_arg_getdouble 関数を使います。
   
  t_max_err atom_arg_getdouble(double *c, long idx, long ac, t_atom *av);
     
  c この関数が成功した場合に、 atom のデータを取得するための double 変数へのポインタ。そうでない場合は、この値は変更されないままです。
  idx atom のリストの中での、対象となる atom のオフセット。0 から始まります。例えば、atom リストの3番目の atom からのデータが欲しい場合、idx は2にセットされなければなりません。
  ac avの数
  av atomリストの最初の t_atom へのポインタ
     
 

このルーチンは、成功するとエラーコード MAX_ERR_NONEを返し、失敗した場合には“ext_obex.h”で定義される他のエラーコードの1つを返します。


atom_arg_getsym

     
  atom が存在する場合、atom リストから、特定の t_atom の t_symbol * を取得するために atom_arg_getsym 関数を使います。
   
  t_max_err atom_arg_getsym(t_symbol **c, long idx, long ac, t_atom *av);
     
  c この関数が成功した場合に、atom のデータを取得するためのt_symbol * 変数へのポインタ。そうでない場合は、この値は変更されないままです。
  idx atom のリストの中での、対象となる atom のオフセット。0 から始まります。例えば、atom リストの3番目の atom からのデータが欲しい場合、idx は2にセットされなければなりません。
  ac avの数
  av atomリストの最初の t_atom へのポインタ
     
 

このルーチンは、成功するとエラーコード MAX_ERR_NONE を返し、失敗した場合には“ext_obex.h”で定義される他のエラーコードの1つを返します。

関数が成功した場合、atom_arg_getsym 関数は c の値を変更するだけです。例えば、次のコードの断片は、シンプルな、しかし典型的な使用の例を示しています。

void myobject_open(t_myobject *x, t_symbol *s, long ac, t_atom *av) { t_symbol *filename = _sym_nothing; // ここに、ファイル名が期待されます。 // 取得できない場合は、ダイアログボックスを開きます。 atom_arg_getsym(&filename, 0, ac, av); if (filename == _sym_nothing) { // 変更されない場合 // ファイルダイアログボックスを開きます // ファイル名として値を取得 } // ファイル名を使って何かを行ないます }