使用頻度の高い 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拡張 |
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 の種別を判定して返す |
メンバ関数 | 機能 |
---|---|
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() | 複数のヘッダレコードの削除 |
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
をご覧ください.
fits_header &swap( fits_header &obj );
指定された
fits_header
オブジェクト
obj
の内容と自身の内容とを入れ替えます.
自身が
fits_hdu
オブジェクトの管理下にある場合,Data Unit に関係する
予約キーワード(BITPIX
等)を持つレコードは入れ替わりません.
ssize_t read_stream( cstreamio &sref );
オープン済みのストリーム
sref
から1つのHeader Unitを読み取ってパースし,
自身にその内容を格納します.
このメンバ関数の実行終了後,ストリームの位置は続くData Unitの 先頭にセットされます.
ストリーム
sref
には,
cstreamioクラスの継承クラス
のいずれかを指定してください.
ssize_t read_buffer( const char *buffer );
文字列バッファから Header Unit を読み込みます.
ssize_t skip_data_stream( cstreamio &sref );
自身が保持しているヘッダ情報に基づき,
オープン済みのストリーム
sref
において
1つのData Unitを読み飛ばします.
このメンバ関数を使う前に,あらかじめ
read_stream()メンバ関数
によりオブジェクトにFITSヘッダの情報を与えておく必要があります.
このメンバ関数が終了した時点でのストリームの位置は, HDUが続く場合は次のHeader Unitの先頭にセットされます. なお,HDUが続くかどうかは次に呼ばれる read_stream() メンバ関数の返り値で判定します.
ストリーム
sref
には,
cstreamioクラスの継承クラス
のいずれかを指定してください.
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クラスの継承クラス
のいずれかを指定してください.
fits_header &reformat();
各 fits_header_record オブジェクトが現在保持している 80文字(×n)のフォーマット済み文字列を, 現在のキーワード,値,コメントの内容から作りなおします.
const char *formatted_string();
ヘッダの全レコードについて, FITSファイル出力時のフォーマット済み文字列を オブジェクト内部に作成し,そのアドレスを返します.
返される文字列は、
改行を含まない
'\0'
で終端される80×nキャラクタの文字列であり、
ロング値は
CONTINUE
キーワードによって分割された形に整形されます。
WCSLIB や WCSToolsのlibwcs と連携する時に使うと便利です.
size_t formatted_length();
全ヘッダレコードのフォーマット済み文字列(80×n文字)の長さを返します.
END
キーワードを含むレコード,空白80文字によるレコードは
含まれません.'\0'
は長さに含まれません.
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()関数 で行なう事ができます.
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()関数 で行なう事ができます.
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では例外を発生します.
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
にセットします.
キーワードが見つからない場合は,負の数を返します.
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
など)のヘッダレコードは
検索対象になりません.
long value_length( const char *keyword ) const; long value_length( long index ) const;
キーワード
keyword
またはレコード番号
index
に対応するヘッダレコードが持つ,生の文字列値の長さを取得します.
キーワードおよび値の存在チェックに使用できるメンバ関数です.
'
」を含む)の長さbool is_sysrecord( long index ) const;
Data Unit に関係する予約キーワード(BITPIX 等)かどうかを返します.
long length() const;
ヘッダのレコード数を返します.
返されるレコード数には,END
キーワードレコードは含まれません.
CONTINUE
を使った複数レコードにまたがる長いヘッダ値
については,
複数レコードにまたがるヘッダ値を展開した後のレコード数(CONTINUE
はカウントせず)です.
int hdutype() const;
ヘッダの情報から HDUの種別 を判定して返します.
HDU種別が判定できる場合は
FITS::IMAGE_HDU
,
FITS::ASCII_TABLE_HDU
,
FITS::BINARY_TABLE_HDU
,
のいずれかを返し,できない場合は
FITS::ANY_HDU
を返します.
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とも, 記述型レコードを更新,追加する事はできません.
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
に
"'ABC'"
のようにセットします.
レコードタイプを数字や論理値にする場合は,value
に
"256"
,"3.14"
,"T"
のようにセットします.
value
とdescription
に文字列長の制限はありません
(複数レコードにまたがる長いヘッダ値,コメント文字列に対するCONTINUEキーワードの適用を参照).
ヘッダレコードが80文字以内に収まらない場合でも,
それぞれ適切な方法でファイルに保存されます.
fits::header_def
の定義については,
ヘッダレコードを定義するための型(構造体)
または
fits.h
をご覧ください.
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
などの形式)で挿入します.
ヘッダのレコードタイプを文字列としたい場合は,value
に
"'ABC'"
のようにセットします.
レコードタイプを数字や論理値にする場合は,value
に
"256"
,"3.14"
,"T"
のようにセットします.
value
とdescription
に文字列長の制限はありません
(複数レコードにまたがる長いヘッダ値,コメント文字列に対するCONTINUEキーワードの適用を参照).
ヘッダレコードが80文字以内に収まらない場合でも,
それぞれ適切な方法でファイルに保存されます.
fits::header_def
の定義については,
ヘッダレコードを定義するための型(構造体)
または
fits.h
をご覧ください.
fits_header &rename( long index0, const char *new_name ); fits_header &rename( const char *keyword0, const char *new_name );
index0
またはkeyword0
で指定された
ヘッダレコードのキーワードを
new_name
で指定されたものに変更します.
fits_header &erase( long index ); fits_header &erase( const char *keyword );
index
または
keyword
で指定された1つのヘッダレコードを削除します.
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
で指定されたヘッダレコードを,
続く引数で指定された内容に更新します.
ヘッダのレコードタイプを文字列としたい場合は,value
に
"'ABC'"
のようにセットします.
レコードタイプを数字や論理値にする場合は,value
に
"256"
,"3.14"
,"T"
のようにセットします.
value
とdescription
に文字列長の制限はありません
(複数レコードにまたがる長いヘッダ値,コメント文字列に対するCONTINUEキーワードの適用を参照).
ヘッダレコードが80文字以内に収まらない場合でも,
それぞれ適切な方法でファイルに保存されます.
fits::header_def
の定義については,
ヘッダレコードを定義するための型(構造体)
または
fits.h
をご覧ください.
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文字以内に収まらない場合でも, それぞれ適切な方法でファイルに保存されます.
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文字以内に収まらない場合でも, それぞれ適切な方法でファイルに保存されます.
fits_header &update_records( const fits_header &obj );
fits_headerオブジェクト
obj
が持つキーワード1つ1つを自身のヘッダから探し,
キーワードが存在しない場合は追加し,同一のキーワードが存在する場合は
obj
が持つ内容で上書きします.
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
をご覧ください.
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
をご覧ください.
fits_header &erase_records( long index0, long num_records ); fits_header &erase_records( const char *keyword0, long num_records );
index0
あるいはkeyword0
で指定されたレコードから,
num_records
個のヘッダレコードを削除します.