Updates for core/{pattern,regexp,stopwatch,duration}.dart

tool/input_sdk/lib/core/pattern.dart

Index: tool/input_sdk/lib/core/pattern.dart
diff --git a/tool/input_sdk/lib/core/pattern.dart b/tool/input_sdk/lib/core/pattern.dart
index cf898afff379470ed7a4baf08cc1e548e30831ee..7f32c7259193813479a861d1930189e7337295d7 100644
--- a/tool/input_sdk/lib/core/pattern.dart
+++ b/tool/input_sdk/lib/core/pattern.dart
@@ -17,8 +17,10 @@ abstract class Pattern {
    *
    * If [start] is provided, matching will start at that index.
    *
-   * The iterable will contain all the non-overlapping matches of the
-   * pattern on the string, ordered by start index.
+   * The returned iterable lazily computes all the non-overlapping matches
+   * of the pattern on the string, ordered by start index.
+   * If a user only requests the first
+   * match, this function should not compute all possible matches.
    *
    * The matches are found by repeatedly finding the first match
    * of the pattern on the string, starting from the end of the previous
@@ -40,3 +42,90 @@ abstract class Pattern {
    */
   Match matchAsPrefix(String string, [int start = 0]);
 }
+
+/**
+ * A result from searching within a string.
+ *
+ * A Match or an [Iterable] of Match objects is returned from [Pattern]
+ * matching methods.
+ *
+ * The following example finds all matches of a [RegExp] in a [String]
+ * and iterates through the returned iterable of Match objects.
+ *
+ *     RegExp exp = new RegExp(r"(\w+)");
+ *     String str = "Parse my string";
+ *     Iterable<Match> matches = exp.allMatches(str);
+ *     for (Match m in matches) {
+ *       String match = m.group(0);
+ *       print(match);
+ *     }
+ *
+ * The output of the example is:
+ *
+ *     Parse
+ *     my
+ *     string
+ *
+ * Some patterns, regular expressions in particular, may record subtrings
+ * that were part of the matching. These are called _groups_ in the Match
+ * object. Some patterns may never have any groups, and their matches always
+ * have zero [groupCount].
+ */
+abstract class Match {
+  /**
+   * Returns the index in the string where the match starts.
+   */
+  int get start;
+
+  /**
+   * Returns the index in the string after the last character of the
+   * match.
+   */
+  int get end;
+
+  /**
+   * Returns the string matched by the given [group].
+   *
+   * If [group] is 0, returns the match of the pattern.
+   *
+   * The result may be `null` if the pattern didn't assign a value to it
+   * as part of this match.
+   */
+  String group(int group);
+
+  /**
+   * Returns the string matched by the given [group].
+   *
+   * If [group] is 0, returns the match of the pattern.
+   *
+   * Short alias for [Match.group].
+   */
+  String operator [](int group);
+
+  /**
+   * Returns a list of the groups with the given indices.
+   *
+   * The list contains the strings returned by [group] for each index in
+   * [groupIndices].
+   */
+  List<String> groups(List<int> groupIndices);
+
+  /**
+   * Returns the number of captured groups in the match.
+   *
+   * Some patterns may capture parts of the input that was used to
+   * compute the full match. This is the number of captured groups,
+   * which is also the maximal allowed argument to the [group] method.
+   */
+  int get groupCount;
+
+  /**
+   * The string on which this match was computed.
+   */
+  String get input;
+
+  /**
+   * The pattern used to search in [input].
+   */
+  Pattern get pattern;
+}