SLLIB + SFITSIO ダイジェスト版 HTML マニュアル

使用頻度の高い API について，主要な内容を記述した， ビギナー向けのリファレンスマニュアルです．

SFITSIO: fits_tableクラス

fits_tableクラスは，ASCII Table HDU または Binary Table HDU を表現します． fits_hduクラス を継承し，オブジェクト内で fits_headerクラス(FITSヘッダ全体を表現)， fits_table_colクラス(テーブルのカラムを表現) mdarrayクラス(バイナリテーブルのヒープ) のオブジェクトを管理します．

HDUやヘッダに関するメンバ関数

fits_table &init();
fits_table &init( const fits_table &obj );
fits_table &init( const fits::table_def defs[] );

ヘッダとテーブルの内容を初期化します．

obj が指定された場合は，その内容をコピーします． defs が指定されば場合には，それに従って カラムを作成します．

配列 defs[] の最終要素のメンバはすべて NULL でなければなりません．

fits::table_defの定義については， バイナリテーブル・ASCIIテーブルを定義するための型(構造体) または fits.h をご覧ください．

返り値

自身の参照

fits_table &swap( fits_table &obj );

自身と obj との中身を交換します．

返り値

自身の参照

void copy( fits_table *dest ) const;

自身の内容を dest で示されたオブジェクトにコピーします．

fits_table &ascii_to_binary();

当該テーブルがアスキーテーブルの属性となっていた場合， 属性をバイナリテーブルに変換します．

属性をバイナリテーブルにすると， FITSファイル上のアスキーテーブルの TFORMn の値(fits::table_def構造体の tdispメンバの値)は， バイナリテーブルとして保存される時には TFORMn のコメント部分に保存されます．

TNULLn の値も，TNULLn のコメント部分に保存されます(値は未定義となります)．

返り値

自身の参照

カラム情報用ヘッダレコードの操作に関するメンバ関数

fits_header_record &col_header( const char *col_name, const char *kwd );
fits_header_record &col_header( long col_index, const char *kwd );
const fits_header_record &col_header( const char *col_name, 
                                      const char *kwd ) const;
const fits_header_record &col_header( long col_index, 
                                      const char *kwd ) const;
const fits_header_record &col_header_cs( const char *col_name, 
                                         const char *kwd ) const;
const fits_header_record &col_header_cs( long col_index, 
                                         const char *kwd ) const;

kwd で指定されたカラムキーワードの プレフィックス(例: TTYPE)を持つヘッダレコードのうち， col_index あるいは col_name で示されたカラムに対応するヘッダレコードオブジェクトへの参照を返します．

.col_header() に続くメンバ関数として， .svalue()， .dvalue()， .lvalue() 等が使えます． これらについては， fits_header_recordクラス を参照してください．

返り値

内部 fits_header_record オブジェクトへの参照

long col_header_index( const char *col_name, const char *kwd ) const;
long col_header_index( long col_index, const char *kwd ) const;

kwd で指定されたカラムキーワードのプレフィックス (例: TTYPE)を持つヘッダレコードのうち， col_index あるいは col_name で示されたカラムに対応するヘッダレコードの番号を返します．

fits_table &update_col_header( const char *col_name, 
                               const char *kwd, const char *val, const char *com );
fits_table &update_col_header( long col_index, 
                               const char *kwd, const char *val, const char *com );

kwd で指定されたカラムキーワードのプレフィックス (例: TTYPE)を持つヘッダレコードのうち， col_index あるいは col_name で示されたカラムに対応するヘッダレコードを更新し， 同時にオブジェクト内部の管理情報も更新します．

返り値

自身の参照

fits_table &erase_col_header( const char *col_name, const char *kwd );
fits_table &erase_col_header( long col_index, const char *kwd );

kwd で指定されたカラムキーワードの プレフィックス(例: TTYPE)を持つヘッダレコードのうち， col_index あるいは col_name で示されたカラムに対応するヘッダレコードを削除します． 同時にオブジェクト内部の管理情報も更新します．

返り値

自身の参照

fits_table &rename_col_header( const char *old_kwd, const char *new_kwd );

ユーザ定義のカラム用ヘッダレコードのキーワードプレフィックス (ヘッダの TXFLDKWD の値(csv形式)に保存されている文字列値) の1つを， old_kwd から new_kwd へ名前を変更します． FITS規約で定められたキーワード(TTYPE等)については 変更できません．

返り値

自身の参照

fits_table &sort_col_header();

すべてのカラム用ヘッダレコードを，カラム順にソートします．

返り値

自身の参照

const char *const *user_col_keywords() const;        ... 1
const tarray_tstring &user_col_keywords_cs() const;  ... 2

メンバ関数1は，ユーザ定義のカラムキーワードのポインタ配列(読み取り専用)を返します．

