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

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

SLLIB クラス:	ストリーム / 文字列 / 文字列配列 / 文字列連想配列 / 多次元配列
SLLIB クラス用関数:	多次元配列用の統計用関数 / 多次元配列用の数学関数 / 多次元配列用の複素関数
SLLIB クラス以外:	定数・型の定義 / C99互換の複素数・複素関数
SFITSIO クラス:	fitscc / fits_hdu / fits_image / fits_table / fits_table_col / fits_header / fits_header_record
SFITSIO クラス以外:	関数 / 定数・型の定義 / FITSファイルの部分読み出し機能 / FITSテンプレート / 規約外FITS拡張

SFITSIO: fits_headerクラス

fits_headerクラスは，Header Unit を表現します．オブジェクト内で， fits_header_recordクラス(1つのヘッダレコードを表現) のオブジェクトを管理します．

ディスク I/O のための public なメンバ関数を持ち，オープンされたストリームを使って Header Unit だけの読み書き，Data Unit の読み飛ばしが可能です．

クラス	ヘッダファイル	コード	namespace
fits_header	`#include <sli/fits_header.h>`	cc	sli

SFITSIO に搭載されているヘッダのコメント辞書については， fits_header_record.cc の最初の部分をご覧ください．

メンバ関数一覧

ヘッダ全体の操作に関するメンバ関数:

メンバ関数	機能
init()	オブジェクトの初期化・コピー
swap()	2つのオブジェクト間での内容のスワップ
read_stream()	オープンされたストリームから Header Unit を読み込む
read_buffer()	文字列バッファから Header Unit を読み込む
skip_data_stream()	ストリームにアクセスし，自身が持つヘッダの内容に基づいて Data Unit を読み飛ばす
write_stream()	ストリームへの Header Unit の書き込み
reformat()	全ヘッダレコードの再フォーマットを行なう
formatted_string()	全ヘッダレコードのフォーマット済み文字列(80×n文字)を取得
formatted_length()	全ヘッダレコードのフォーマット済み文字列(80×n文字)の長さを取得
fill_blank_comments()	コメントが存在しない場合，現在のヘッダコメント辞書の内容で埋める
assign_default_comments()	コメントの存在にかかわらず，現在のヘッダコメント辞書の内容で埋める

ヘッダ情報のための基本的なメンバ関数:

メンバ関数	機能
at(), at_cs()	fits_header_recordオブジェクトへの参照を取得
index()	キーワードに対応するヘッダレコード番号を取得
regmatch()	POSIX拡張正規表現でキーワードを(連続的に)検索
value_length()	キーワードに対応する生の文字列値の長さを取得 (存在チェックに使用可)
is_sysrecord()	Data Unit に関係する予約キーワード(BITPIX 等)かどうかを返す
length()	ヘッダレコードの長さを取得
hdutype()	ヘッダの情報から HDU の種別を判定して返す

1つのヘッダレコードを操作するメンバ関数:

メンバ関数	機能
update()	1つのヘッダレコードを追加，更新
append()	1つのヘッダレコードを追加
insert()	1つのヘッダレコードを挿入
rename()	1つのヘッダキーワード名の変更
erase()	1つのヘッダレコードの消去
assign()	1つのヘッダレコードを更新
assignf_value()	1つのヘッダレコードの値を更新 (printf()の記法)
assignf_comment()	1つのヘッダレコードのコメントを更新 (printf()の記法)

複数のヘッダレコードを操作するメンバ関数:

メンバ関数	機能
update_records()	複数のヘッダレコードの追加，更新
append_records()	複数のヘッダレコードの追加
insert_records()	複数のヘッダレコードの挿入
erase_records()	複数のヘッダレコードの削除

ヘッダ全体の操作に関するメンバ関数

init()

fits_header &init();
fits_header &init( const fits::header_def defs[] );
fits_header &init( const fits_header &obj );

ヘッダを消去し，defs または obj が指定された場合はその内容をヘッダにセットします．配列 defs[] の最終要素のメンバはすべて NULL でなければなりません．

fits::header_defの定義については，ヘッダレコードを定義するための型(構造体) または fits.h をご覧ください．

返り値: 自身の参照

