NIRE

regexp<charT>

　正規表現オブジェクトの作成、保持ならびに検索や置換を行います。NIREの中核をなすクラスで、ECMAScript (JavaScript) のRegExpクラスの仕様を参考にしています。
　次のメンバ変数ならびにメンバ函数が定義されています。

コンストラクタとフラグ

　インスタンスの作成と同時に正規表現オブジェクトの新規作成も行う場合、正規表現文字列の渡し方としては「1) ヌル終端文字列へのポインタを渡す」「2) ポインタと文字列の長さとを渡す」「3) std::basic_stringへのconst参照を渡す」の3通りがあります。
　それぞれフラグの渡し方に「a) nire::flag::type型の値を渡す」「b) フラグ文字列へのポインタを渡す」の2通りがありますので、3×2＝6通りの渡し方が存在するということになります。

regexp();
regexp(const regexp &r);    //  既存のものをコピー。
regexp(regexp &&r) noexcept;    //  C++11以降。

//  ポインタ
regexp(const charT *const p, const flag::type f = flag::ECMAScript);
regexp(const charT *const p, const charT *const flags);

//  ポインタと文字列長
regexp(const charT *const p, const std::size_t len, const flag::type f);
regexp(const charT *const p, const std::size_t len, const charT *const flags);

//  basic_string
regexp(const std::basic_string<charT> &str, const flag::type f = flag::ECMAScript);
regexp(const std::basic_string<charT> &str, const charT *const flags);
				

　フラグには次のものがあります。
　nire::flag::type型の値として渡す時は | (or) で区切ることにより複数のフラグを同時に渡すことが出来ます。
　文字列として渡す時は、"im" のように書くことにより複数のフラグを渡すことが出来ます。

フラグ一覧

nire::flag::type型の値として渡す時	文字列として渡す時
nire::flag::global	"g"	グローバル検索。マッチした箇所の直後の位置をlastIndexメンバに記録し、次はそこを起点に検索する。
nire::flag::icase	"i"	大文字小文字の区別がない検索。
nire::flag::multiline	"m"	^と$とが改行文字の前後にもマッチするようにする。
nire::flag::dotall	"s"	.が改行文字も含むあらゆる文字にマッチするようにする。
nire::flag::sticky	"y"	文字列のlastIndex番目の要素からマッチするかどうかのみを調べる。
nire::flag::noflags nire::flag::ECMAScript	""	フラグ無しであることをあえて指定したい場合。

assign()

　既存の正規表現オブジェクトのコピー、移動（C++11以降のみ）または新規作成を行います。
　新規作成の場合、正規表現文字列およびフラグの渡し方にはコンストラクタ同様6通りあります。

regexp &assign(const regexp &r);
regexp &assign(regexp &&r) noexcept;    //  C++11以降。

//  ポインタ
regexp &assign(const charT *const p, const flag::type f = flag::ECMAScript);
regexp &assign(const charT *const p, const charT *const flags);

//  ポインタと文字列長
regexp &assign(const charT *const p, std::size_t len, const flag::type f);
regexp &assign(const charT *const p, std::size_t len, const charT *const flags);

//  basic_string
regexp &assign(const std::basic_string<charT> &str, const flag::type f = flag::ECMAScript);
regexp &assign(const std::basic_string<charT> &str, const charT *const flags);
				

operator=()

　既存の正規表現オブジェクトのコピー、移動（C++11以降のみ）または新規作成を行います。
　コンストラクタやassign()とは異なり、引数を1つしか指定できませんので、新規作成の場合は「1) ヌル終端文字列へのポインタを渡す」「2) std::basic_stringへのconst参照を渡す」の2択です。

regexp &operator=(const regexp &r);
regexp &operator=(regexp &&r) noexcept; //  C++11以降。

//  ポインタ
regexp &operator=(const charT *const p)

//  basic_string
regexp &operator=(const std::basic_string<charT> &str)
				

lastIndex変数

　パターンコンパイル時にglobalフラグかstickyフラグかが指定されていた場合、対象文字列のlastIndex番目の要素から検索が行われるようになります。どちらのフラグもセットされていない場合はlastIndexの値は無視され、常に対象文字列の先頭から検索が行われます。