メンバ関数2は， ユーザ定義のカラムキーワードを保存している文字列配列オブジェクトの参照(読み取り専用)を返します．

返される文字列配列には， ヘッダの TXFLDKWD の値(csv形式)に保存される文字列が格納されています．

bool is_user_col_keyword( const char *kwd ) const;

引数のキーワードがユーザ定義のカラムキーワードかどうか (ヘッダの TXFLDKWD の値(csv形式)に存在するか) を返します．

fits_table &append_a_user_col_keyword( const char *kwd );

ユーザ定義のカラムキーワード(TLMAX，TLMIN等)を1つ追加します． 指定されたキーワードプレフィックスは ヘッダの TXFLDKWD の値(csv形式)に追加されます．

fits_table &erase_a_user_col_keyword( const char *kwd );

ユーザ定義のカラムキーワード(TLMAX，TLMIN等)を1つ削除します． 指定されたキーワードプレフィックスは ヘッダの TXFLDKWD の値(csv形式)から削除されます．

カラム(列)の操作に関するメンバ関数

fits_table_col &col( long col_index );                        ... 1
fits_table_col &col( const char *col_name );                  ... 2
fits_table_col &colf( const char *fmt, ... );                 ... 3
const fits_table_col &col( long col_index ) const;            ... 4
const fits_table_col &col( const char *col_name ) const;      ... 5
const fits_table_col &colf( const char *fmt, ... ) const;     ... 6
const fits_table_col &col_cs( long col_index ) const;         ... 7
const fits_table_col &col_cs( const char *col_name ) const;   ... 8
const fits_table_col &colf_cs( const char *fmt, ... ) const;  ... 9

カラム番号 col_index または カラム名 col_name に対応する内部 fits_table_col オブジェクトへの参照を返します． メンバ関数4〜9は読み取り専用です．

取得した fits_table_col オブジェクトへの参照を経由し， テーブルのカラムデータへアクセスします．

指定されたカラムが存在しない場合， メンバ関数1〜3では 新規カラムが作られ，メンバ関数4〜9では例外を発生します．

返り値

内部 fits_table_col オブジェクトへの参照

long col_index( const char *col_name ) const;

col_name で指定されたカラムの番号を返します．

const char *col_name( long col_index ) const;

col_index で指定されたカラムの名前を返します．

long col_length() const;

テーブルのカラム数を返します．

fits_table &assign_col_name( long col_index, const char *newname );
fits_table &assign_col_name( const char *col_name, const char *newname );

col_index あるいは col_name で示されたカラムの名前を newname に設定します．

返り値

自身の参照

fits_table &assign_null_svalue( const char *snull );

内部 fits_table_colオブジェクトの svalue()， assign( const char * ) で使用するNULL文字列値を設定します．

デフォルトでは， svalue() と assign( const char * ) では "NULL" がヌル文字列として 使用されますが， このメンバ関数を使う事でヌル文字列を変更する事ができます．

返り値

自身の参照

fits_table &append_cols( const fits::table_def defs[] );
fits_table &append_cols( const fits_table &src );

テーブルに(複数の)カラムを追加します．

defs が指定された場合には，それに従ってカラムを追加します． 配列 defs[] の最終要素のメンバはすべて NULL でなければなりません．

srcが指定された場合は， srcの持つカラムの定義だけでなくデータ領域もコピーされますが， 自身の行数が十分でない場合はすべての行がコピーされません．

fits::table_defの定義については， バイナリテーブル・ASCIIテーブルを定義するための型(構造体) または fits.h をご覧ください．

返り値

自身の参照

fits_table &insert_cols( long index, const fits::table_def defs[] );
fits_table &insert_cols( const char *col_name, const fits::table_def defs[] );
fits_table &insert_cols( long index, const fits_table &src );
fits_table &insert_cols( const char *col_name, const fits_table &src );

index あるいは col_name で指定されたカラムの前に，(複数の)カラムを挿入します．

defs が指定された場合には，それに従ってカラムを挿入します． 配列 defs[] の最終要素のメンバはすべて NULL でなければなりません．

srcが指定された場合は， srcの持つカラムの定義だけでなくデータ領域もコピーされますが， 自身の行数が十分でない場合はすべての行がコピーされません．

fits::table_defの定義については， バイナリテーブル・ASCIIテーブルを定義するための型(構造体) または fits.h をご覧ください．

返り値

自身の参照

fits_table &erase_cols( long index, long num_cols );
fits_table &erase_cols( const char *col_name, long num_cols );

index あるいは col_name で指定されたカラムから num_cols 個のカラム群を消去します．

返り値

自身の参照

fits_table &swap_cols( long index0, long num_cols, long index1 );
fits_table &swap_cols( const char *col_name0, long num_cols, const char *col_name1 );

index0あるいは col_name0で指定されたカラムから num_cols個のカラム群を， index1あるいは col_name1で指定されたカラムから num_cols個のカラム群と入れ替えます．