swap()

fits_header &swap( fits_header &obj );

指定された fits_header オブジェクト obj の内容と自身の内容とを入れ替えます．

自身が fits_hdu オブジェクトの管理下にある場合，Data Unit に関係する予約キーワード(BITPIX等)を持つレコードは入れ替わりません．

返り値: 自身の参照

read_stream()

ssize_t read_stream( cstreamio &sref );

オープン済みのストリーム sref から1つのHeader Unitを読み取ってパースし，自身にその内容を格納します．

このメンバ関数の実行終了後，ストリームの位置は続くData Unitの先頭にセットされます．

ストリーム sref には， cstreamioクラスの継承クラスのいずれかを指定してください．

返り値: 正の値: ストリームから読み取られたバイト数
ゼロ: FITSファイルのストリームが終了した場合
負の値(エラー): ストリームの操作に失敗した場合

read_buffer()

ssize_t read_buffer( const char *buffer );

文字列バッファから Header Unit を読み込みます．

返り値: 非負値: 読み込んだバイト数
負値: エラー

skip_data_stream()

ssize_t skip_data_stream( cstreamio &sref );

自身が保持しているヘッダ情報に基づき，オープン済みのストリーム sref において 1つのData Unitを読み飛ばします．このメンバ関数を使う前に，あらかじめ read_stream()メンバ関数によりオブジェクトにFITSヘッダの情報を与えておく必要があります．

このメンバ関数が終了した時点でのストリームの位置は， HDUが続く場合は次のHeader Unitの先頭にセットされます．なお，HDUが続くかどうかは次に呼ばれる read_stream() メンバ関数の返り値で判定します．

ストリーム sref には， cstreamioクラスの継承クラスのいずれかを指定してください．

返り値: 非負の値: ストリームから読み取られたバイト数
負の値(エラー): ストリームの操作に失敗した場合

write_stream()

ssize_t write_stream( cstreamio &sref, bool end_and_blank = false );

オープン済みのストリーム sref に対し，自身の内容をFITS規約に従った形式(横80文字の改行なしテキスト)で出力します．

引数 end_and_blank が true の場合， ENDキーワードと空白文字によるパディングが追加されるので，このメンバ関数の終了後にストリームに対して続けて出力する事で， Data Unitを先頭から書き込む事ができます．

引数 end_and_blank が false の場合は，ENDキーワード以降は出力されません．

ストリーム sref には， cstreamioクラスの継承クラスのいずれかを指定してください．

返り値: 非負の値: ストリームに書き出されたバイト数
負の値(エラー): ストリームの操作に失敗した場合

reformat()

fits_header &reformat();

各 fits_header_record オブジェクトが現在保持している 80文字(×n)のフォーマット済み文字列を，現在のキーワード，値，コメントの内容から作りなおします．

返り値: 自身の参照

formatted_string()

const char *formatted_string();

ヘッダの全レコードについて， FITSファイル出力時のフォーマット済み文字列をオブジェクト内部に作成し，そのアドレスを返します．

返される文字列は、改行を含まない '\0' で終端される80×nキャラクタの文字列であり、ロング値は CONTINUEキーワードによって分割された形に整形されます。

WCSLIB や WCSToolsのlibwcs と連携する時に使うと便利です．

返り値: フォーマット済み文字列のアドレス

formatted_length()

size_t formatted_length();

全ヘッダレコードのフォーマット済み文字列(80×n文字)の長さを返します．

ENDキーワードを含むレコード，空白80文字によるレコードは含まれません．'\0' は長さに含まれません．

fill_blank_comments()

fits_header &fill_blank_comments( int hdutype = FITS::ANY_HDU );

全ヘッダレコード(ただし記述型レコードを除く)からコメントがセットされていないものを調べ， SFITSIOが持つコメント辞書に該当するキーワードがあればその内容でコメント文をセットします．このコメント辞書は，各HDUタイプ専用の辞書が3つ，汎用の辞書が1つから構成され，どれを使うかは引数 hdutype で指定します(辞書の内容はfits_header_record.ccの最初のあたりをご覧ください)．なお，それぞれのHDU専用の辞書にキーワードが存在しない場合は，汎用のコメント辞書が使われます．

