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

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

SLLIB: 文字列配列 (tarray_tstringクラス)

tarray_tstring は文字列配列を扱うためのクラスで，tstring クラスと同様， スクリプト言語のような強力な文字列処理用 API を提供します． tarray_tstring のオブジェクト内では， tstringクラス のオブジェクト配列 が管理されており，各要素の参照を引き出す事で，tstring クラスの メンバ関数も使用可能です． 配列用バッファはほぼ完全な自動管理であり， 配列に対するアドレスを使う事がほとんど無く高い安全性を確保します． 下記のような機能を持ちます．

• ほぼ完全な文字列バッファの自動管理 (自動確保・自動拡張・自動開放)
• 要素単位のアクセス
• 値のセット，追加，挿入等で printf() の記法が使える API
• 文字列のデリミタでの分割
• 左右の空白，改行文字の除去
• 基本的な文字・文字列の検索
• シェル風の文字列マッチ
• 正規表現による検索，置換，後方参照情報の取得
• 要素文字列に対するポインタ配列の取得 など

tarray_tstring クラスは単独のクラスです．継承関係はありません．

基本機能のためのメンバ関数

tstring &operator[]( size_t index );              ... 1
const tstring &operator[]( size_t index ) const;  ... 2

添え字で指定された配列要素(tstringクラスのオブジェクト) の参照を返します．

index (0-indexed) に配列長以上の値を指定した場合， メンバ関数1では配列の長さが自動拡張されますが， メンバ関数2では例外が発生します．

返り値

指定された位置にある配列要素(tstringクラスのオブジェクト)の参照

tarray_tstring &operator=(const tarray_tstring &obj);       ... 1
const char *const *operator=(const char *const *elements);  ... 2

演算子の右側(引数)で指定されたオブジェクトの内容または文字列配列を 自身に代入します.

引数 elements には， NULL で終端している文字列のポインタ配列のアドレスを与えます．

返り値

自身の参照 (メンバ関数1)
内部文字列バッファへのポインタ配列 (メンバ関数2)

size_t length( size_t index ) const;

配列の長さ(個数)を返します．

const char *const *cstrarray() const;

tstring &at( size_t index );
const tstring &at( size_t index ) const;
const tstring &at_cs( size_t index ) const;

void dprint( const char *msg = NULL ) const;

自身のオブジェクト情報を標準エラー出力へ出力します． 引数 msg を指定すると，オブジェクト情報と同時に msg の内容を表示します．

ssize_t copy( size_t index, size_t n, tarray_tstring *dest ) const;
ssize_t copy( size_t index, tarray_tstring *dest ) const;
ssize_t copy( tarray_tstring *dest ) const;

tarray_tstring &swap( tarray_tstring &sobj );

tarray_tstring &init();
tarray_tstring &init(const tarray_tstring &obj);

tarray_tstring &assign( const char *str, size_t n );
tarray_tstring &assign( const tstring &one, size_t n );
tarray_tstring &assignf( size_t n, const char *format, ... );

tarray_tstring &assign( const char *const *elements );
tarray_tstring &assign( const char *const *elements, size_t n );
tarray_tstring &assign( const tarray_tstring &src, size_t idx2 = 0 );
tarray_tstring &assign( const tarray_tstring &src, size_t idx2, size_t n2 );
tarray_tstring &assign( const char *el0, const char *el1, ... );

文字列の内容を元に，文字列配列をセットするためのメンバ関数

tarray_tstring &explode( const char *src_str, const char *delim, bool zero_str );
tarray_tstring &explode( const char *src_str, const char *delim, bool zero_str,
                         const char *quot_bkt, int escape, bool rm_escape );

tarray_tstring &split( const char *src_str, const char *delims, bool zero_str );
tarray_tstring &split( const char *src_str, const char *delims, bool zero_str, 
                       const char *quotations, int escape, bool rm_escape );

文字列 src_str を区切り文字で分割し， その結果を文字列配列として自身へ代入します． 区切り文字は、文字リストとして delims で与え， " \t" のような単純な文字リストに加え， 正規表現で用いられる "[A-Z]" あるいは "[^A-Z]" のような指定が可能です．さらに， "[…]" の中では，文字クラスが指定できます．

分割後の要素として，ゼロの文字列長を許すかどうかを， zero_str で指定できます． zero_str が false の場合， 文字列長 0 の要素の作成を許可しません． zero_str が true の場合， 文字列長 0 の要素の作成を許可します(csv形式の場合などに使います)． zero_str の指定がない場合は，false の扱いとなります．

クォーテーション等の「特定の文字」および括弧で囲まれた文字列は分割しない場合， quotations に「特定の文字」を指定します． たとえば，シングルクォーテーションと丸括弧で囲まれた文字列を 分割対象外とする場合は， "'()" と指定します． 括弧として扱う事ができるのは，"[]{}<>()" の4種類です．

エスケープ文字は escape で指定します． 分割後のエスケープ文字を削除する場合は， rm_escape を true にセットします． ただし，quotations で指定された文字で囲まれた部分の エスケープ文字は削除しません．

返り値

