NSRegularExpression

Overview 概要

The fundamental matching method for NSRegularExpression is a Block iterator method that allows clients to supply a Block object which will be invoked each time the regular expression matches a portion of the target string. There are additional convenience methods for returning all the matches as an array, the total number of matches, the first match, and the range of the first match. NSRegularExpressionの基本となるマッチング・メソッドは、「ブロック」イテレータメソッド（反復子メソッド）です、それは、その正規表現が目標文字列のある部分にマッチするたびに呼び出される「ブロック」オブジェクトを、クライアントが提供できるようにするものです。全てのマッチの配列、マッチの総数、最初のマッチ、そして最初のマッチの範囲を返す、いっそう便利なメソッドもあります。

An individual match is represented by an instance of the NSTextCheckingResult class, which carries information about the overall matched range (via its range property), and the range of each individual capture group (via the range(at:) method). For basic NSRegularExpression objects, these match results will be of type regularExpression, but subclasses may use other types. ある特定のマッチはNSTextCheckingResultクラスのインスタンスによって表されます、そして、それはマッチされた全体の範囲（そのrangeプロパティによって）、そして個々の捕獲グループの範囲（range(at:)メソッドによって）に関する情報を持ち運びます。基本的なNSRegularExpressionオブジェクトに対して、これらのマッチ結果は型regularExpressionのものです、しかしサブクラスは他の型を使うかもしれません。

Examples Using NSRegularExpression NSRegularExpressionの使用例

What follows are a set of graduated examples for using the NSRegularExpression class. All these examples use the regular expression \\b(a|b)(c|d)\\b as their regular expression. 以下のものは、NSRegularExpressionクラスの使用に対する一揃いの段階的な例です。これらの例の全ては、それらの正規表現として正規表現\\b(a|b)(c|d)\\bを使います。

This snippet creates a regular expression to match two-letter words, in which the first letter is “a” or “b” and the second letter is “c” or “d”. Specifying caseInsensitive means that matches will be case-insensitive, so this will match “BC”, “aD”, and so forth, as well as their lower-case equivalents. この切れっぱしは、最初の文字が“a”または“b”で２番目の文字が“c”または“d”であるところの、２文字単語にマッチする正規表現をつくります。caseInsensitiveの指定は、マッチが大文字と小文字の区別をしないことを意味します、それでこれは、“BC”、“aD”、その他にマッチします、それらの小文字の等価物だけではなしに。

NSError *error = NULL;
NSRegularExpression *regex = [NSRegularExpression regularExpressionWithPattern:@"\\b(a|b)(c|d)\\b"
                                                                       options:NSRegularExpressionCaseInsensitive
                                                                         error:&error];

The numberOfMatches(in:options:range:) method provides a simple mechanism for counting the number of matches in a given range of a string. numberOfMatches(in:options:range:)メソッドは、ある文字列の与えられた範囲においてマッチの数を数えるための単純な仕組みを提供します。

NSUInteger numberOfMatches = [regex numberOfMatchesInString:string
                                                    options:0
                                                      range:NSMakeRange(0, [string length])];

If you are interested only in the overall range of the first match, the rangeOfFirstMatch(in:options:range:) method provides it for you. Some regular expressions (though not the example pattern) can successfully match a zero-length range, so the comparison of the resulting range with {NSNotFound, 0} is the most reliable way to determine whether there was a match or not. あなたが最初のマッチの範囲だけに興味があるならば、rangeOfFirstMatch(in:options:range:)メソッドがあなたにそれを与えます。若干の正規表現は（例パターンはそうでないけれども）成功裏にゼロ長の範囲にマッチすることができるので、結果として生じる範囲を{NSNotFound, 0}と比較することは、マッチがあったかどうか判定する最も信頼できる方法です。

The example regular expression contains two capture groups, corresponding to the two sets of parentheses, one for the first letter, and one for the second. If you are interested in more than just the overall matched range, you want to obtain an NSTextCheckingResult object corresponding to a given match. This object provides information about the overall matched range, via its range property, and also supplies the capture group ranges, via the range(at:) method. The first capture group range is given by [result rangeAtIndex:1], the second by [result rangeAtIndex:2]. この例の正規表現は、最初の文字のためのものと２番目のためのもの、２つの括弧対に対応している、２つの捕獲グループを含みます。あなたが単にマッチした範囲全体だけでなくより多くのことに興味を持つならば、あなたは与えられたマッチに対応しているNSTextCheckingResultオブジェクトを得るといいでしょう。このオブジェクトは、そのrangeプロパティによって、全体的なマッチされた範囲に関する情報を提供して、そのうえ、range(at:)メソッドによって、捕獲グループの範囲を供給します。最初の捕獲グループ範囲は[result rangeAtIndex:1]で、２番目は[result rangeAtIndex:2]で与えられます。 Sending a result the range(at:) message and passing 0 is equivalent to [result range].

