jdk-sandbox: comparison src/java.base/share/classes/java/util/regex/Matcher.java

equal deleted inserted replaced

-:ede65c4fb6da
+:d52bba1f19aa
 /*
-* Copyright (c) 1999, 2015, Oracle and/or its affiliates. All rights reserved.
+* Copyright (c) 1999, 2018, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 import java.util.function.Function;
 import java.util.stream.Stream;
 import java.util.stream.StreamSupport;
 /**
-* An engine that performs match operations on a {@linkplain java.lang.CharSequence
+* An engine that performs match operations on a {@linkplain
-* character sequence} by interpreting a {@link Pattern}.
+* java.lang.CharSequence character sequence} by interpreting a {@link Pattern}.
 *
 * <p> A matcher is created from a pattern by invoking the pattern's {@link
 * Pattern#matcher matcher} method.  Once created, a matcher can be used to
 * perform three different kinds of match operations:
 *
 *   input sequence against the pattern.  </p></li>
 *
 *   <li><p> The {@link #lookingAt lookingAt} method attempts to match the
 *   input sequence, starting at the beginning, against the pattern.  </p></li>
 *
-*   <li><p> The {@link #find find} method scans the input sequence looking for
+*   <li><p> The {@link #find find} method scans the input sequence looking
-*   the next subsequence that matches the pattern.  </p></li>
+*   for the next subsequence that matches the pattern.  </p></li>
 *
 * </ul>
 *
 * <p> Each of these methods returns a boolean indicating success or failure.
 * More information about a successful match can be obtained by querying the
 * state of the matcher.
 *
 * <p> A matcher finds matches in a subset of its input called the
 * <i>region</i>. By default, the region contains all of the matcher's input.
-* The region can be modified via the {@link #region region} method and queried
+* The region can be modified via the {@link #region(int, int) region} method
-* via the {@link #regionStart regionStart} and {@link #regionEnd regionEnd}
+* and queried via the {@link #regionStart() regionStart} and {@link
-* methods. The way that the region boundaries interact with some pattern
+* #regionEnd() regionEnd} methods. The way that the region boundaries interact
-* constructs can be changed. See {@link #useAnchoringBounds
+* with some pattern constructs can be changed. See {@link
-* useAnchoringBounds} and {@link #useTransparentBounds useTransparentBounds}
+* #useAnchoringBounds(boolean) useAnchoringBounds} and {@link
-* for more details.
+* #useTransparentBounds(boolean) useTransparentBounds} for more details.
 *
 * <p> This class also defines methods for replacing matched subsequences with
 * new strings whose contents can, if desired, be computed from the match
 * result.  The {@link #appendReplacement appendReplacement} and {@link
 * #appendTail appendTail} methods can be used in tandem in order to collect
 /**
 * Returns the input subsequence matched by the previous match.
 *
 * <p> For a matcher <i>m</i> with input sequence <i>s</i>,
 * the expressions <i>m.</i>{@code group()} and
-* <i>s.</i>{@code substring(}<i>m.</i>{@code start(),}&nbsp;<i>m.</i>{@code end())}
+* <i>s.</i>{@code substring(}<i>m.</i>{@code start(),}&nbsp;<i>m.</i>
-* are equivalent.  </p>
+* {@code end())} are equivalent.  </p>
 *
 * <p> Note that some patterns, for example {@code a*}, match the empty
 * string.  This method will return the empty string when the pattern
 * successfully matches the empty string in the input.  </p>
 *
 return getSubSequence(groups[group * 2], groups[group * 2 + 1]).toString();
 }
 /**
 * Returns the input subsequence captured by the given
-* <a href="Pattern.html#groupname">named-capturing group</a> during the previous
+* <a href="Pattern.html#groupname">named-capturing group</a> during the
-* match operation.
+* previous match operation.
 *
 * <p> If the match was successful but the group specified failed to match
 * any part of the input sequence, then {@code null} is returned. Note
 * that some groups, for example {@code (a*)}, match the empty string.
 * This method will return the empty string when such a group successfully
 * treated as references to captured subsequences as described above, and
 * backslashes are used to escape literal characters in the replacement
 * string.
 *
 * <p> This method is intended to be used in a loop together with the
-* {@link #appendTail appendTail} and {@link #find find} methods.  The
+* {@link #appendTail(StringBuffer) appendTail} and {@link #find() find}
-* following code, for example, writes {@code one dog two dogs in the
+* methods.  The following code, for example, writes {@code one dog two dogs
-* yard} to the standard-output stream: </p>
+* in the yard} to the standard-output stream: </p>
 *
 * <blockquote><pre>
 * Pattern p = Pattern.compile("cat");
 * Matcher m = p.matcher("one cat two cats in the yard");
 * StringBuffer sb = new StringBuffer();
 * treated as references to captured subsequences as described above, and
 * backslashes are used to escape literal characters in the replacement
 * string.
 *
 * <p> This method is intended to be used in a loop together with the
-* {@link #appendTail appendTail} and {@link #find find} methods.  The
+* {@link #appendTail(StringBuilder) appendTail} and
-* following code, for example, writes {@code one dog two dogs in the
+* {@link #find() find} methods. The following code, for example, writes
-* yard} to the standard-output stream: </p>
+* {@code one dog two dogs in the yard} to the standard-output stream: </p>
 *
 * <blockquote><pre>
 * Pattern p = Pattern.compile("cat");
 * Matcher m = p.matcher("one cat two cats in the yard");
 * StringBuilder sb = new StringBuilder();
 * Implements a terminal append-and-replace step.
 *
 * <p> This method reads characters from the input sequence, starting at
 * the append position, and appends them to the given string buffer.  It is
 * intended to be invoked after one or more invocations of the {@link
-* #appendReplacement appendReplacement} method in order to copy the
+* #appendReplacement(StringBuffer, String) appendReplacement} method in
-* remainder of the input sequence.  </p>
+* order to copy the remainder of the input sequence.  </p>
 *
 * @param  sb
 *         The target string buffer
 *
 * @return  The target string buffer
 * Implements a terminal append-and-replace step.
 *
 * <p> This method reads characters from the input sequence, starting at
 * the append position, and appends them to the given string builder.  It is
 * intended to be invoked after one or more invocations of the {@link
-* #appendReplacement appendReplacement} method in order to copy the
+* #appendReplacement(StringBuilder, String)
-* remainder of the input sequence.  </p>
+* appendReplacement} method in order to copy the remainder of the input
+* sequence.  </p>
 *
 * @param  sb
 *         The target string builder
 *
 * @return  The target string builder
 * method resets the matcher, and then sets the region to start at the
 * index specified by the {@code start} parameter and end at the
 * index specified by the {@code end} parameter.
 *
 * <p>Depending on the transparency and anchoring being used (see
-* {@link #useTransparentBounds useTransparentBounds} and
+* {@link #useTransparentBounds(boolean) useTransparentBounds} and
-* {@link #useAnchoringBounds useAnchoringBounds}), certain constructs such
+* {@link #useAnchoringBounds(boolean) useAnchoringBounds}), certain
-* as anchors may behave differently at or around the boundaries of the
+* constructs such as anchors may behave differently at or around the
-* region.
+* boundaries of the region.
 *
 * @param  start
 *         The index to start searching at (inclusive)
 * @param  end
 *         The index to end searching at (exclusive)
 }
 /**
 * Reports the start index of this matcher's region. The
 * searches this matcher conducts are limited to finding matches
-* within {@link #regionStart regionStart} (inclusive) and
+* within {@link #regionStart() regionStart} (inclusive) and
-* {@link #regionEnd regionEnd} (exclusive).
+* {@link #regionEnd() regionEnd} (exclusive).
 *
 * @return  The starting point of this matcher's region
 * @since 1.5
 */
 public int regionStart() {
 }
 /**
 * Reports the end index (exclusive) of this matcher's region.
 * The searches this matcher conducts are limited to finding matches
-* within {@link #regionStart regionStart} (inclusive) and
+* within {@link #regionStart() regionStart} (inclusive) and
-* {@link #regionEnd regionEnd} (exclusive).
+* {@link #regionEnd() regionEnd} (exclusive).
 *
 * @return  the ending point of this matcher's region
 * @since 1.5
 */
 public int regionEnd() {
 *
 * <p> This method returns {@code true} if this matcher uses
 * <i>transparent</i> bounds, {@code false} if it uses <i>opaque</i>
 * bounds.
 *
-* <p> See {@link #useTransparentBounds useTransparentBounds} for a
+* <p> See {@link #useTransparentBounds(boolean) useTransparentBounds} for a
 * description of transparent and opaque bounds.
 *
 * <p> By default, a matcher uses opaque region boundaries.
 *
 * @return {@code true} iff this matcher is using transparent bounds,
 * Queries the anchoring of region bounds for this matcher.
 *
 * <p> This method returns {@code true} if this matcher uses
 * <i>anchoring</i> bounds, {@code false} otherwise.
 *
-* <p> See {@link #useAnchoringBounds useAnchoringBounds} for a
+* <p> See {@link #useAnchoringBounds(boolean) useAnchoringBounds} for a
 * description of anchoring bounds.
 *
 * <p> By default, a matcher uses anchoring region boundaries.
 *
 * @return {@code true} iff this matcher is using anchoring bounds,
 int getTextLength() {
 return text.length();
 }
 /**
-* Generates a String from this Matcher's input in the specified range.
+* Generates a String from this matcher's input in the specified range.
 *
 * @param  beginIndex   the beginning index, inclusive
 * @param  endIndex     the ending index, exclusive
-* @return A String generated from this Matcher's input
+* @return A String generated from this matcher's input
 */
 CharSequence getSubSequence(int beginIndex, int endIndex) {
 return text.subSequence(beginIndex, endIndex);
 }
 /**
-* Returns this Matcher's input character at index i.
+* Returns this matcher's input character at index i.
 *
 * @return A char from the specified index
 */
 char charAt(int i) {
 return text.charAt(i);

changeset 50340	d52bba1f19aa
parent 47216	71c04702a3d5
child 58242	94bb65cb37d3