match_results
-
template<class BidirectionalIterator, class Allocator = std::allocator<sub_match<BidirectionalIterator>>>
class match_results 正規表現が他の多くの単純なパターンマッチアルゴリズムと異なるのは、マッチを発見するだけでなく、部分式のマッチを生成する点である。各部分式はパターン中の括弧の組
(…)
により、その範囲が与えられる。部分式のマッチをユーザに知らせるために何らかの方法が必要である。部分式マッチの添字付きコレクションとして振舞うmatch_results
クラスの定義がそれであり、各部分式マッチはsub_match
型オブジェクトに含まれる。テンプレートクラス
match_results
は、正規表現マッチの結果を表す文字シーケンスのコレクションを表現する。match_results
型のオブジェクトはregex_match
およびregex_search
アルゴリズムに渡して使用する。またイテレータregex_iterator
がこのオブジェクトを返す。このコレクションが使用するストレージは、match_results
のメンバ関数が必要に応じて割り当て、解放する。テンプレートクラス
match_results
は(lib.sequence.reqmts)が規定する Sequence の要件を満たす。ただし const 限定の操作に限られる。大抵の場合、クラステンプレート
match_results
を使用するときは、その typedef であるcmatch
、wcmatch
、smatch
およびwsmatch
のいずれかを用いる。
概要
#include <boost/regex.hpp> template <class BidirectionalIterator, class Allocator = std::allocator<sub_match<BidirectionalIterator> > class match_results; typedef match_results<const char*> cmatch; typedef match_results<const wchar_t*> wcmatch; typedef match_results<string::const_iterator> smatch; typedef match_results<wstring::const_iterator> wsmatch; template <class BidirectionalIterator, class Allocator = std::allocator<sub_match<BidirectionalIterator> > class match_results { public: typedef sub_match<BidirectionalIterator> value_type; typedef const value_type& const_reference; typedef const_reference reference; typedefimplementation defined
const_iterator; typedef const_iterator iterator; typedef typename iterator_traits<BidirectionalIterator>::difference_type difference_type; typedef typename Allocator::size_type size_type; typedef Allocator allocator_type; typedef typename iterator_traits<BidirectionalIterator>::value_type char_type; typedef basic_string<char_type> string_type; // 構築、コピー、解体: explicitmatch_results
(const Allocator& a = Allocator());match_results
(const match_results& m); match_results&operator=
(const match_results& m); ~match_results(); // サイズ: size_typesize
() const; size_typemax_size
() const; boolempty
() const; // 要素アクセス: difference_typelength
(int sub = 0) const; difference_typelength
(const char_type* sub) const; template <class charT> difference_typelength
(const charT* sub) const; template <class charT, class Traits, class A> difference_typelength
(const std::basic_string<charT, Traits, A>& sub) const; difference_typeposition
(unsigned int sub = 0) const; difference_typeposition
(const char_type* sub) const; template <class charT> difference_typeposition
(const charT* sub) const; template <class charT, class Traits, class A> difference_typeposition
(const std::basic_string<charT, Traits, A>& sub) const; string_typestr
(int sub = 0) const; string_typestr
(const char_type* sub)const; template <class Traits, class A> string_typestr
(const std::basic_string<char_type, Traits, A>& sub)const; template <class charT> string_typestr
(const charT* sub)const; template <class charT, class Traits, class A> string_typestr
(const std::basic_string<charT, Traits, A>& sub)const; const_referenceoperator[]
(int n) const; const_referenceoperator[]
(const char_type* n) const; template <class Traits, class A> const_referenceoperator[]
(const std::basic_string<char_type, Traits, A>& n) const; template <class charT> const_referenceoperator[]
(const charT* n) const; template <class charT, class Traits, class A> const_referenceoperator[]
(const std::basic_string<charT, Traits, A>& n) const; const_referenceprefix
() const; const_referencesuffix
() const; const_iteratorbegin
() const; const_iteratorend
() const; // 書式化: template <class OutputIterator, class Formatter> OutputIteratorformat
(OutputIterator out, Formatter& fmt, match_flag_type flags = format_default) const; template <class Formatter> string_typeformat
</methodname>(const Formatter fmt, match_flag_type flags = format_default) const; allocator_typeget_allocator
() const; voidswap
(match_results& that); #ifdef BOOST_REGEX_MATCH_EXTRA typedef typename value_type::capture_sequence_type capture_sequence_type; const capture_sequence_type&captures
(std::size_t i)const; #endif }; template <class BidirectionalIterator, class Allocator> booloperator ==
(const match_results<BidirectionalIterator, Allocator>& m1, const match_results<BidirectionalIterator, Allocator>& m2); template <class BidirectionalIterator, class Allocator> booloperator !=
(const match_results<BidirectionalIterator, Allocator>& m1, const match_results<BidirectionalIterator, Allocator>& m2); template <class charT, class traits, class BidirectionalIterator, class Allocator> basic_ostream<charT, traits>&operator <<
(basic_ostream<charT, traits>& os, const match_results<BidirectionalIterator, Allocator>& m); template <class BidirectionalIterator, class Allocator> voidswap
(match_results<BidirectionalIterator, Allocator>& m1, match_results<BidirectionalIterator, Allocator>& m2);
説明
-
match_results(const Allocator &a = Allocator())
- 効果
match_results
クラスのオブジェクトを構築する。この関数の事後条件は次の表のとおりである。
要素
値
empty()
true
size()
0
str()
basic_string<charT>()
match_results
のすべてのコンストラクタにおけるAllocator
引数のコピーは、オブジェクトの生涯にわたってコンストラクタとメンバ関数によるメモリ割り当てに使用される。
-
match_results(const match_results &m)
- 効果
m
をコピーしてmatch_results
クラスのオブジェクトを構築する。
-
match_results &operator=(const match_results &m)
- 効果
m
を *this に代入する。この関数の事後条件は次の表のとおりである。
要素
値
empty()
m.empty()
size()
m.size()
str(n)
prefix()
m.prefix()
suffix()
m.suffix()
(*this)[n]
length(n)
position(n)
-
difference_type length(int sub = 0) const
-
difference_type length(const char_type *sub) const
-
template<class charT>
difference_type length(const charT *sub) const -
template<charT, class Traits, class A>
difference_type length(const std::basic_string<charT, Traits, A> &sub) const - 要件
match_results
オブジェクトがregex_search
かregex_match
の呼び出し結果で初期化された、またはregex_iterator
が返したもので、かつそのイテレータが無効状態でない。match_results
オブジェクトが未初期化の場合、std::logic_error
が発生する。- 効果
部分式
sub
の長さを返す。(*this)[sub].length() と同じである。文字列を引数に取る多重定義は
n
番目の名前付き部分式を参照する。指定した名前をもつ部分式がない場合は 0 を返す。この関数のテンプレート多重定義に渡す文字列・文字の型は、オブジェクトが保持するシーケンスや正規表現の文字型と異なっていてもよい。この場合、文字列は正規表現が保持する文字型に変換される。引数の文字型が正規表現が保持するシーケンスの文字型より幅が大きい場合はコンパイルエラーとなる。これらの多重定義は、マッチを行う正規表現の文字型が Unicode 文字型のような変り種の場合であっても、通常の幅の小さい C 文字列リテラルを引数として渡せるようにしてある。
-
difference_type position(unsigned int sub = 0) const
-
difference_type position(const char_type *sub) const
-
template<class charT>
difference_type position(const charT *sub) const -
template<class charT, class Traits, class A>
difference_type position(const std::basic_string<charT, Traits, A> &sub) const - 要件
match_results
オブジェクトがregex_search
かregex_match
の呼び出し結果で初期化された、またはregex_iterator
が返したもので、かつそのイテレータが無効状態でない。match_results
オブジェクトが未初期化の場合、std::logic_error
が発生する。- 効果
部分式
sub
の開始位置を返す。sub
がマッチしなかった場合は -1 を返す。部分マッチの場合は (*this)[0].matched は偽であるが、position() は部分マッチの位置を返す。文字列を引数に取る多重定義は
n
番目の名前付き部分式を参照する。指定した名前をもつ部分式がない場合は -1 を返す。この関数のテンプレート多重定義に渡す文字列・文字の型は、オブジェクトが保持するシーケンスや正規表現の文字型と異なっていてもよい。この場合、文字列は正規表現が保持する文字型に変換される。引数の文字型が正規表現が保持するシーケンスの文字型より幅が大きい場合はコンパイルエラーとなる。これらの多重定義は、マッチを行う正規表現の文字型が Unicode 文字型のような変り種の場合であっても、通常の幅の小さい C 文字列リテラルを引数として渡せるようにしてある。
-
string_type str(int sub = 0) const
-
string_type str(const char_type *sub) const
-
template<class Traits, class A>
string_type str(const std::basic_string<char_type, Traits, A> &sub) const -
template<class charT>
string_type str(const charT *sub) const -
template<class charT, class Traits, class A>
string_type str(const std::basic_string<charT, Traits, A> &sub) const - 要件
match_results
オブジェクトがregex_search
かregex_match
の呼び出し結果で初期化された、またはregex_iterator
が返したもので、かつそのイテレータが無効状態でない。match_results
オブジェクトが未初期化の場合、std::logic_error
が発生する。- 効果
部分式
sub
の文字列を返す。string_type((*this)[sub]) と同じである。文字列を引数に取る多重定義は
n
番目の名前付き部分式を参照する。指定した名前をもつ部分式がない場合は空文字列を返す。この関数のテンプレート多重定義に渡す文字列・文字の型は、オブジェクトが保持するシーケンスや正規表現の文字型と異なっていてもよい。この場合、文字列は正規表現が保持する文字型に変換される。引数の文字型が正規表現が保持するシーケンスの文字型より幅が大きい場合はコンパイルエラーとなる。これらの多重定義は、マッチを行う正規表現の文字型が Unicode 文字型のような変り種の場合であっても、通常の幅の小さい C 文字列リテラルを引数として渡せるようにしてある。
-
const_reference operator[](int n) const
-
const_reference operator[](const char_type *n) const
-
template<class Traits, class A>
const_reference operator[](const std::basic_string<char_type, Traits, A> &n) const -
template<class charT>
const_reference operator[](const charT *n) const -
template<class charT, class Traits, class A>
const_reference operator[](const std::basic_string<charT, Traits, A> &n) const - 要件
match_results
オブジェクトがregex_search
かregex_match
の呼び出し結果で初期化された、またはregex_iterator
が返したもので、かつそのイテレータが無効状態でない。match_results
オブジェクトが未初期化の場合、std::logic_error
が発生する。- 効果
マーク済み部分式
n
にマッチした文字シーケンスを表すsub_match
オブジェクトへの参照を返す。n == 0 の場合は、正規表現全体にマッチした文字シーケンスを表すsub_match
オブジェクトへの参照を返す。n
が範囲外であるかマッチしなかった部分式を指している場合は、matched
メンバが偽であるsub_match
オブジェクトを返す。文字列を引数に取る多重定義は
n
番目の名前付き部分式にマッチした文字シーケンスを表すsub_match
オブジェクトへの参照を返す。指定した名前をもつ部分式がない場合はmatched
メンバが偽であるsub_match
オブジェクトを返す。この関数のテンプレート多重定義に渡す文字列・文字の型は、オブジェクトが保持するシーケンスや正規表現の文字型と異なっていてもよい。この場合、文字列は正規表現が保持する文字型に変換される。引数の文字型が正規表現が保持するシーケンスの文字型より幅が大きい場合はコンパイルエラーとなる。これらの多重定義は、マッチを行う正規表現の文字型が Unicode 文字型のような変り種の場合であっても、通常の幅の小さい C 文字列リテラルを引数として渡せるようにしてある。
-
const_reference prefix() const
- 要件
match_results
オブジェクトがregex_search
かregex_match
の呼び出し結果で初期化された、またはregex_iterator
が返したもので、かつそのイテレータが無効状態でない。match_results
オブジェクトが未初期化の場合、std::logic_error
が発生する。- 効果
マッチ・検索を行う文字列の先頭から見つかったマッチの先頭までの文字シーケンスを表す
sub_match
オブジェクトへの参照を返す。
-
const_reference suffix() const
- 要件
match_results
オブジェクトがregex_search
かregex_match
の呼び出し結果で初期化された、またはregex_iterator
が返したもので、かつそのイテレータが無効状態でない。match_results
オブジェクトが未初期化の場合、std::logic_error
が発生する。- 効果
見つかったマッチの終端からマッチ・検索を行う文字列の終端までの文字シーケンスを表す
sub_match
オブジェクトへの参照を返す。
-
const_iterator begin() const
- 効果
*this に格納されたすべてのマーク済み部分式を列挙する開始イテレータを返す。
-
const_iterator end() const
- 効果
*this に格納されたすべてのマーク済み部分式を列挙する終了イテレータを返す。
-
template<class OutputIterator, class Formatter>
OutputIterator format(OutputIterator out, Formatter fmt, match_flag_type flags = format_default) - 要件
型
OutputIterator
が出力イテレータの要件(C++ 標準 24.1.2)を満たす。型
Formatter
はchar_type[]
型の null 終端文字列へのポインタ、char_type
型のコンテナ(例えばstd::basic_string<char_type>
)、あるいは関数呼び出しにより置換文字列を生成する単項・二項・三項関数子のいずれかでなければならない。関数子の場合、fmt(*this) は置換テキストと使用するchar_type
のコンテナを返さなければならず、fmt(*this, out) および fmt(*this, out, flags) はいずれも置換テキストを *out に出力しOutputIterator
の新しい位置を返さなければならない。書式化子が関数子の場合は値渡しとなることに注意していただきたい。内部状態を持つ関数オブジェクトを渡す場合、Boost.Ref を使用してオブジェクトを参照渡しするとよい。- 要件
match_results
オブジェクトがregex_search
かregex_match
の呼び出し結果で初期化された、またはregex_iterator
が返したもので、かつそのイテレータが無効状態でない。match_results
オブジェクトが未初期化の場合、std::logic_error
が発生する。- 効果
fmt
が null 終端文字列かchar_type
のコンテナであれば、文字シーケンス [fmt.begin(), fmt.end()) をOutputIterator
out
にコピーする。fmt
中の各書式指定子とエスケープシーケンスは、シーケンスをそれぞれが表す文字(列)か、参照する *this 中の文字シーケンスで置換する。flags
で指定したビットマスクはどの書式指定子・エスケープシーケンスを使用するか決定し、既定では ECMA-262 、ECMAScript 言語仕様、15 章 5.4.11 String.prototype.replace で使用されている書式である。fmt
が関数オブジェクトであれば、関数オブジェクトが受け取った引数の数により以下のようになる。すべての場合で
OutputIterator
の新しい位置が返される。詳細は書式化構文ガイドを見よ。
- 戻り値
out
-
template<class Formatter>
string_type format(Formatter fmt, match_flag_type flags = format_default) - 要件
型
Formatter
はchar_type[]
型の null 終端文字列へのポインタ、char_type
型のコンテナ(例えばstd::basic_string<char_type>
)、あるいは関数呼び出しにより置換文字列を生成する単項・二項・三項関数子のいずれかでなければならない。関数子の場合、fmt(*this) は置換テキストと使用するchar_type
のコンテナを返さなければならず、fmt(*this, out) および fmt(*this, out, flags) はいずれも置換テキストを *out に出力しOutputIterator
の新しい位置を返さなければならない。- 要件
match_results
オブジェクトがregex_search
かregex_match
の呼び出し結果で初期化された、またはregex_iterator
が返したもので、かつそのイテレータが無効状態でない。match_results
オブジェクトが未初期化の場合、std::logic_error
が発生する。- 効果
fmt
が null 終端文字列かchar_type
のコンテナであれば、文字列fmt
をコピーする。fmt
中の各書式指定子とエスケープシーケンスは、シーケンスをそれぞれが表す文字(列)か、参照する *this 中の文字シーケンスで置換する。flags
で指定したビットマスクはどの書式指定子・エスケープシーケンスを使用するか決定し、既定では ECMA-262 、ECMAScript 言語仕様、15 章 5.4.11 String.prototype.replace で使用されている書式である。fmt
が関数オブジェクトであれば、関数オブジェクトが受け取った引数の数により以下のようになる。fmt(*this) を呼び出し、結果を返す。
fmt(*this, unspecified_output_iterator) を呼び出す。
unspecified_output_iterator
は出力を結果文字列にコピーする指定なしのOutputIterator
型である。fmt(*this, unspecified_output_iterator, flags) を呼び出す。
unspecified_output_iterator
は出力を結果文字列にコピーする指定なしのOutputIterator
型である。
すべての場合で
OutputIterator
の新しい位置が返される。詳細は書式化構文ガイドを見よ。
-
allocator_type get_allocator() const
- 効果
オブジェクトのコンストラクタで渡した
Allocator
のコピーを返す。
-
void swap(match_results &that)
- 効果
2 つのシーケンスの内容を交換する。
- 事後条件
*this は、
that
が保持していた、部分式にマッチしたシーケンスを保持する。that
は、*this が保持していた、部分式にマッチしたシーケンスを保持する。- 計算量
一定。
-
typedef typename value_type::capture_sequence_type capture_sequence_type
標準ライブラリ Sequence の要件(21.1.1 および表 68 の操作)を満たす実装固有の型を定義する。その
value_type
はsub_match<BidirectionalIterator>
である。この型がstd::vector<sub_match<BidirectionalIterator> >
となる可能性もあるが、それに依存すべきではない。
-
const capture_sequence_type &captures(std::size_t i) const
- 要件
match_results
オブジェクトがregex_search
かregex_match
の呼び出し結果で初期化された、またはregex_iterator
が返したもので、かつそのイテレータが無効状態でない。match_results
オブジェクトが未初期化の場合、std::logic_error
が発生する。- 効果
部分式
i
に対するすべての捕捉を格納したシーケンスを返す。- 戻り値
(*this)[i].captures()
- 事前条件
BOOST_REGEX_MATCH_EXTRA
を使ってライブラリをビルドしていなければ、このメンバ関数は定義されない。また正規表現マッチ関数(regex_match
、regex_search
、regex_iterator
、regex_token_iterator
)にフラグmatch_extra
を渡していなければ、有用な情報を返さない。- 根拠
この機能を有効にするといくつか影響がある。
sub_match
がより多くのメモリを占有し、複雑な正規表現をマッチする場合にすぐにメモリやスタック空間の不足に陥る。match_extra
を使用しない場合であっても、処理する機能(例えば独立部分式)によってはマッチアルゴリズムの効率が落ちる。match_extra
を使用するとさらに効率が落ちる(速度が低下する)。ほとんどの場合、さらに必要なメモリ割り当てが起こる。
-
template<class BidirectionalIterator, class Allocator>
bool operator==(const match_results<BidirectionalIterator, Allocator> &m1, const match_results<BidirectionalIterator, Allocator> &m2) - 効果
2 つのシーケンスの等価性を比較する。
-
template<class BidirectionalIterator, class Allocator>
bool operator!=(const match_results<BidirectionalIterator, Allocator> &m1, const match_results<BidirectionalIterator, Allocator> &m2) - 効果
2 つのシーケンスの非等価性を比較する。
-
template<class charT, class traits, class BidirectionalIterator, class Allocator>
basic_ostream<charT, traits> &operator<<(basic_ostream<charT, traits> &os, const match_results<BidirectionalIterator, Allocator> &m)
-
template<class BidirectionalIterator, class Allocator>
void swap(match_results<BidirectionalIterator, Allocator> &m1, match_results<BidirectionalIterator, Allocator> &m2) - 効果
2 つのシーケンスの内容を交換する。