If the result returned is non-nil, then [result range] will always be a valid range, so it is not necessary to compare it against {NSNotFound, 0}. However, for some regular expressions (though not the example pattern) some capture groups may or may not participate in a given match. If a given capture group does not participate in a given match, then [result rangeAtIndex:idx] will return {NSNotFound, 0}. 返される結果がnilでないならば、[result range]は常に有効な範囲であるので、それを{NSNotFound, 0}と比較することは必要ではありません。しかし、若干の正規表現では（例パターンはそうでないけれども）いくつかの捕獲グループが、ある与えられたマッチに関与するかもしれないし、しないかもしれません。ある捕獲グループが与えられたマッチに関与しないならば、 [result rangeAtIndex:idx]は{NSNotFound, 0}を返すでしょう。

NSRange rangeOfFirstMatch = [regex rangeOfFirstMatchInString:string options:0 range:NSMakeRange(0, [string length])];
if (!NSEqualRanges(rangeOfFirstMatch, NSMakeRange(NSNotFound, 0))) {
    NSString *substringForFirstMatch = [string substringWithRange:rangeOfFirstMatch];
}

The matches(in:options:range:) returns all the matching results. matches(in:options:range:)は、全てのマッチした結果を返します。

NSArray *matches = [regex matchesInString:string
                                  options:0
                                    range:NSMakeRange(0, [string length])];
for (NSTextCheckingResult *match in matches) {
     NSRange matchRange = [match range];
     NSRange firstHalfRange = [match rangeAtIndex:1];
     NSRange secondHalfRange = [match rangeAtIndex:2];
}

The firstMatch(in:options:range:) method is similar to matches(in:options:range:) but it returns only the first match. firstMatch(in:options:range:)メソッドはmatches(in:options:range:)に似ています、しかしそれは最初のマッチだけを返します。

NSTextCheckingResult *match = [regex firstMatchInString:string
                                                options:0
                                                  range:NSMakeRange(0, [string length])];
if (match) {
    NSRange matchRange = [match range];
    NSRange firstHalfRange = [match rangeAtIndex:1];
    NSRange secondHalfRange = [match rangeAtIndex:2];
 }

The Block enumeration method enumerateMatches(in:options:range:using:) is the most general and flexible of the matching methods of NSRegularExpression. It allows you to iterate through matches in a string, performing arbitrary actions on each as specified by the code in the Block and to stop partway through if desired. In the following example case, the iteration is stopped after a certain number of matches have been found. 「ブロック」列挙メソッドenumerateMatches(in:options:range:using:)は、NSRegularExpressionのマッチング・メソッドの最も一般的で柔軟性に富むものです。それはある文字列の中のマッチすべてに対して、それぞれにおいて「ブロック」のコードで指定される通りに任意のアクションの実行を繰り返すこと、そして希望する場合には最後までの途中で中止することをあなたに可能にします。以下の例の場合には、繰り返しは、特定の数のマッチが見つけられた後で中止されます。

If neither of the special options reportProgress or reportCompletion is specified, then the result argument to the Block is guaranteed to be non-nil, and as mentioned before, it is guaranteed to have a valid overall range. See NSRegularExpression.MatchingOptions for the significance of reportProgress or reportCompletion. 特別なオプションreportProgressまたはreportCompletionのどちらも指定されないならば、「ブロック」に対する結果引数は、nilでないことを保証されます、そして前に言及されたように、それは有効な全体的な範囲を持つと保証されます。NSRegularExpression.MatchingOptionsをreportProgressやreportCompletionの意義のために見てください。

__block NSUInteger count = 0;
[regex enumerateMatchesInString:string options:0 range:NSMakeRange(0, [string length]) usingBlock:^(NSTextCheckingResult *match, NSMatchingFlags flags, BOOL *stop){
     NSRange matchRange = [match range];
     NSRange firstHalfRange = [match rangeAtIndex:1];
     NSRange secondHalfRange = [match rangeAtIndex:2];
     if (++count >= 100) *stop = YES;
}];

NSRegularExpression also provides simple methods for performing find-and-replace operations on a string. The following example returns a modified copy, but there is a corresponding method for modifying a mutable string in place. The template specifies what is to be used to replace each match, with $0 representing the contents of the overall matched range, $1 representing the contents of the first capture group, and so on. In this case, the template reverses the two letters of the word. NSRegularExpressionはまた、単純なメソッドを検索置換操作を文字列において実行するために提供します。以下の例は修正されたコピーを返します、しかし可変文字列をその場で修正する対応するメソッドがあります。テンプレート（ひな形）は、全体的なマッチされた範囲の内容を表す$0、そして最初の捕獲グループ内容を表す$1など、各マッチを置換するために何が使われることになるかを指定します。この場合では、テンプレートは語の２つの文字を逆にします。

NSString *modifiedString = [regex stringByReplacingMatchesInString:string
                                                           options:0
                                                             range:NSMakeRange(0, [string length])
                                                      withTemplate:@"$2$1"];