引数として指定できるのは， FITS::IMAGE_HDU， FITS::BINARY_TABLE_HDU， FITS::ASCII_TABLE_HDU， FITS::ANY_HDU，のいずれかで， FITS::ANY_HDU が指定された場合と引数を省略した場合は，HDUのタイプをヘッダの内容から自動判定します．

コメント辞書の変更は， fits::update_comment_dictionary()関数で行なう事ができます．

返り値: 自身の参照

assign_default_comments()

fits_header &assign_default_comments( int hdutype = FITS::ANY_HDU );

全ヘッダレコード(ただし記述型レコードを除く)を調べ， SFITSIOが持つコメント辞書に該当するキーワードがあればその内容でコメント文をセット(上書き)します．このコメント辞書は，各HDUタイプ専用の辞書が3つ，汎用の辞書が1つから構成され，どれを使うかは引数 hdutype で指定します(辞書の内容はfits_header_record.ccの最初のあたりをご覧ください)．なお，それぞれのHDU専用の辞書にキーワードが存在しない場合は，汎用のコメント辞書が使われます．

引数として指定できるのは， FITS::IMAGE_HDU， FITS::BINARY_TABLE_HDU， FITS::ASCII_TABLE_HDU， FITS::ANY_HDU，のいずれかで，FITS::ANY_HDUが指定された場合と引数を省略した場合は，HDUのタイプをヘッダの内容から自動判定します．

コメント辞書の変更は， fits::update_comment_dictionary()関数で行なう事ができます．

返り値: 自身の参照

ヘッダ情報のための基本的なメンバ関数

at()

fits_header_record &at( long index0 );                          ... 1
fits_header_record &at( const char *keyword0 );                 ... 2
const fits_header_record &at( long index0 ) const;              ... 3
const fits_header_record &at( const char *keyword0 ) const;     ... 4
const fits_header_record &at_cs( long index0 ) const;           ... 5
const fits_header_record &at_cs( const char *keyword0 ) const;  ... 6

ヘッダレコード番号 index0 またはヘッダキーワード名 keyword0 に対応する内部 fits_header_record オブジェクトへの参照を返します．メンバ関数3～6は読み取り専用です．

これらのメンバ関数で取得した fits_header_record オブジェクトへの参照を経由し， 1つのヘッダレコード情報にアクセスします．

指定されたヘッダレコードが存在しない場合，メンバ関数1～2では新規ヘッダレコードが作られ，メンバ関数3～6では例外を発生します．

返り値: 内部 fits_header_record オブジェクトへの参照

index()

long index( const char *keyword0 ) const;                       ... 1
long index( const char *keyword0, bool is_description ) const;  ... 2

メンバ関数1は，記述形式 (COMMENTやHISTORYなど) ではないレコードからキーワードkeywordを探してそのレコード番号を返します．

記述形式のレコードのみから探す場合，メンバ関数2を使い，is_descriptionを true にセットします．

キーワードが見つからない場合は，負の数を返します．

regmatch()

long regmatch( const char *keypat, 
               ssize_t *rpos = NULL, size_t *rlen = NULL ) const;
long regmatch( long index, const char *keypat, 
               ssize_t *rpos = NULL, size_t *rlen = NULL ) const;

index で示されたレコードから順に POSIX拡張正規表現 keypat にマッチするキーワードを探し，そのレコード番号を返します．マッチするものが見つからない場合は，負の数を返します．index が指定されない場合は，最初のレコードから検索します．

*rpos には見つかった文字の位置を， *rlen にはマッチした文字列の長さを返します．これらの引数は与えなくてもかまいません．

このメンバ関数では，記述形式(COMMENTやHISTORYなど)のヘッダレコードは検索対象になりません．

value_length()

long value_length( const char *keyword ) const;
long value_length( long index ) const;

キーワード keyword またはレコード番号 index に対応するヘッダレコードが持つ，生の文字列値の長さを取得します．

キーワードおよび値の存在チェックに使用できるメンバ関数です．