自身の参照

tarray_tstring &regassign( const char *src_str, const char *pat );    ... 1
tarray_tstring &regassign( const char *src_str, size_t pos,
                           const char *pat );                         ... 2
tarray_tstring &regassign( const char *src_str, size_t pos,
                           const char *pat, size_t *nextpos );        ... 3
tarray_tstring &regassign( const char *src_str, const tregex &pat );  ... 4
tarray_tstring &regassign( const char *src_str, size_t pos,
                           const tregex &pat );                       ... 5
tarray_tstring &regassign( const char *src_str, size_t pos,
                           const tregex &pat, size_t *nextpos );      ... 6

文字列 src_str対し，pat で指定された POSIX拡張正規表現(以下，正規表現)による文字列マッチを試行し， マッチした場合は，マッチした部分全体および 後方参照されるべき部分文字列を，文字列配列として自身に 格納します(配列の長さは1以上になります)． マッチしなかった場合や正規表現に誤りがある等 の原因で処理にエラーが発生した場合は， 自身の配列が初期化されて何も代入されません (配列の長さが0になります)．

マッチした部分の位置は，reg_posメンバ関数で得る事 ができます．プロトタイプは次のとおりです．

size_t reg_pos( size_t idx ) const;

引数 idx には，0から始まる要素番号を指定します． 要素番号0 の要素には，マッチした文字列全体の情報が格納され， 要素番号1 からは，正規表現「(...)」それぞれにマッチした 部分文字列の情報が格納されます(つまり，後方参照のための情報です)．

メンバ関数1〜3の場合，正規表現 pat をコンパイルし， その結果を自身が持つ内部バッファに保存し，マッチを行ないます pat が前回と同じ場合は，再コンパイルしません)． 正規表現のコンパイルに失敗すると， 標準エラー出力にその内容を出力します．

メンバ関数4〜6の場合，正規表現のコンパイル結果を保持 している tregexクラスのオブジェクトを指定します． したがって，regassign()メンバ関数を使う前に， あらかじめ tregexクラスのcompile()メンバ関数で 正規表現をコンパイルする必要があります．

pos が指定されない場合は， 文字列src_str の左端からマッチを試行しますが， 指定された場合は， 文字列src_str の位置 pos からマッチを試行します． 文字列マッチが試行される対象範囲は， 文字列終端の '\0' が現れるまでです (改行文字 '\n' が現れても処理は終了しません)．

連続して文字や文字列を検索する場合に， nextpos を使って， 次の呼び出しで pos に与えるべき値を得る事ができます． nextpos の指す変数には， マッチした場合はその位置からさらに マッチした部分の長さ分(マッチした部分の長さが0の場合は1文字分) だけ右方向に移動させた位置が， マッチしなかった場合には文字列 src_str の長さ+1が 返ります． nextpos が不要な場合は，NULLを与える事もできます．

正規表現の詳細は， tstringクラスのregmatch()の解説 を参照してください．

返り値

自身の参照

配列の編集のためのメンバ関数

tarray_tstring &put( size_t index, const char *str, size_t n );
tarray_tstring &put( size_t index, const tstring &one, size_t n );
tarray_tstring &putf( size_t index, size_t n, const char *format, ... );

tarray_tstring &put( size_t index, const char *const *elements );
tarray_tstring &put( size_t index, const char *const *elements, size_t n );
tarray_tstring &put( size_t index, const tarray_tstring &src, size_t idx2 = 0 );
tarray_tstring &put( size_t index, const tarray_tstring &src, size_t idx2, size_t n2 );
tarray_tstring &put( size_t index, const char *el0, const char *el1, ... );

tarray_tstring &append( const char *str, size_t n );
tarray_tstring &append( const tstring &one, size_t n );
tarray_tstring &appendf( size_t n, const char *format, ... );

tarray_tstring &append( const char *const *elements );
tarray_tstring &append( const char *const *elements, size_t n );
tarray_tstring &append( const tarray_tstring &src, size_t idx2 = 0 );
tarray_tstring &append( const tarray_tstring &src, size_t idx2, size_t n2 );
tarray_tstring &append( const char *el0, const char *el1, ... );

tarray_tstring &insert( size_t index, const char *const *elements );
tarray_tstring &insert( size_t index, const char *const *elements, size_t n );
tarray_tstring &insert( size_t index, const tarray_tstring &src, size_t idx2 = 0 );
tarray_tstring &insert( size_t index, const tarray_tstring &src, size_t idx2, size_t n2 );
tarray_tstring &insert( size_t index, const char *el0, const char *el1, ... );

tarray_tstring &insert( size_t index, const char *str, size_t n );
tarray_tstring &insert( size_t index, const tstring &one, size_t n );
tarray_tstring &insertf( size_t index, size_t n, const char *format, ... );

tarray_tstring &replace( size_t idx1, size_t n1, const char *str, size_t n2 );
tarray_tstring &replace( size_t idx1, size_t n1, const tstring &one, size_t n2 );
tarray_tstring &replacef( size_t idx1, size_t n1, size_t n2,
                          const char *format, ... );