Concurrency and Thread Safety 並列性とスレッド安全

NSRegularExpression is designed to be immutable and thread safe, so that a single instance can be used in matching operations on multiple threads at once. However, the string on which it is operating should not be mutated during the course of a matching operation, whether from another thread or from within the Block used in the iteration. NSRegularExpressionはイミュータブル（不変）でスレッドセーフに設計されます、そのため単一のインスタンスが同時に複数のスレッドの上でのマッチング操作で使われることができます。しかしながら、別のスレッド由来かまたは繰り返しにおいて使われる「ブロック」内部由来かどうかに関係なく、それが作用している文字列がマッチング操作の経過の間に変化しないようにする必要があります。

Regular Expression Syntax 正規表現構文

The following tables describe the character expressions used by the regular expression to match patterns within a string, the pattern operators that specify how many times a pattern is matched and additional matching restrictions, and the last table specifies flags that can be included in the regular expression pattern that specify search behavior over multiple lines (these flags can also be specified using the NSRegularExpression.Options option flags. 以下の表は、ある文字列内部においてさまざまな類型（パターン）にマッチするために正規表現において使われる文字表現、どのくらい多くの回数あるパターンがマッチするかを、そして特別なマッチング制約を指定するパターン演算子を解説します、そして最後の表は正規表現パターンに含めることが出来るフラグを指定します、それは複数行にわたる検索挙動を指定します（これらのフラグはまた、NSRegularExpression.Optionsオプションフラグを使って指定されることができます）。

Regular Expression Metacharacters 正規表現メタ文字

Table 1 describe the character sequences used to match characters within a string. 表 1は、ある文字列内のなんらかの文字にマッチするために使われる文字表記を記述します。

Regular Expression Operators 正規表現演算子

Table 2 defines the regular expression operators. 表 2は正規表現演算子を定義します。

Template Matching Format テンプレートマッチング書式

The NSRegularExpression class provides find-and-replace methods for both immutable and mutable strings using the technique of template matching. Table 3 describes the syntax. NSRegularExpressionクラスは、検索置換メソッドをテンプレート（ひな形）マッチングのテクニックを使用して不変および可変の文字列両方のために用意します。表 3は、構文を記述します。

The replacement string is treated as a template, with $0 being replaced by the contents of the matched range, $1 by the contents of the first capture group, and so on. Additional digits beyond the maximum required to represent the number of capture groups will be treated as ordinary characters, as will a $ not followed by digits. Backslash will escape both $ and \. 置き換え文字列はテンプレートとしてみなされ、$0はマッチされた範囲の内容に、$1は最初の捕獲グループの内容等々によって取り替えられます。捕獲グループの数を表すのに必要とされる最大を越えた追加の桁、そして桁が続かない$もまた普通の文字とみなされます。バックスラッシュは、$と\をエスケープします。

Flag Options フラグ・オプション

The following flags control various aspects of regular expression matching. These flag values may be specified within the pattern using the (?ismx-ismx) pattern options. Equivalent behaviors can be specified for the entire pattern when an NSRegularExpression is initialized, using the NSRegularExpression.Options option flags. 以下のフラグは、正規表現マッチングのさまざまな面を制御します。これらのフラグ値は、パターンの範囲内で(?ismx-ismx)パターン・オプションを使って指定されことができます。同等の挙動は、パターン全体に対してNSRegularExpressionが初期化される時に、NSRegularExpression.Optionsオプション・フラグを使って指定されることができます。

Performance 性能

NSRegularExpression implements a nondeterministic finite automaton matching engine. As such, complex regular expression patterns containing multiple * or + operators may result in poor performance when attempting to perform matches — particularly failing to match a given input. For more information, see the “Performance Tips” section of the ICU User Guide. NSRegularExpressionは、ある非決定性有限オートマトンマッチエンジンを実装します。そういうことで、*や+演算子を含む複雑な正規表現式は、マッチ実行を試みようとすれば — とりわけ与えられた入力にマッチするのに失敗すれば、貧弱な性能という結果になります。さらなる情報として、ICUユーザガイドの“Performance Tips”の節を見てください。

ICU License ICUライセンス

Table 1, Table 2, Table 3, Table 4 are reproduced from the ICU User Guide, Copyright (c) 2000 - 2009 IBM and Others, which are licensed under the following terms: 表 1、表 2、表 3、表 4は、「ICUユーザー・ガイド」、著作権(c) 2000-2009 IBMその他、から転載されます、それは次の条項の下で認可されます：

COPYRIGHT AND PERMISSION NOTICE

Copyright (c) 1995-2009 International Business Machines Corporation and others. All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, provided that the above copyright notice(s) and this permission notice appear in all copies of the Software and that both the above copyright notice(s) and this permission notice appear in supporting documentation.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization of the copyright holder.

All trademarks and registered trademarks mentioned herein are the property of their respective owners.