返り値: 正の値: 生の文字列値(「'」を含む)の長さ
0: 値が存在しない場合
負の値: キーワードが存在しない場合

is_sysrecord()

bool is_sysrecord( long index ) const;

Data Unit に関係する予約キーワード(BITPIX 等)かどうかを返します．

length()

long length() const;

ヘッダのレコード数を返します．

返されるレコード数には，END キーワードレコードは含まれません． CONTINUEを使った複数レコードにまたがる長いヘッダ値については，複数レコードにまたがるヘッダ値を展開した後のレコード数(CONTINUEはカウントせず)です．

hdutype()

int hdutype() const;

ヘッダの情報から HDUの種別を判定して返します．

HDU種別が判定できる場合は FITS::IMAGE_HDU， FITS::ASCII_TABLE_HDU， FITS::BINARY_TABLE_HDU，のいずれかを返し，できない場合は FITS::ANY_HDU を返します．

1つのヘッダレコードを操作するメンバ関数

update()

fits_header &update( const char *keyword, const char *value, 
                     const char *comment );                   ... 1
fits_header &update( const fits_header_record &obj );         ... 2

メンバ関数1では， keywordで指定されたヘッダレコードを，生の値をvalueで，コメントをcommentで更新します．更新が不要な場合，valueかcommentのどちらかに NULLを与えます． keywordがヘッダに見つからない場合は追加します．

ヘッダのレコードタイプを文字列としたい場合は，value に "'ABC'" のようにセットします．レコードタイプを数字や論理値にする場合は，valueに "256"，"3.14"，"T" のようにセットします．

メンバ関数2では， fits_header_record オブジェクト obj が持つキーワードを自身のヘッダレコードから探し，存在すれば値とコメントを更新し，そうでなければ新規レコードを追加します．

メンバ関数1，2とも，記述型レコードを更新，追加する事はできません．

返り値: 自身の参照

append()

fits_header &append( const char *keyword );
fits_header &append( const char *keyword, const char *value, 
                     const char *comment );
fits_header &append( const char *keyword, const char *description );
fits_header &append( const fits::header_def &def );
fits_header &append( const fits_header_record &obj );

キーワードkeyword，値value，コメントcommentの1つのヘッダレコードを追加します． descriptionが指定された場合は，記述形式(COMMENTやHISTORYなどの形式)で追加します．

valueとdescriptionに文字列長の制限はありません (複数レコードにまたがる長いヘッダ値，コメント文字列に対するCONTINUEキーワードの適用を参照)．ヘッダレコードが80文字以内に収まらない場合でも，それぞれ適切な方法でファイルに保存されます．

fits::header_defの定義については，ヘッダレコードを定義するための型(構造体) または fits.h をご覧ください．

返り値: 自身の参照

insert()

fits_header &insert( long index0, const char *keyword );
fits_header &insert( const char *keyword0, const char *keyword );
fits_header &insert( long index0,
                     const char *keyword, const char *value, const char *comment );
fits_header &insert( const char *keyword0,
                     const char *keyword, const char *value, const char *comment );
fits_header &insert( long index0, 
                     const char *keyword, const char *description );
fits_header &insert( const char *keyword0, 
                     const char *keyword, const char *description );
fits_header &insert( long index0, const fits::header_def &def );
fits_header &insert( const char *keyword0, const fits::header_def &def );
fits_header &insert( long index0, const fits_header_record &obj );
fits_header &insert( const char *keyword0, const fits_header_record &obj );

index0またはkeyword0で指定された位置に，キーワードkeyword，値value，コメントcommentの1つのヘッダレコードを挿入します． descriptionが指定された場合は，記述形式(COMMENTやHISTORYなどの形式)で挿入します．

fits::header_defの定義については，ヘッダレコードを定義するための型(構造体) または fits.h をご覧ください．

返り値: 自身の参照

rename()

fits_header &rename( long index0, const char *new_name );
fits_header &rename( const char *keyword0, const char *new_name );

index0またはkeyword0で指定されたヘッダレコードのキーワードを new_nameで指定されたものに変更します．

返り値: 自身の参照

erase()

fits_header &erase( long index );
fits_header &erase( const char *keyword );

index または keyword で指定された1つのヘッダレコードを削除します．

返り値: 自身の参照

assign()

fits_header &assign( long index0, const fits::header_def &def );
fits_header &assign( const char *keyword0, const fits::header_def &def );
fits_header &assign( long index0, const fits_header_record &obj );
fits_header &assign( const char *keyword0, const fits_header_record &obj );
fits_header &assign( long index0, 
                     const char *keyword, const char *value, const char *comment );
fits_header &assign( const char *keyword0, 
                     const char *keyword, const char *value, const char *comment );
fits_header &assign( long index0, const char *keyword, const char *description );
fits_header &assign( const char *keyword0, 
                     const char *keyword, const char *description );

index0 または keyword0 で指定されたヘッダレコードを，続く引数で指定された内容に更新します．

fits::header_defの定義については，ヘッダレコードを定義するための型(構造体) または fits.h をご覧ください．

返り値: 自身の参照

assignf_value()

fits_header &assignf_value( long index0, const char *format, ... );
fits_header &assignf_value( const char *keyword0, const char *format, ... );

index0 または keyword0 で指定されたヘッダレコードの値に，続く可変引数で指定された値をセットします． format以降の引数は，libcの printf()のそれと同様に指定します．

ヘッダのレコードタイプを文字列としたい場合は，値に "'ABC'" のようにセットします．レコードタイプを数字や論理値にする場合は，値に"256"，"3.14"，"T" のようにセットします．

値に文字列長の制限はありません (複数レコードにまたがる長いヘッダ値を参照)．ヘッダレコードが80文字以内に収まらない場合でも，それぞれ適切な方法でファイルに保存されます．

返り値: 自身の参照

assignf_comment()

fits_header &assignf_comment( long index0, const char *format, ... );
fits_header &assignf_comment( const char *keyword0, const char *format, ... );

index0 または keyword0 で指定されたヘッダレコードのコメントに，続く可変引数で指定された文字列をセットします． format以降の引数は，libcの printf()のそれと同様に指定します．

コメントに文字列長の制限はありません (コメント文字列に対するCONTINUEキーワードの適用を参照)．ヘッダレコードが80文字以内に収まらない場合でも，それぞれ適切な方法でファイルに保存されます．

返り値: 自身の参照

複数のヘッダレコードを操作するメンバ関数

update_records()

fits_header &update_records( const fits_header &obj );

fits_headerオブジェクト obj が持つキーワード1つ1つを自身のヘッダから探し，キーワードが存在しない場合は追加し，同一のキーワードが存在する場合は objが持つ内容で上書きします．

返り値: 自身の参照

append_records()

fits_header &append_records( const fits::header_def defs[] );
fits_header &append_records( const fits::header_def defs[], long num_defs );
fits_header &append_records( const fits_header &obj );

defs で指定された内容，または fits_headerオブジェクト obj が持つ内容を，自身のヘッダレコードを追加します．

引数 num_defs を指定しない場合は，配列 defs[] の最終要素のメンバはすべて NULL でなければなりません．

fits::header_defの定義については，ヘッダレコードを定義するための型(構造体) または fits.h をご覧ください．

返り値: 自身の参照

insert_records()

fits_header &insert_records( long index0, const fits::header_def defs[] );
fits_header &insert_records( long index0, 
                             const fits::header_def defs[], long num_defs );
fits_header &insert_records( const char *keyword0,
                             const fits::header_def defs[] );
fits_header &insert_records( const char *keyword0,
                             const fits::header_def defs[], long num_defs );
fits_header &insert_records( long index0, const fits_header &obj );
fits_header &insert_records( const char *keyword0, const fits_header &obj );

自身のヘッダレコードの index0またはkeyword0で指定された位置に， defs で指定された内容，または fits_headerオブジェクト obj が持つ内容を挿入します．

引数 num_defs を指定しない場合は，配列 defs[] の最終要素のメンバはすべて NULL でなければなりません．

fits::header_defの定義については，ヘッダレコードを定義するための型(構造体) または fits.h をご覧ください．

返り値: 自身の参照

erase_records()

fits_header &erase_records( long index0, long num_records );
fits_header &erase_records( const char *keyword0, long num_records );

index0あるいはkeyword0で指定されたレコードから， num_records個のヘッダレコードを削除します．

返り値: 自身の参照