　検索して正規表現にマッチする位置が見つかった場合、その範囲の次（[begin, end) で言うところのend）のオフセット値がlastIndexに書き込まれます。見つからなかった場合は0にリセットされます。

　検索対象文字列を変えた場合でもlastIndexは自動的にクリアされません。

　このメンバはmutable指定されていますので、regexpのインスタンスそのものがconst指定されていても書き込むことが出来ます。

exec() const

　検索を行うメンバ函数です。
　検索対象文字列の渡し方には「1) ヌル終端文字列へのポインタを渡す」「2) ポインタと文字列の長さとを渡す」「3) std::basic_stringへのconst参照を渡す」の3通りがあります。
　結果の受け取り方には「a) re_match型インスタンスの参照を引数として渡しておき、検索結果はそこに書き込んでもらう」「b) 検索結果を書き込んだre_match型インスタンスを戻り値としてreturnしてもらう」の2通りがあります。

　re_match型インスタンスの参照を引数として渡した場合、戻り値は「マッチしたかどうかを表すbool値」です。

//  ポインタ
bool exec(
    re_match<charT> &m,
    const charT *const str
) const;

re_match<charT> exec(
    const charT *const str
) const;

//  ポインタと文字列長
bool exec(
    re_match<charT> &m,
    const charT *const str,
    const std::size_t len
) const;

re_match<charT> exec(
    const charT *const str,
    const std::size_t len
) const;

//  basic_string
bool exec(
    re_match<charT> &m,
    const std::basic_string<charT> &str
) const;

re_match<charT> exec(
    const std::basic_string<charT> &str
) const;
				

　globalフラグかstickyフラグかが指定されていた場合、検索はlastIndexで指定されたオフセット位置より始まります。そしてマッチする箇所があった時にはそのマッチした範囲 [begin, end) のendのオフセット位置がlastIndexに書き込まれ、なかった時にはlastIndexには0が書き込まれます。

　繰り返しの中で使う場合はre_match型インスタンスを参照で渡す版の使用をお勧めします。

test() const

　検索対象文字列の中にマッチする箇所があるかないかだけを調べます。それ以外はexec()と同じです。

//  ポインタ
bool test(
    const charT *const str
) const;

//  ポインタと文字列長
bool test(
    const charT *const str,
    const std::size_t len
) const;

//  basic_string
bool test(
    const std::basic_string<charT> &str
) const;
				

replace() const

　JavaScriptのString.prototype.replace(RegExpオブジェクト, 置換文字列またはコールバック函数)に準拠した動作をします。
　検索対象文字列中の「正規表現とマッチする箇所」を別の文字列に置き換えます。置き換えられた文字列は戻り値としてreturnされてきて、元の検索対象文字列はそのまま残ります。
　置換後の文字列の指定方法としては「1) 書式文字列を渡す」「2) コールバック函数を渡す」の2通りがあります。

　globalフラグがセットされていた時は、対象文字列中の正規表現にマッチする箇所すべてが置換の対象となります。それ以外の時は最初にマッチした部分だけが対象となります。

//  書式文字列による置換
//  ポインタ
std::basic_string<charT> replace(
    const charT *const str,
    const charT *const fmt
) const;

//  ポインタと文字列長
std::basic_string<charT> replace(
    const charT *const str,
    const std::size_t len,
    const charT *const fmt_text,
    const std::size_t fmt_len
) const;

//  basic_string
std::basic_string<charT> replace(
    const std::basic_string<charT> &str,
    const std::basic_string<charT> &fmt
) const;

//  コールバック函数による置換
typedef std::basic_string<charT> (*replace_function)(const re_match<charT> &);

//  ポインタ
std::basic_string<charT> replace(
    const charT *const str,
    const replace_function repfunc
) const;

//  ポインタと文字列長
std::basic_string<charT> replace(
    const charT *str,
    const std::size_t len,
    const replace_function repfunc
) const;

//  basic_string
std::basic_string<charT> replace(
    const std::basic_string<charT> &str,
    const replace_function repfunc
) const;
				

書式文字列による置換

