POSIX 互換 C API

注釈

本リファレンスは POSIX API 関数の要約である。これらは（C++ 以外の言語によるアクセスが必要でない限り）新しいコードで使用する API ではなく、他のライブラリとの互換性のために提供されている。これらの関数が使用している名前は実際の関数名に展開されるマクロであるため、他のバージョンとの共存が可能である。

#include <boost/cregex.hpp>

あるいは

#include <boost/regex.h>

以下の関数は POSIX 互換の C ライブラリが必要なユーザ向けである。Unicode 版とナロー文字版の両方が利用可能であり、標準 POSIX API 名は UNICODE が定義されているかどうかでいずれかの版に展開されるマクロである。

重要

ここで定義するシンボルは、C++ プログラムではすべて名前空間 boost 内にあることに注意していただきたい。#include <boost/regex.h> を使用した場合はシンボルが名前空間 boost 内で定義されるのは変わらないが、大域名前空間でも利用できるようになっている。

関数の定義は以下のとおりである。

extern "C" {

struct regex_tA;
struct regex_tW;

int regcompA(regex_tA*, const char*, int);
unsigned int regerrorA(int, const regex_tA*, char*, unsigned int);
int regexecA(const regex_tA*, const char*, unsigned int, regmatch_t*, int);
void regfreeA(regex_tA*);

int regcompW(regex_tW*, const wchar_t*, int);
unsigned int regerrorW(int, const regex_tW*, wchar_t*, unsigned int);
int regexecW(const regex_tW*, const wchar_t*, unsigned int, regmatch_t*, int);
void regfreeW(regex_tW*);

#ifdef UNICODE
#define regcomp regcompW
#define regerror regerrorW
#define regexec regexecW
#define regfree regfreeW
#define regex_t regex_tW
#else
#define regcomp regcompA
#define regerror regerrorA
#define regexec regexecA
#define regfree regfreeA
#define regex_t regex_tA
#endif
}

これらの関数はすべて構造 regex_t に対して処理を行う。この構造体は次の 2 つの公開メンバを持つ。

メンバ	意味
`unsigned int` `re_nsub`	`regcomp` により値が設定され、正規表現中の部分式の総数を表す。
`const TCHAR*` `re_endp`	フラグ `REG_PEND` が設定されている場合、コンパイルする正規表現の終端を指す。

注釈

regex_t は実際は #define であり、UNICODE が定義されているかどうかにより regex_tA か regex_tW のいずれかとなる。TCHAR はマクロ UNICODE により char か wchar_t のいずれかとなる。

regcomp

regcomp は regex_t へのポインタ、コンパイルする式へのポインタおよび以下の組み合わせとなるフラグ引数をとる。

フラグ	意味
`REG_EXTENDED`	現代的な正規表現をコンパイルする。regbase::char_classes \| regbase::intervals \| regbase::bk_refs と等価である。
`REG_BASIC`	基本的な（旧式の）正規表現構文をコンパイルする。regbase::char_classes \| regbase::intervals \| regbase::limited_ops \| regbase::bk_braces \| regbase::bk_parens \| regbase::bk_refs と等価である。
`REG_NOSPEC`	文字をすべて通常の文字として扱う。正規表現は直値文字列である。
`REG_ICASE`	大文字小文字を区別しないマッチを行う。
`REG_NOSUB`	このライブラリでは効果なし。
`REG_NEWLINE`	このフラグを設定した場合、ドットが改行文字にマッチしない。
`REG_PEND`	このフラグを設定した場合、`regex_t` 構造体の `re_endp` 引数はコンパイルする正規表現の終端を指していなければならない。
`REG_NOCOLLATE`	このフラグを設定した場合、文字範囲においてロカール依存の照合が無効になる。
`REG_ESCAPE_IN_LISTS`	このフラグを設定した場合、括弧式（文字集合）内でエスケープシーケンスが使用できる。
`REG_NEWLINE_ALT`	このフラグを設定した場合、改行文字は選択演算子 `\|` と等価である。
`REG_PERL`	Perl 似の正規表現をコンパイルする。
`REG_AWK`	awk 似動作のショートカット：REG_EXTENDED \| REG_ESCAPE_IN_LISTS
`REG_GREP`	grep 似動作のショートカット：REG_BASIC \| REG_NEWLINE_ALT
`REG_EGREP`	egrep 似動作のショートカット：REG_EXTENDED \| REG_NEWLINE_ALT

regerror

regerror は以下の引数をとり、エラーコードを可読性の高い文字列に変換する。

引数	意味
`int` `code`	エラーコード。
`const regex_t*` `e`	正規表現（null でもよい）。
`char*` `buf`	エラーメッセージを書き込む文字列。
`unsigned int` `buf_size`	`buf` の長さ

エラーコードが REG_ITOA との論理和になっている場合は、結果はメッセージではなく、例えば “REG_BADPAT” のようなコードの印字可能な名前となる。code が REG_ATOI の場合は、e は null であってはならず e->re_endp は印字可能名の終端を指していなければならない。またこの場合の戻り値はエラーコードの値である。code の値がこれら以外の場合は、戻り値はエラーメッセージの文字数であり、戻り値が buf_size 以上であればより大きなバッファを用いて regerror を再度呼び出す必要がある。

regexec

regexec は文字列 buf 内から式 e の最初のマッチを検索する。len が 0 以外の場合は、*m には正規表現にマッチした内容が書き込まれる。m[0] はマッチした文字列全体、m[1] は 1 番目の部分式、m[2] は 2 番目などとなる。詳細はヘッダファイルの regmatch_t の宣言を見よ。eflags 引数は以下の組み合わせである。

フラグ	意味
`REG_NOTBOL`	引数 `buf` が行の先頭ではない。
`REG_NOTEOL`	引数 `buf` が行末で終了していない。
`REG_STARTEND`	検索する文字列は buf + pmatch[0].rm_so が先頭で、buf + pmatch[0].rm_eo が終端である。

regfree

regfree は regcomp が割り当てたメモリをすべて解放する。