num_colsによって，2つのカラム群が重なる場合は， num_colsの値を減らして入れ替えを行ないます．

返り値

自身の参照

fits_table &append_a_col( const fits::table_def &def );
fits_table &append_a_col( const fits_table_col &src );

テーブルに1つのカラムを追加します．

def が指定された場合には，それに従ってカラムを追加します．

srcが指定された場合は， srcの持つカラムの定義だけでなくデータ領域もコピーされますが， 自身の行数が十分でない場合はすべての行がコピーされません．

fits::table_defの定義については， バイナリテーブル・ASCIIテーブルを定義するための型(構造体) または fits.h をご覧ください．

返り値

自身の参照

fits_table &insert_a_col( long col_index, const fits::table_def &def );
fits_table &insert_a_col( const char *col_name, const fits::table_def &def );
fits_table &insert_a_col( long col_index, const fits_table_col &src );
fits_table &insert_a_col( const char *col_name, const fits_table_col &src );

col_index あるいは col_name で指定されたカラムの前に，1つのカラムを挿入します．

def が指定された場合には，それに従ってカラムを挿入します．

srcが指定された場合は， srcの持つカラムの定義だけでなくデータ領域もコピーされますが， 自身の行数が十分でない場合はすべての行がコピーされません．

fits::table_defの定義については， バイナリテーブル・ASCIIテーブルを定義するための型(構造体) または fits.h をご覧ください．

返り値

自身の参照

fits_table &erase_a_col( long col_index );
fits_table &erase_a_col( const char *col_name );

col_index あるいは col_name で指定された 1つのカラムを消去します．

返り値

自身の参照

fits_table &put_a_col( long col_index, const fits_table_col &src );
fits_table &put_a_col( const char *col_name, const fits_table_col &src );

col_index あるいは col_name で指定されたカラムを src の持つカラムの定義で上書きし，セル値をコピーします．

自身の行数が十分でない場合はすべての行がコピーされません．

返り値

自身の参照

fits_table &define_a_col( long col_index, const fits::table_def &def );
fits_table &define_a_col( const char *col_name, const fits::table_def &def );

col_index あるいは col_name で指定されたカラムの定義を変更します．

def で行なうカラム設定のうち，変更したくない項目については， def のメンバに NULL を代入します．

fits::table_defの定義については， バイナリテーブル・ASCIIテーブルを定義するための型(構造体) または fits.h をご覧ください．

返り値

自身の参照

ロウ(行)の操作に関するメンバ関数

long row_length() const;

テーブルの行数を返します．

fits_table &resize_rows( long num_rows );

テーブルの行数を num_rows 行に変更します．

返り値

自身の参照

fits_table &append_rows( long num_rows );

テーブルの最後に， num_rows 個の新しい行を追加します．

新しいセルには，デフォルト値がセットされます． デフォルト値の初期設定値は， 論理型の場合は 'F'， 文字列型の場合は ' ' からなる文字列， その他の型の場合は 0 です． デフォルト値は assign_default() メンバ関数で変更できます．

返り値

自身の参照

fits_table &insert_rows( long index, long num_rows );

index で指定された行の直前に， num_rows 個の新しい行を挿入します．

新しいセルには，デフォルト値がセットされます． デフォルト値の初期設定値は， 論理型の場合は 'F'， 文字列型の場合は ' ' からなる文字列， その他の型の場合は 0 です． デフォルト値は assign_default() メンバ関数で変更できます．

返り値

自身の参照

fits_table &erase_rows( long index, long num_rows );

index で指定された行から num_rows 個の行を削除します．

返り値

自身の参照

fits_table &clean_rows();
fits_table &clean_rows( long row_index, long num_rows );

すべてのカラムにおいて， index で指定された行から num_rows 個の行をデフォルト値にします． 引数が指定されない場合は，すべての行が対象です．

fits_table &move_rows( long src_index, long num_rows, long dest_index );

fits_table &swap_rows( long index0, long num_rows, long index1 );

fits_table &flip_rows( long index, long num_rows );

fits_table &import_rows( long dest_index, bool match_by_name,
                         const fits_table &from, 
                         long idx_begin = 0, long num_rows = FITS::ALL );

size_t heap_length();

fits_table &resize_heap( size_t sz );

ssize_t get_heap( void *dest_buf, size_t buf_size ) const;
ssize_t get_heap( long offset, void *dest_buf, size_t buf_size ) const;

ssize_t put_heap( const void *src_buf, size_t buf_size );
ssize_t put_heap( long offset, const void *src_buf, size_t buf_size );

fits_table &reverse_heap_endian( long offset, int type, long length );

void *heap_ptr();
const void *heap_ptr() const;
const void *heap_ptr_cs() const;

const mdarray &heap_array_cs() const;

long long reserved_area_length() const;

fits_table &resize_reserved_area( long long val );