　ECMAScript仕様書の Runtime Semantics: GetSubstitutionの表に定められているものが書式文字列として使えます。
　この表にない文字はそのまま置換後の文字列として使われます。

書式文字列として使えるテキストシンボル一覧

テキストシンボル	置換テキスト
$$	$そのもの。
$&	マッチした箇所全体。
$`	マッチした箇所に先行する部分。
$'	マッチした箇所より後方の部分。
$1 $2 $3 $4 $5 $6 $7 $8 $9 （後ろに数字が続かぬこと）	正規表現中の対応する括弧で捕獲された文字列。該当する括弧が何も捕獲していない場合は空文字に置換される。正規表現中のキャプチャ括弧の個数より大きな数が指定された場合は置換されず。
$nn（nnは01から99までの範囲）	正規表現中の対応する括弧で捕獲された文字列。該当する括弧が何も捕獲していない場合は空文字に置換される。正規表現中のキャプチャ括弧の個数より大きな数が指定された場合は置換されず。
$<NAME>	正規表現中に「名前付きキャプチャ」が存在しない場合、置換されずそのまま出力される。 存在する場合、NAMEという名前の丸括弧によって捕獲された文字列と置換される。NAMEに相当する名前のグループ名が正規表現中にないか、あっても何もキャプチャされていなければ空文字列に置換される。

//  書式指定による置換例。
#include <cstdio>
#include <string>
#include "nire.hpp"

int main()
{
    const nire::RegExp re("(\\d)(\\d)", "g");   //  数字が2つ続いている箇所を探す。
    const std::string rep = re.replace("abc0123456789def", "($2$1)");
        //  $1と$2との順番を入れ替えて括弧でくくる。

    std::printf("Result: %s\n", rep.c_str());
    return 0;
}
---- 実行結果 ----
Result: abc(10)(32)(54)(76)(98)def
					

コールバック函数による置換

　マッチした箇所の情報を函数内部のre_match<charT>型インスタンスにセットし、それへのconst参照を引数とするコールバック函数を呼び出します。
　コールバック函数の側は、置換後の文字列をstd::basic_string<charT>型インスタンスにセットしてreturnする必要があります。なおこちらの方法では前述の書式文字列は使えません。

//  コールバック函数による置換例。
#include <cstdio>
#include <string>
#include "nire.hpp"

std::string repfunc1(const nire::Match &m)
{
    return " [" + m[1].str() + ", " + m[2].str() + "] ";
}

int main()
{
    const nire::RegExp re("(\\d)(\\d)", "g");
    const std::string text("abc0123456789def");
    std::string rep;

    rep = re.replace(text, repfunc1);
    std::printf("Result1(C++98/C++03): %s\n", rep.c_str());

    //  C++11以降のラムダ式による置換。
    rep = re.replace(text, [](const nire::Match &m) -> std::string {
        return " [" + m[1].str() + ", " + m[2].str() + "] ";
    });
    std::printf("Result2(C++11): %s\n", rep.c_str());

    //  C++14以降。
    rep = re.replace(text, [](const auto &m) {
        return " [" + m[1].str() + ", " + m[2].str() + "] ";
    });
    std::printf("Result3(C++14): %s\n", rep.c_str());

    return 0;
}
---- 実行結果 ----
Result1(C++98/C++03): abc [0, 1]  [2, 3]  [4, 5]  [6, 7]  [8, 9] def
Result2(C++11): abc [0, 1]  [2, 3]  [4, 5]  [6, 7]  [8, 9] def
Result3(C++14): abc [0, 1]  [2, 3]  [4, 5]  [6, 7]  [8, 9] def
					

split() const

　JavaScriptのString.prototype.split(RegExpオブジェクト, リミット)に準拠した動作をします。
　検索対象文字列中の「正規表現とマッチする箇所」の前後を分割してstd::basic_string型インスタンスを作り、それらを配列コンテナに詰め込んでreturnします。
　正規表現の中にキャプチャ括弧があった場合はそれらもすべて配列コンテナに詰め込まれます。何も捕獲していない括弧のところも飛ばされず、空文字列がpushされます。

　結果を受け取るコンテナ型は、clear(), size(), push_back()の3つが実装されていれば何でも使えます。戻り値はpush_back()が行われた回数です。

//  ポインタ
template <typename ContainerT>
std::size_t split(
    ContainerT &out,
    const charT *const str,
    const std::size_t limit = static_cast<std::size_t>(-1),
    const bool push_remainder = false
) const;

//  ポインタと文字列長（lengthのほうが先なのはオーヴァーロード解決のため）
template <typename ContainerT>
std::size_t split(
    ContainerT &out,
    const std::size_t len,
    const charT *const str,
    const std::size_t limit = static_cast<std::size_t>(-1),
    const bool push_remainder = false
) const;

//  basic_string
template <typename ContainerT>
std::size_t split(
    ContainerT &out,
    const std::basic_string<charT> &str,
    const std::size_t limit = static_cast<std::size_t>(-1),
    const bool push_remainder = false
) const;
				

　引数のlimitは分割する回数の上限値です。例えば分割する正規表現が /,/ でlimitが5であった場合、検索対象文字列中に5回 ',' を発見した時点で分割処理は終了します。

　分割回数の上限が指定できるsplit()というのはスクリプト言語によくある機能ですが、JavaScriptのsplit()は少し変わっていて、マッチングがlimitで指定された回数に達するとそれ以降のまだ調べていない部分の文字列は戻り値の中に含めず、そのまま捨ててしまいます。
　この挙動は個人的にあまり嬉しくありませんので、NIREでは独自拡張機能として「分割がlimitの回数に達した時、それより後ろのまだ調べていない部分の文字列も戻り値の中に含めるかどうか」を指定するpush_remainderフラグを追加してあります。
　push_remainderがtrueの時は、最大でlimit + 1個分の要素が返されてくることになります。これは結果的にPythonのsplit()と似た挙動になっています。

//  limitとpush_remainderフラグの挙動。
#include <cstdio>
#include <string>
#include <vector>
#include "nire.hpp"

int main()
{
    const nire::RegExp re(":");
    const std::string text("0:12:345:6789:abcdef");
    std::vector<std::string> res;

    //  無制限分割。
    re.split(res, text);
    for (std::size_t i = 0; i < res.size(); ++i)
        std::printf("%s%s", i == 0 ? "[" : ", ", res[i].c_str());
    std::puts("]");

    //  limit=2. 残りは捨てられる。
    re.split(res, text, 2);
    for (std::size_t i = 0; i < res.size(); ++i)
        std::printf("%s%s", i == 0 ? "[" : ", ", res[i].c_str());
    std::puts("]");

    //  limit=2 かつ push_remainder=true. 残りは最後に一括してpushされる。
    re.split(res, text, 2, true);
    for (std::size_t i = 0; i < res.size(); ++i)
        std::printf("%s%s", i == 0 ? "[" : ", ", res[i].c_str());
    std::puts("]");

    return 0;
}
---- 実行結果 ----
[0, 12, 345, 6789, abcdef]
[0, 12]
[0, 12, 345:6789:abcdef]
				

swap()

　インスタンスの内容を交換します。re1.swap(re2)とnire::swap(re1, re2)とが定義されています。

フラグの読み出し

　以下は正規表現オブジェクト作成時に指定されたフラグを読み出すためのメンバ函数です。函数名はいずれもJavaScriptにおける同名のプロパティー名から来ています。

フラグの読み出し函数一覧

函数名	戻り値
std::basic_string<charT> flags();	パターンコンパイル時に渡されたフラグを文字列化したもの。
bool global();	nire::flag::global または "g" が指定されたか否か。
bool ignoreCase();	nire::flag::icase または "i" が指定されたか否か。
bool multiline();	nire::flag::multiline または "m" が指定されたか否か。
bool dotAll();	nire::flag::dotall または "s" が指定されたか否か。
bool unicode();	常にtrueが返る。
bool sticky();	nire::flag::sticky または "y" が指定されたか否か。

re_match<charT>

　RegExp.exec()によって正規表現検索の結果が収められるクラスです。
　JavaScriptのRegExp.exec()の返り値を参考に次のメンバが定義されています。

bool値へのキャスト

　re_match型インスタンスは正規表現にマッチしたかどうかを示すbool値にキャストすることが出来ます。

std::size_t length() const
std::size_t size() const

　直前のマッチが成功していた場合、正規表現中に出てくるキャプチャ括弧の数+1が返ってきます。失敗していた場合やインスタンス作成後まだ一度も検索の結果を受け取っていない場合は0が返ってきます。+1されるのは「正規表現全体にマッチした箇所は暗黙の0番括弧によって捕獲された」と見なされるためです。

　C++のクラスでは.size()という名前のメンバ函数を通して要素の数を取得することが多いのに対して、JavaScriptでは.lengthというプロパティーを使って要素の数を読み書きする仕組みになっています。どちらでもお好みで使えるようにNIREではsize()とlength()との両方用意してあります。

const re_group<charT> &operator[](unsigned int n) const
const re_group<charT> &operator[](const charT *gname) const
const re_group<charT> &operator[](const std::basic_string<charT> &gname) const

　re_match型インスタンスをmとした時、m[0]には正規表現にマッチした箇所全体の位置情報が収められています。m[1]以降にはそれぞれ対応する番号の括弧で捕獲された文字列の位置情報が収められています。
　引数として指定できるのは、0からlength()の値-1までです。

　引数が文字列の場合はgnameというグループ名で捕獲された文字列の位置情報を返します。

　戻り値であるre_group<charT>型はstd::basic_string<charT>にキャストできますので、マッチした部分の情報を直接文字列として受け取ることも可能です。この型の詳細については後述します。

std::size_t index(unsigned int n = 0) const
std::size_t index(const charT *gname) const
std::size_t index(const std::basic_string<charT> &gname) const

　引数で指定されたグループの範囲 [begin, end) のbeginが、検索対象文字列において何番目（0起点）の要素に当たるかを返します。

std::size_t endIndex(unsigned int n = 0) const
std::size_t endIndex(const charT *gname) const
std::size_t endIndex(const std::basic_string<charT> &gname) const

　引数で指定されたグループの範囲 [begin, end) のendが、検索対象文字列において何番目（0起点）の要素に当たるかを返します。

swap()

　インスタンスの内容を交換します。re1.swap(re2)とnire::swap(re1, re2)とが定義されています。

re_group<charT>

　正規表現にマッチした範囲の位置情報を保持する構造体です。この型はis_trivially_copyableですのでmemcpyでコピーすることも出来ます。
　この型が保持しているのは位置情報だけですので、文字列を取り出す際には検索対象文字列がその時点でまだメモリ上に存在している必要があります。

　次のメンバが定義されています。

bool値へのキャスト

　re_group型インスタンスは、内部の位置情報が有効な範囲を指し示しているかどうかを示すbool値にキャストすることが出来ます。

std::basic_string<charT>へのキャスト
std::basic_string<charT> str() const

　re_group内で保持している位置情報を元にstd::basic_string<charT>型の文字列を作り、それをreturnします。

std::size_t length() const
std::size_t size() const

　保持している範囲がコードユニット何個分になるかを返します。何もキャプチャしていない時は0が返ります。

　例によってsize()とlength()との両方用意してあります。

matched() const

　文字列が捕獲されているかどうかを示すbool値を返します。

比較

　re_group<charT>同士またはstd::basic_string<charT>との比較用に==, !=, <, <=, >, >=が定義されています。

re_error

　パターンコンパイル時または照合時にエラーが発生すると、nire::re_errorがthrowされてきます。
　nire::re_errorはstd::runtime_errorの派生クラスで次のメンバが定義されています。

//  nire::re_errorのメンバ。
const char *what() const;       //  std::runtime_errorより継承したもの。
re_error::type code() const;    //  エラー番号の読み出しを行う。
		

　エラー番号は次の通りです。

　これらの他、メモリの確保に失敗した時にはstd::bad_allocがthrowされてきます。

ECMAScriptのRegExp関連

• ECMAScript規格最新ドラフトの21.2 RegExp (Regular Expression) Objects
• ECMAScript 2016+ compatibility table

• Proposal to add support for sequence properties in Unicode property escapes to ECMAScript regular expressions
  Issue #10: Using something other than `\p{…}`, e.g. `\m{…}`?
• ECMAScript RegExp Match Indices