tarray_tstring &replace( size_t idx1, size_t n1, const char *const *elements );
tarray_tstring &replace( size_t idx1, size_t n1, const char *const *elements, size_t n2 );
tarray_tstring &replace( size_t idx1, size_t n1,
                         const tarray_tstring &src, size_t idx2 = 0 );
tarray_tstring &replace( size_t idx1, size_t n1,
                         const tarray_tstring &src, size_t idx2, size_t n2 );
tarray_tstring &replace( size_t idx1, size_t n1, 
                         const char *el0, const char *el1, ... );

tarray_tstring &erase();
tarray_tstring &erase( size_t index, size_t num_elements = 1 );

tarray_tstring &clean(const char *str = "");

tarray_tstring &resize( size_t new_num_elements );

tarray_tstring &resizeby( ssize_t len );

tarray_tstring &crop( size_t idx, size_t len );
tarray_tstring &crop( size_t idx );

全配列要素に対する編集のためのメンバ関数

tarray_tstring &chomp( const char *rs = "\n" );

tarray_tstring &trim( const char *side_spaces = " \t\n\r\f\v" );
tarray_tstring &trim( int side_space );

tarray_tstring &ltrim( const char *side_spaces = " \t\n\r\f\v" );
tarray_tstring &ltrim( int side_space );

tarray_tstring &rtrim( const char *side_spaces = " \t\n\r\f\v" );
tarray_tstring &rtrim( int side_space );

tarray_tstring &strreplace( const char *org_str, const char *new_str,
                            bool all = false );

tarray_tstring &regreplace( const char *pat, 
                            const char *new_str, bool all = false );
tarray_tstring &regreplace( const tregex &pat, 
                            const char *new_str, bool all = false );

tarray_tstring &tolower();

tarray_tstring &toupper();

配列要素に対する検索のためのメンバ関数

ssize_t find_elem( const char *str ) const;
ssize_t find_elem( size_t idx, const char *str ) const;
ssize_t find_elem( size_t idx, const char *str, size_t *nextidx ) const;

ssize_t rfind_elem( const char *str ) const;
ssize_t rfind_elem( size_t idx, const char *str ) const;
ssize_t rfind_elem( size_t idx, const char *str, size_t *nextidx ) const;

ssize_t find( const char *str, ssize_t *pos_r ) const;
ssize_t find( size_t idx, size_t pos, const char *str, ssize_t *pos_r ) const;
ssize_t find( size_t idx, size_t pos, const char *str, ssize_t *pos_r,
              size_t *nextidx, size_t *nextpos ) const;

ssize_t rfind( const char *str, ssize_t *pos_r ) const;
ssize_t rfind( size_t idx, size_t pos, const char *str, ssize_t *pos_r ) const;
ssize_t rfind( size_t idx, size_t pos, const char *str, ssize_t *pos_r,
               size_t *nextidx, size_t *nextpos ) const;

ssize_t find_matched_str( const char *str ) const;
ssize_t find_matched_str( size_t idx, const char *str ) const;
ssize_t find_matched_str( size_t idx, const char *str, size_t *nextidx ) const;

ssize_t find_matched_fn( const char *str ) const;
ssize_t find_matched_fn( size_t idx, const char *str ) const;
ssize_t find_matched_fn( size_t idx, const char *str, size_t *nextidx ) const;

ssize_t find_matched_pn( const char *str ) const;
ssize_t find_matched_pn( size_t idx, const char *str ) const;
ssize_t find_matched_pn( size_t idx, const char *str, size_t *nextidx ) const;

ssize_t regmatch( const char *pat, ssize_t *pos_r, size_t *span_r ) const;
ssize_t regmatch( size_t idx, size_t pos, const char *pat,
                  ssize_t *pos_r, size_t *span_r ) const;
ssize_t regmatch( size_t idx, size_t pos, const char *pat,
                  ssize_t *pos_r, size_t *span_r,
                  size_t *nextidx, size_t *nextpos ) const;
ssize_t regmatch( const tregex &pat, ssize_t *pos_r, size_t *span_r ) const;
ssize_t regmatch( size_t idx, size_t pos, const tregex &pat,
                  ssize_t *pos_r, size_t *span_r ) const;
ssize_t regmatch( size_t idx, size_t pos, const tregex &pat,
                  ssize_t *pos_r, size_t *span_r,
                  size_t *nextidx, size_t *nextpos ) const;

ssize_t regmatch( const char *pat, tarray_tstring *result );
ssize_t regmatch( size_t idx, size_t pos, const char *pat,
                  tarray_tstring *result );
ssize_t regmatch( size_t idx, size_t pos, const char *pat,
                  tarray_tstring *result, size_t *nextidx, size_t *nextpos );
ssize_t regmatch( const tregex &pat, tarray_tstring *result ) const;
ssize_t regmatch( size_t idx, size_t pos, const tregex &pat,
                  tarray_tstring *result ) const;
ssize_t regmatch( size_t idx, size_t pos, const tregex &pat,
                  tarray_tstring *result, size_t *nextidx, size_t *nextpos ) const;