1 /*
2 * Copyright 1999-2008 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package java.util.regex;
27
28
29 /**
30 * An engine that performs match operations on a {@link java.lang.CharSequence
31 * </code>character sequence<code>} by interpreting a {@link Pattern}.
32 *
33 * <p> A matcher is created from a pattern by invoking the pattern's {@link
34 * Pattern#matcher matcher} method. Once created, a matcher can be used to
35 * perform three different kinds of match operations:
36 *
37 * <ul>
38 *
39 * <li><p> The {@link #matches matches} method attempts to match the entire
40 * input sequence against the pattern. </p></li>
41 *
42 * <li><p> The {@link #lookingAt lookingAt} method attempts to match the
43 * input sequence, starting at the beginning, against the pattern. </p></li>
44 *
45 * <li><p> The {@link #find find} method scans the input sequence looking for
46 * the next subsequence that matches the pattern. </p></li>
47 *
48 * </ul>
49 *
50 * <p> Each of these methods returns a boolean indicating success or failure.
51 * More information about a successful match can be obtained by querying the
52 * state of the matcher.
53 *
54 * <p> A matcher finds matches in a subset of its input called the
55 * <i>region</i>. By default, the region contains all of the matcher's input.
56 * The region can be modified via the{@link #region region} method and queried
57 * via the {@link #regionStart regionStart} and {@link #regionEnd regionEnd}
58 * methods. The way that the region boundaries interact with some pattern
59 * constructs can be changed. See {@link #useAnchoringBounds
60 * useAnchoringBounds} and {@link #useTransparentBounds useTransparentBounds}
61 * for more details.
62 *
63 * <p> This class also defines methods for replacing matched subsequences with
64 * new strings whose contents can, if desired, be computed from the match
65 * result. The {@link #appendReplacement appendReplacement} and {@link
66 * #appendTail appendTail} methods can be used in tandem in order to collect
67 * the result into an existing string buffer, or the more convenient {@link
68 * #replaceAll replaceAll} method can be used to create a string in which every
69 * matching subsequence in the input sequence is replaced.
70 *
71 * <p> The explicit state of a matcher includes the start and end indices of
72 * the most recent successful match. It also includes the start and end
73 * indices of the input subsequence captured by each <a
74 * href="Pattern.html#cg">capturing group</a> in the pattern as well as a total
75 * count of such subsequences. As a convenience, methods are also provided for
76 * returning these captured subsequences in string form.
77 *
78 * <p> The explicit state of a matcher is initially undefined; attempting to
79 * query any part of it before a successful match will cause an {@link
80 * IllegalStateException} to be thrown. The explicit state of a matcher is
81 * recomputed by every match operation.
82 *
83 * <p> The implicit state of a matcher includes the input character sequence as
84 * well as the <i>append position</i>, which is initially zero and is updated
85 * by the {@link #appendReplacement appendReplacement} method.
86 *
87 * <p> A matcher may be reset explicitly by invoking its {@link #reset()}
88 * method or, if a new input sequence is desired, its {@link
89 * #reset(java.lang.CharSequence) reset(CharSequence)} method. Resetting a
90 * matcher discards its explicit state information and sets the append position
91 * to zero.
92 *
93 * <p> Instances of this class are not safe for use by multiple concurrent
94 * threads. </p>
95 *
96 *
97 * @author Mike McCloskey
98 * @author Mark Reinhold
99 * @author JSR-51 Expert Group
100 * @since 1.4
101 * @spec JSR-51
102 */
103
104 public final class Matcher implements MatchResult {
105
106 /**
107 * The Pattern object that created this Matcher.
108 */
109 Pattern parentPattern;
110
111 /**
112 * The storage used by groups. They may contain invalid values if
113 * a group was skipped during the matching.
114 */
115 int[] groups;
116
117 /**
118 * The range within the sequence that is to be matched. Anchors
119 * will match at these "hard" boundaries. Changing the region
120 * changes these values.
121 */
122 int from, to;
123
124 /**
125 * Lookbehind uses this value to ensure that the subexpression
126 * match ends at the point where the lookbehind was encountered.
127 */
128 int lookbehindTo;
129
130 /**
131 * The original string being matched.
132 */
133 CharSequence text;
134
135 /**
136 * Matcher state used by the last node. NOANCHOR is used when a
137 * match does not have to consume all of the input. ENDANCHOR is
138 * the mode used for matching all the input.
139 */
140 static final int ENDANCHOR = 1;
141 static final int NOANCHOR = 0;
142 int acceptMode = NOANCHOR;
143
144 /**
145 * The range of string that last matched the pattern. If the last
146 * match failed then first is -1; last initially holds 0 then it
147 * holds the index of the end of the last match (which is where the
148 * next search starts).
149 */
150 int first = -1, last = 0;
151
152 /**
153 * The end index of what matched in the last match operation.
154 */
155 int oldLast = -1;
156
157 /**
158 * The index of the last position appended in a substitution.
159 */
160 int lastAppendPosition = 0;
161
162 /**
163 * Storage used by nodes to tell what repetition they are on in
164 * a pattern, and where groups begin. The nodes themselves are stateless,
165 * so they rely on this field to hold state during a match.
166 */
167 int[] locals;
168
169 /**
170 * Boolean indicating whether or not more input could change
171 * the results of the last match.
172 *
173 * If hitEnd is true, and a match was found, then more input
174 * might cause a different match to be found.
175 * If hitEnd is true and a match was not found, then more
176 * input could cause a match to be found.
177 * If hitEnd is false and a match was found, then more input
178 * will not change the match.
179 * If hitEnd is false and a match was not found, then more
180 * input will not cause a match to be found.
181 */
182 boolean hitEnd;
183
184 /**
185 * Boolean indicating whether or not more input could change
186 * a positive match into a negative one.
187 *
188 * If requireEnd is true, and a match was found, then more
189 * input could cause the match to be lost.
190 * If requireEnd is false and a match was found, then more
191 * input might change the match but the match won't be lost.
192 * If a match was not found, then requireEnd has no meaning.
193 */
194 boolean requireEnd;
195
196 /**
197 * If transparentBounds is true then the boundaries of this
198 * matcher's region are transparent to lookahead, lookbehind,
199 * and boundary matching constructs that try to see beyond them.
200 */
201 boolean transparentBounds = false;
202
203 /**
204 * If anchoringBounds is true then the boundaries of this
205 * matcher's region match anchors such as ^ and $.
206 */
207 boolean anchoringBounds = true;
208
209 /**
210 * No default constructor.
211 */
212 Matcher() {
213 }
214
215 /**
216 * All matchers have the state used by Pattern during a match.
217 */
218 Matcher(Pattern parent, CharSequence text) {
219 this.parentPattern = parent;
220 this.text = text;
221
222 // Allocate state storage
223 int parentGroupCount = Math.max(parent.capturingGroupCount, 10);
224 groups = new int[parentGroupCount * 2];
225 locals = new int[parent.localCount];
226
227 // Put fields into initial states
228 reset();
229 }
230
231 /**
232 * Returns the pattern that is interpreted by this matcher.
233 *
234 * @return The pattern for which this matcher was created
235 */
236 public Pattern pattern() {
237 return parentPattern;
238 }
239
240 /**
241 * Returns the match state of this matcher as a {@link MatchResult}.
242 * The result is unaffected by subsequent operations performed upon this
243 * matcher.
244 *
245 * @return a <code>MatchResult</code> with the state of this matcher
246 * @since 1.5
247 */
248 public MatchResult toMatchResult() {
249 Matcher result = new Matcher(this.parentPattern, text.toString());
250 result.first = this.first;
251 result.last = this.last;
252 result.groups = this.groups.clone();
253 return result;
254 }
255
256 /**
257 * Changes the <tt>Pattern</tt> that this <tt>Matcher</tt> uses to
258 * find matches with.
259 *
260 * <p> This method causes this matcher to lose information
261 * about the groups of the last match that occurred. The
262 * matcher's position in the input is maintained and its
263 * last append position is unaffected.</p>
264 *
265 * @param newPattern
266 * The new pattern used by this matcher
267 * @return This matcher
268 * @throws IllegalArgumentException
269 * If newPattern is <tt>null</tt>
270 * @since 1.5
271 */
272 public Matcher usePattern(Pattern newPattern) {
273 if (newPattern == null)
274 throw new IllegalArgumentException("Pattern cannot be null");
275 parentPattern = newPattern;
276
277 // Reallocate state storage
278 int parentGroupCount = Math.max(newPattern.capturingGroupCount, 10);
279 groups = new int[parentGroupCount * 2];
280 locals = new int[newPattern.localCount];
281 for (int i = 0; i < groups.length; i++)
282 groups[i] = -1;
283 for (int i = 0; i < locals.length; i++)
284 locals[i] = -1;
285 return this;
286 }
287
288 /**
289 * Resets this matcher.
290 *
291 * <p> Resetting a matcher discards all of its explicit state information
292 * and sets its append position to zero. The matcher's region is set to the
293 * default region, which is its entire character sequence. The anchoring
294 * and transparency of this matcher's region boundaries are unaffected.
295 *
296 * @return This matcher
297 */
298 public Matcher reset() {
299 first = -1;
300 last = 0;
301 oldLast = -1;
302 for(int i=0; i<groups.length; i++)
303 groups[i] = -1;
304 for(int i=0; i<locals.length; i++)
305 locals[i] = -1;
306 lastAppendPosition = 0;
307 from = 0;
308 to = getTextLength();
309 return this;
310 }
311
312 /**
313 * Resets this matcher with a new input sequence.
314 *
315 * <p> Resetting a matcher discards all of its explicit state information
316 * and sets its append position to zero. The matcher's region is set to
317 * the default region, which is its entire character sequence. The
318 * anchoring and transparency of this matcher's region boundaries are
319 * unaffected.
320 *
321 * @param input
322 * The new input character sequence
323 *
324 * @return This matcher
325 */
326 public Matcher reset(CharSequence input) {
327 text = input;
328 return reset();
329 }
330
331 /**
332 * Returns the start index of the previous match. </p>
333 *
334 * @return The index of the first character matched
335 *
336 * @throws IllegalStateException
337 * If no match has yet been attempted,
338 * or if the previous match operation failed
339 */
340 public int start() {
341 if (first < 0)
342 throw new IllegalStateException("No match available");
343 return first;
344 }
345
346 /**
347 * Returns the start index of the subsequence captured by the given group
348 * during the previous match operation.
349 *
350 * <p> <a href="Pattern.html#cg">Capturing groups</a> are indexed from left
351 * to right, starting at one. Group zero denotes the entire pattern, so
352 * the expression <i>m.</i><tt>start(0)</tt> is equivalent to
353 * <i>m.</i><tt>start()</tt>. </p>
354 *
355 * @param group
356 * The index of a capturing group in this matcher's pattern
357 *
358 * @return The index of the first character captured by the group,
359 * or <tt>-1</tt> if the match was successful but the group
360 * itself did not match anything
361 *
362 * @throws IllegalStateException
363 * If no match has yet been attempted,
364 * or if the previous match operation failed
365 *
366 * @throws IndexOutOfBoundsException
367 * If there is no capturing group in the pattern
368 * with the given index
369 */
370 public int start(int group) {
371 if (first < 0)
372 throw new IllegalStateException("No match available");
373 if (group > groupCount())
374 throw new IndexOutOfBoundsException("No group " + group);
375 return groups[group * 2];
376 }
377
378 /**
379 * Returns the offset after the last character matched. </p>
380 *
381 * @return The offset after the last character matched
382 *
383 * @throws IllegalStateException
384 * If no match has yet been attempted,
385 * or if the previous match operation failed
386 */
387 public int end() {
388 if (first < 0)
389 throw new IllegalStateException("No match available");
390 return last;
391 }
392
393 /**
394 * Returns the offset after the last character of the subsequence
395 * captured by the given group during the previous match operation.
396 *
397 * <p> <a href="Pattern.html#cg">Capturing groups</a> are indexed from left
398 * to right, starting at one. Group zero denotes the entire pattern, so
399 * the expression <i>m.</i><tt>end(0)</tt> is equivalent to
400 * <i>m.</i><tt>end()</tt>. </p>
401 *
402 * @param group
403 * The index of a capturing group in this matcher's pattern
404 *
405 * @return The offset after the last character captured by the group,
406 * or <tt>-1</tt> if the match was successful
407 * but the group itself did not match anything
408 *
409 * @throws IllegalStateException
410 * If no match has yet been attempted,
411 * or if the previous match operation failed
412 *
413 * @throws IndexOutOfBoundsException
414 * If there is no capturing group in the pattern
415 * with the given index
416 */
417 public int end(int group) {
418 if (first < 0)
419 throw new IllegalStateException("No match available");
420 if (group > groupCount())
421 throw new IndexOutOfBoundsException("No group " + group);
422 return groups[group * 2 + 1];
423 }
424
425 /**
426 * Returns the input subsequence matched by the previous match.
427 *
428 * <p> For a matcher <i>m</i> with input sequence <i>s</i>,
429 * the expressions <i>m.</i><tt>group()</tt> and
430 * <i>s.</i><tt>substring(</tt><i>m.</i><tt>start(),</tt> <i>m.</i><tt>end())</tt>
431 * are equivalent. </p>
432 *
433 * <p> Note that some patterns, for example <tt>a*</tt>, match the empty
434 * string. This method will return the empty string when the pattern
435 * successfully matches the empty string in the input. </p>
436 *
437 * @return The (possibly empty) subsequence matched by the previous match,
438 * in string form
439 *
440 * @throws IllegalStateException
441 * If no match has yet been attempted,
442 * or if the previous match operation failed
443 */
444 public String group() {
445 return group(0);
446 }
447
448 /**
449 * Returns the input subsequence captured by the given group during the
450 * previous match operation.
451 *
452 * <p> For a matcher <i>m</i>, input sequence <i>s</i>, and group index
453 * <i>g</i>, the expressions <i>m.</i><tt>group(</tt><i>g</i><tt>)</tt> and
454 * <i>s.</i><tt>substring(</tt><i>m.</i><tt>start(</tt><i>g</i><tt>),</tt> <i>m.</i><tt>end(</tt><i>g</i><tt>))</tt>
455 * are equivalent. </p>
456 *
457 * <p> <a href="Pattern.html#cg">Capturing groups</a> are indexed from left
458 * to right, starting at one. Group zero denotes the entire pattern, so
459 * the expression <tt>m.group(0)</tt> is equivalent to <tt>m.group()</tt>.
460 * </p>
461 *
462 * <p> If the match was successful but the group specified failed to match
463 * any part of the input sequence, then <tt>null</tt> is returned. Note
464 * that some groups, for example <tt>(a*)</tt>, match the empty string.
465 * This method will return the empty string when such a group successfully
466 * matches the empty string in the input. </p>
467 *
468 * @param group
469 * The index of a capturing group in this matcher's pattern
470 *
471 * @return The (possibly empty) subsequence captured by the group
472 * during the previous match, or <tt>null</tt> if the group
473 * failed to match part of the input
474 *
475 * @throws IllegalStateException
476 * If no match has yet been attempted,
477 * or if the previous match operation failed
478 *
479 * @throws IndexOutOfBoundsException
480 * If there is no capturing group in the pattern
481 * with the given index
482 */
483 public String group(int group) {
484 if (first < 0)
485 throw new IllegalStateException("No match found");
486 if (group < 0 || group > groupCount())
487 throw new IndexOutOfBoundsException("No group " + group);
488 if ((groups[group*2] == -1) || (groups[group*2+1] == -1))
489 return null;
490 return getSubSequence(groups[group * 2], groups[group * 2 + 1]).toString();
491 }
492
493 /**
494 * Returns the input subsequence captured by the given
495 * <a href="Pattern.html#groupname">named-capturing group</a> during the previous
496 * match operation.
497 *
498 * <p> If the match was successful but the group specified failed to match
499 * any part of the input sequence, then <tt>null</tt> is returned. Note
500 * that some groups, for example <tt>(a*)</tt>, match the empty string.
501 * This method will return the empty string when such a group successfully
502 * matches the empty string in the input. </p>
503 *
504 * @param name
505 * The name of a named-capturing group in this matcher's pattern
506 *
507 * @return The (possibly empty) subsequence captured by the named group
508 * during the previous match, or <tt>null</tt> if the group
509 * failed to match part of the input
510 *
511 * @throws IllegalStateException
512 * If no match has yet been attempted,
513 * or if the previous match operation failed
514 *
515 * @throws IllegalArgumentException
516 * If there is no capturing group in the pattern
517 * with the given name
518 */
519 public String group(String name) {
520 if (name == null)
521 throw new NullPointerException("Null group name");
522 if (first < 0)
523 throw new IllegalStateException("No match found");
524 if (!parentPattern.namedGroups().containsKey(name))
525 throw new IllegalArgumentException("No group with name <" + name + ">");
526 int group = parentPattern.namedGroups().get(name);
527 if ((groups[group*2] == -1) || (groups[group*2+1] == -1))
528 return null;
529 return getSubSequence(groups[group * 2], groups[group * 2 + 1]).toString();
530 }
531
532 /**
533 * Returns the number of capturing groups in this matcher's pattern.
534 *
535 * <p> Group zero denotes the entire pattern by convention. It is not
536 * included in this count.
537 *
538 * <p> Any non-negative integer smaller than or equal to the value
539 * returned by this method is guaranteed to be a valid group index for
540 * this matcher. </p>
541 *
542 * @return The number of capturing groups in this matcher's pattern
543 */
544 public int groupCount() {
545 return parentPattern.capturingGroupCount - 1;
546 }
547
548 /**
549 * Attempts to match the entire region against the pattern.
550 *
551 * <p> If the match succeeds then more information can be obtained via the
552 * <tt>start</tt>, <tt>end</tt>, and <tt>group</tt> methods. </p>
553 *
554 * @return <tt>true</tt> if, and only if, the entire region sequence
555 * matches this matcher's pattern
556 */
557 public boolean matches() {
558 return match(from, ENDANCHOR);
559 }
560
561 /**
562 * Attempts to find the next subsequence of the input sequence that matches
563 * the pattern.
564 *
565 * <p> This method starts at the beginning of this matcher's region, or, if
566 * a previous invocation of the method was successful and the matcher has
567 * not since been reset, at the first character not matched by the previous
568 * match.
569 *
570 * <p> If the match succeeds then more information can be obtained via the
571 * <tt>start</tt>, <tt>end</tt>, and <tt>group</tt> methods. </p>
572 *
573 * @return <tt>true</tt> if, and only if, a subsequence of the input
574 * sequence matches this matcher's pattern
575 */
576 public boolean find() {
577 int nextSearchIndex = last;
578 if (nextSearchIndex == first)
579 nextSearchIndex++;
580
581 // If next search starts before region, start it at region
582 if (nextSearchIndex < from)
583 nextSearchIndex = from;
584
585 // If next search starts beyond region then it fails
586 if (nextSearchIndex > to) {
587 for (int i = 0; i < groups.length; i++)
588 groups[i] = -1;
589 return false;
590 }
591 return search(nextSearchIndex);
592 }
593
594 /**
595 * Resets this matcher and then attempts to find the next subsequence of
596 * the input sequence that matches the pattern, starting at the specified
597 * index.
598 *
599 * <p> If the match succeeds then more information can be obtained via the
600 * <tt>start</tt>, <tt>end</tt>, and <tt>group</tt> methods, and subsequent
601 * invocations of the {@link #find()} method will start at the first
602 * character not matched by this match. </p>
603 *
604 * @throws IndexOutOfBoundsException
605 * If start is less than zero or if start is greater than the
606 * length of the input sequence.
607 *
608 * @return <tt>true</tt> if, and only if, a subsequence of the input
609 * sequence starting at the given index matches this matcher's
610 * pattern
611 */
612 public boolean find(int start) {
613 int limit = getTextLength();
614 if ((start < 0) || (start > limit))
615 throw new IndexOutOfBoundsException("Illegal start index");
616 reset();
617 return search(start);
618 }
619
620 /**
621 * Attempts to match the input sequence, starting at the beginning of the
622 * region, against the pattern.
623 *
624 * <p> Like the {@link #matches matches} method, this method always starts
625 * at the beginning of the region; unlike that method, it does not
626 * require that the entire region be matched.
627 *
628 * <p> If the match succeeds then more information can be obtained via the
629 * <tt>start</tt>, <tt>end</tt>, and <tt>group</tt> methods. </p>
630 *
631 * @return <tt>true</tt> if, and only if, a prefix of the input
632 * sequence matches this matcher's pattern
633 */
634 public boolean lookingAt() {
635 return match(from, NOANCHOR);
636 }
637
638 /**
639 * Returns a literal replacement <code>String</code> for the specified
640 * <code>String</code>.
641 *
642 * This method produces a <code>String</code> that will work
643 * as a literal replacement <code>s</code> in the
644 * <code>appendReplacement</code> method of the {@link Matcher} class.
645 * The <code>String</code> produced will match the sequence of characters
646 * in <code>s</code> treated as a literal sequence. Slashes ('\') and
647 * dollar signs ('$') will be given no special meaning.
648 *
649 * @param s The string to be literalized
650 * @return A literal string replacement
651 * @since 1.5
652 */
653 public static String quoteReplacement(String s) {
654 if ((s.indexOf('\\') == -1) && (s.indexOf('$') == -1))
655 return s;
656 StringBuilder sb = new StringBuilder();
657 for (int i=0; i<s.length(); i++) {
658 char c = s.charAt(i);
659 if (c == '\\' || c == '$') {
660 sb.append('\\');
661 }
662 sb.append(c);
663 }
664 return sb.toString();
665 }
666
667 /**
668 * Implements a non-terminal append-and-replace step.
669 *
670 * <p> This method performs the following actions: </p>
671 *
672 * <ol>
673 *
674 * <li><p> It reads characters from the input sequence, starting at the
675 * append position, and appends them to the given string buffer. It
676 * stops after reading the last character preceding the previous match,
677 * that is, the character at index {@link
678 * #start()} <tt>-</tt> <tt>1</tt>. </p></li>
679 *
680 * <li><p> It appends the given replacement string to the string buffer.
681 * </p></li>
682 *
683 * <li><p> It sets the append position of this matcher to the index of
684 * the last character matched, plus one, that is, to {@link #end()}.
685 * </p></li>
686 *
687 * </ol>
688 *
689 * <p> The replacement string may contain references to subsequences
690 * captured during the previous match: Each occurrence of
691 * <tt>$</tt><<i>name</i>> or <tt>$</tt><i>g</i>
692 * will be replaced by the result of evaluating the corresponding
693 * {@link #group(String) group(name)} or {@link #group(int) group(g)</tt>}
694 * respectively. For <tt>$</tt><i>g</i><tt></tt>,
695 * the first number after the <tt>$</tt> is always treated as part of
696 * the group reference. Subsequent numbers are incorporated into g if
697 * they would form a legal group reference. Only the numerals '0'
698 * through '9' are considered as potential components of the group
699 * reference. If the second group matched the string <tt>"foo"</tt>, for
700 * example, then passing the replacement string <tt>"$2bar"</tt> would
701 * cause <tt>"foobar"</tt> to be appended to the string buffer. A dollar
702 * sign (<tt>$</tt>) may be included as a literal in the replacement
703 * string by preceding it with a backslash (<tt>\$</tt>).
704 *
705 * <p> Note that backslashes (<tt>\</tt>) and dollar signs (<tt>$</tt>) in
706 * the replacement string may cause the results to be different than if it
707 * were being treated as a literal replacement string. Dollar signs may be
708 * treated as references to captured subsequences as described above, and
709 * backslashes are used to escape literal characters in the replacement
710 * string.
711 *
712 * <p> This method is intended to be used in a loop together with the
713 * {@link #appendTail appendTail} and {@link #find find} methods. The
714 * following code, for example, writes <tt>one dog two dogs in the
715 * yard</tt> to the standard-output stream: </p>
716 *
717 * <blockquote><pre>
718 * Pattern p = Pattern.compile("cat");
719 * Matcher m = p.matcher("one cat two cats in the yard");
720 * StringBuffer sb = new StringBuffer();
721 * while (m.find()) {
722 * m.appendReplacement(sb, "dog");
723 * }
724 * m.appendTail(sb);
725 * System.out.println(sb.toString());</pre></blockquote>
726 *
727 * @param sb
728 * The target string buffer
729 *
730 * @param replacement
731 * The replacement string
732 *
733 * @return This matcher
734 *
735 * @throws IllegalStateException
736 * If no match has yet been attempted,
737 * or if the previous match operation failed
738 *
739 * @throws IllegalArgumentException
740 * If the replacement string refers to a named-capturing
741 * group that does not exist in the pattern
742 *
743 * @throws IndexOutOfBoundsException
744 * If the replacement string refers to a capturing group
745 * that does not exist in the pattern
746 */
747 public Matcher appendReplacement(StringBuffer sb, String replacement) {
748
749 // If no match, return error
750 if (first < 0)
751 throw new IllegalStateException("No match available");
752
753 // Process substitution string to replace group references with groups
754 int cursor = 0;
755 StringBuilder result = new StringBuilder();
756
757 while (cursor < replacement.length()) {
758 char nextChar = replacement.charAt(cursor);
759 if (nextChar == '\\') {
760 cursor++;
761 nextChar = replacement.charAt(cursor);
762 result.append(nextChar);
763 cursor++;
764 } else if (nextChar == '$') {
765 // Skip past $
766 cursor++;
767 // A StringIndexOutOfBoundsException is thrown if
768 // this "$" is the last character in replacement
769 // string in current implementation, a IAE might be
770 // more appropriate.
771 nextChar = replacement.charAt(cursor);
772 int refNum = -1;
773 if (nextChar == '<') {
774 cursor++;
775 StringBuilder gsb = new StringBuilder();
776 while (cursor < replacement.length()) {
777 nextChar = replacement.charAt(cursor);
778 if (ASCII.isLower(nextChar) ||
779 ASCII.isUpper(nextChar) ||
780 ASCII.isDigit(nextChar)) {
781 gsb.append(nextChar);
782 cursor++;
783 } else {
784 break;
785 }
786 }
787 if (gsb.length() == 0)
788 throw new IllegalArgumentException(
789 "named capturing group has 0 length name");
790 if (nextChar != '>')
791 throw new IllegalArgumentException(
792 "named capturing group is missing trailing '>'");
793 String gname = gsb.toString();
794 if (!parentPattern.namedGroups().containsKey(gname))
795 throw new IllegalArgumentException(
796 "No group with name <" + gname + ">");
797 refNum = parentPattern.namedGroups().get(gname);
798 cursor++;
799 } else {
800 // The first number is always a group
801 refNum = (int)nextChar - '0';
802 if ((refNum < 0)||(refNum > 9))
803 throw new IllegalArgumentException(
804 "Illegal group reference");
805 cursor++;
806 // Capture the largest legal group string
807 boolean done = false;
808 while (!done) {
809 if (cursor >= replacement.length()) {
810 break;
811 }
812 int nextDigit = replacement.charAt(cursor) - '0';
813 if ((nextDigit < 0)||(nextDigit > 9)) { // not a number
814 break;
815 }
816 int newRefNum = (refNum * 10) + nextDigit;
817 if (groupCount() < newRefNum) {
818 done = true;
819 } else {
820 refNum = newRefNum;
821 cursor++;
822 }
823 }
824 }
825 // Append group
826 if (start(refNum) != -1 && end(refNum) != -1)
827 result.append(text, start(refNum), end(refNum));
828 } else {
829 result.append(nextChar);
830 cursor++;
831 }
832 }
833 // Append the intervening text
834 sb.append(text, lastAppendPosition, first);
835 // Append the match substitution
836 sb.append(result);
837
838 lastAppendPosition = last;
839 return this;
840 }
841
842 /**
843 * Implements a terminal append-and-replace step.
844 *
845 * <p> This method reads characters from the input sequence, starting at
846 * the append position, and appends them to the given string buffer. It is
847 * intended to be invoked after one or more invocations of the {@link
848 * #appendReplacement appendReplacement} method in order to copy the
849 * remainder of the input sequence. </p>
850 *
851 * @param sb
852 * The target string buffer
853 *
854 * @return The target string buffer
855 */
856 public StringBuffer appendTail(StringBuffer sb) {
857 sb.append(text, lastAppendPosition, getTextLength());
858 return sb;
859 }
860
861 /**
862 * Replaces every subsequence of the input sequence that matches the
863 * pattern with the given replacement string.
864 *
865 * <p> This method first resets this matcher. It then scans the input
866 * sequence looking for matches of the pattern. Characters that are not
867 * part of any match are appended directly to the result string; each match
868 * is replaced in the result by the replacement string. The replacement
869 * string may contain references to captured subsequences as in the {@link
870 * #appendReplacement appendReplacement} method.
871 *
872 * <p> Note that backslashes (<tt>\</tt>) and dollar signs (<tt>$</tt>) in
873 * the replacement string may cause the results to be different than if it
874 * were being treated as a literal replacement string. Dollar signs may be
875 * treated as references to captured subsequences as described above, and
876 * backslashes are used to escape literal characters in the replacement
877 * string.
878 *
879 * <p> Given the regular expression <tt>a*b</tt>, the input
880 * <tt>"aabfooaabfooabfoob"</tt>, and the replacement string
881 * <tt>"-"</tt>, an invocation of this method on a matcher for that
882 * expression would yield the string <tt>"-foo-foo-foo-"</tt>.
883 *
884 * <p> Invoking this method changes this matcher's state. If the matcher
885 * is to be used in further matching operations then it should first be
886 * reset. </p>
887 *
888 * @param replacement
889 * The replacement string
890 *
891 * @return The string constructed by replacing each matching subsequence
892 * by the replacement string, substituting captured subsequences
893 * as needed
894 */
895 public String replaceAll(String replacement) {
896 reset();
897 boolean result = find();
898 if (result) {
899 StringBuffer sb = new StringBuffer();
900 do {
901 appendReplacement(sb, replacement);
902 result = find();
903 } while (result);
904 appendTail(sb);
905 return sb.toString();
906 }
907 return text.toString();
908 }
909
910 /**
911 * Replaces the first subsequence of the input sequence that matches the
912 * pattern with the given replacement string.
913 *
914 * <p> This method first resets this matcher. It then scans the input
915 * sequence looking for a match of the pattern. Characters that are not
916 * part of the match are appended directly to the result string; the match
917 * is replaced in the result by the replacement string. The replacement
918 * string may contain references to captured subsequences as in the {@link
919 * #appendReplacement appendReplacement} method.
920 *
921 * <p>Note that backslashes (<tt>\</tt>) and dollar signs (<tt>$</tt>) in
922 * the replacement string may cause the results to be different than if it
923 * were being treated as a literal replacement string. Dollar signs may be
924 * treated as references to captured subsequences as described above, and
925 * backslashes are used to escape literal characters in the replacement
926 * string.
927 *
928 * <p> Given the regular expression <tt>dog</tt>, the input
929 * <tt>"zzzdogzzzdogzzz"</tt>, and the replacement string
930 * <tt>"cat"</tt>, an invocation of this method on a matcher for that
931 * expression would yield the string <tt>"zzzcatzzzdogzzz"</tt>. </p>
932 *
933 * <p> Invoking this method changes this matcher's state. If the matcher
934 * is to be used in further matching operations then it should first be
935 * reset. </p>
936 *
937 * @param replacement
938 * The replacement string
939 * @return The string constructed by replacing the first matching
940 * subsequence by the replacement string, substituting captured
941 * subsequences as needed
942 */
943 public String replaceFirst(String replacement) {
944 if (replacement == null)
945 throw new NullPointerException("replacement");
946 reset();
947 if (!find())
948 return text.toString();
949 StringBuffer sb = new StringBuffer();
950 appendReplacement(sb, replacement);
951 appendTail(sb);
952 return sb.toString();
953 }
954
955 /**
956 * Sets the limits of this matcher's region. The region is the part of the
957 * input sequence that will be searched to find a match. Invoking this
958 * method resets the matcher, and then sets the region to start at the
959 * index specified by the <code>start</code> parameter and end at the
960 * index specified by the <code>end</code> parameter.
961 *
962 * <p>Depending on the transparency and anchoring being used (see
963 * {@link #useTransparentBounds useTransparentBounds} and
964 * {@link #useAnchoringBounds useAnchoringBounds}), certain constructs such
965 * as anchors may behave differently at or around the boundaries of the
966 * region.
967 *
968 * @param start
969 * The index to start searching at (inclusive)
970 * @param end
971 * The index to end searching at (exclusive)
972 * @throws IndexOutOfBoundsException
973 * If start or end is less than zero, if
974 * start is greater than the length of the input sequence, if
975 * end is greater than the length of the input sequence, or if
976 * start is greater than end.
977 * @return this matcher
978 * @since 1.5
979 */
980 public Matcher region(int start, int end) {
981 if ((start < 0) || (start > getTextLength()))
982 throw new IndexOutOfBoundsException("start");
983 if ((end < 0) || (end > getTextLength()))
984 throw new IndexOutOfBoundsException("end");
985 if (start > end)
986 throw new IndexOutOfBoundsException("start > end");
987 reset();
988 from = start;
989 to = end;
990 return this;
991 }
992
993 /**
994 * Reports the start index of this matcher's region. The
995 * searches this matcher conducts are limited to finding matches
996 * within {@link #regionStart regionStart} (inclusive) and
997 * {@link #regionEnd regionEnd} (exclusive).
998 *
999 * @return The starting point of this matcher's region
1000 * @since 1.5
1001 */
1002 public int regionStart() {
1003 return from;
1004 }
1005
1006 /**
1007 * Reports the end index (exclusive) of this matcher's region.
1008 * The searches this matcher conducts are limited to finding matches
1009 * within {@link #regionStart regionStart} (inclusive) and
1010 * {@link #regionEnd regionEnd} (exclusive).
1011 *
1012 * @return the ending point of this matcher's region
1013 * @since 1.5
1014 */
1015 public int regionEnd() {
1016 return to;
1017 }
1018
1019 /**
1020 * Queries the transparency of region bounds for this matcher.
1021 *
1022 * <p> This method returns <tt>true</tt> if this matcher uses
1023 * <i>transparent</i> bounds, <tt>false</tt> if it uses <i>opaque</i>
1024 * bounds.
1025 *
1026 * <p> See {@link #useTransparentBounds useTransparentBounds} for a
1027 * description of transparent and opaque bounds.
1028 *
1029 * <p> By default, a matcher uses opaque region boundaries.
1030 *
1031 * @return <tt>true</tt> iff this matcher is using transparent bounds,
1032 * <tt>false</tt> otherwise.
1033 * @see java.util.regex.Matcher#useTransparentBounds(boolean)
1034 * @since 1.5
1035 */
1036 public boolean hasTransparentBounds() {
1037 return transparentBounds;
1038 }
1039
1040 /**
1041 * Sets the transparency of region bounds for this matcher.
1042 *
1043 * <p> Invoking this method with an argument of <tt>true</tt> will set this
1044 * matcher to use <i>transparent</i> bounds. If the boolean
1045 * argument is <tt>false</tt>, then <i>opaque</i> bounds will be used.
1046 *
1047 * <p> Using transparent bounds, the boundaries of this
1048 * matcher's region are transparent to lookahead, lookbehind,
1049 * and boundary matching constructs. Those constructs can see beyond the
1050 * boundaries of the region to see if a match is appropriate.
1051 *
1052 * <p> Using opaque bounds, the boundaries of this matcher's
1053 * region are opaque to lookahead, lookbehind, and boundary matching
1054 * constructs that may try to see beyond them. Those constructs cannot
1055 * look past the boundaries so they will fail to match anything outside
1056 * of the region.
1057 *
1058 * <p> By default, a matcher uses opaque bounds.
1059 *
1060 * @param b a boolean indicating whether to use opaque or transparent
1061 * regions
1062 * @return this matcher
1063 * @see java.util.regex.Matcher#hasTransparentBounds
1064 * @since 1.5
1065 */
1066 public Matcher useTransparentBounds(boolean b) {
1067 transparentBounds = b;
1068 return this;
1069 }
1070
1071 /**
1072 * Queries the anchoring of region bounds for this matcher.
1073 *
1074 * <p> This method returns <tt>true</tt> if this matcher uses
1075 * <i>anchoring</i> bounds, <tt>false</tt> otherwise.
1076 *
1077 * <p> See {@link #useAnchoringBounds useAnchoringBounds} for a
1078 * description of anchoring bounds.
1079 *
1080 * <p> By default, a matcher uses anchoring region boundaries.
1081 *
1082 * @return <tt>true</tt> iff this matcher is using anchoring bounds,
1083 * <tt>false</tt> otherwise.
1084 * @see java.util.regex.Matcher#useAnchoringBounds(boolean)
1085 * @since 1.5
1086 */
1087 public boolean hasAnchoringBounds() {
1088 return anchoringBounds;
1089 }
1090
1091 /**
1092 * Sets the anchoring of region bounds for this matcher.
1093 *
1094 * <p> Invoking this method with an argument of <tt>true</tt> will set this
1095 * matcher to use <i>anchoring</i> bounds. If the boolean
1096 * argument is <tt>false</tt>, then <i>non-anchoring</i> bounds will be
1097 * used.
1098 *
1099 * <p> Using anchoring bounds, the boundaries of this
1100 * matcher's region match anchors such as ^ and $.
1101 *
1102 * <p> Without anchoring bounds, the boundaries of this
1103 * matcher's region will not match anchors such as ^ and $.
1104 *
1105 * <p> By default, a matcher uses anchoring region boundaries.
1106 *
1107 * @param b a boolean indicating whether or not to use anchoring bounds.
1108 * @return this matcher
1109 * @see java.util.regex.Matcher#hasAnchoringBounds
1110 * @since 1.5
1111 */
1112 public Matcher useAnchoringBounds(boolean b) {
1113 anchoringBounds = b;
1114 return this;
1115 }
1116
1117 /**
1118 * <p>Returns the string representation of this matcher. The
1119 * string representation of a <code>Matcher</code> contains information
1120 * that may be useful for debugging. The exact format is unspecified.
1121 *
1122 * @return The string representation of this matcher
1123 * @since 1.5
1124 */
1125 public String toString() {
1126 StringBuilder sb = new StringBuilder();
1127 sb.append("java.util.regex.Matcher");
1128 sb.append("[pattern=" + pattern());
1129 sb.append(" region=");
1130 sb.append(regionStart() + "," + regionEnd());
1131 sb.append(" lastmatch=");
1132 if ((first >= 0) && (group() != null)) {
1133 sb.append(group());
1134 }
1135 sb.append("]");
1136 return sb.toString();
1137 }
1138
1139 /**
1140 * <p>Returns true if the end of input was hit by the search engine in
1141 * the last match operation performed by this matcher.
1142 *
1143 * <p>When this method returns true, then it is possible that more input
1144 * would have changed the result of the last search.
1145 *
1146 * @return true iff the end of input was hit in the last match; false
1147 * otherwise
1148 * @since 1.5
1149 */
1150 public boolean hitEnd() {
1151 return hitEnd;
1152 }
1153
1154 /**
1155 * <p>Returns true if more input could change a positive match into a
1156 * negative one.
1157 *
1158 * <p>If this method returns true, and a match was found, then more
1159 * input could cause the match to be lost. If this method returns false
1160 * and a match was found, then more input might change the match but the
1161 * match won't be lost. If a match was not found, then requireEnd has no
1162 * meaning.
1163 *
1164 * @return true iff more input could change a positive match into a
1165 * negative one.
1166 * @since 1.5
1167 */
1168 public boolean requireEnd() {
1169 return requireEnd;
1170 }
1171
1172 /**
1173 * Initiates a search to find a Pattern within the given bounds.
1174 * The groups are filled with default values and the match of the root
1175 * of the state machine is called. The state machine will hold the state
1176 * of the match as it proceeds in this matcher.
1177 *
1178 * Matcher.from is not set here, because it is the "hard" boundary
1179 * of the start of the search which anchors will set to. The from param
1180 * is the "soft" boundary of the start of the search, meaning that the
1181 * regex tries to match at that index but ^ won't match there. Subsequent
1182 * calls to the search methods start at a new "soft" boundary which is
1183 * the end of the previous match.
1184 */
1185 boolean search(int from) {
1186 this.hitEnd = false;
1187 this.requireEnd = false;
1188 from = from < 0 ? 0 : from;
1189 this.first = from;
1190 this.oldLast = oldLast < 0 ? from : oldLast;
1191 for (int i = 0; i < groups.length; i++)
1192 groups[i] = -1;
1193 acceptMode = NOANCHOR;
1194 boolean result = parentPattern.root.match(this, from, text);
1195 if (!result)
1196 this.first = -1;
1197 this.oldLast = this.last;
1198 return result;
1199 }
1200
1201 /**
1202 * Initiates a search for an anchored match to a Pattern within the given
1203 * bounds. The groups are filled with default values and the match of the
1204 * root of the state machine is called. The state machine will hold the
1205 * state of the match as it proceeds in this matcher.
1206 */
1207 boolean match(int from, int anchor) {
1208 this.hitEnd = false;
1209 this.requireEnd = false;
1210 from = from < 0 ? 0 : from;
1211 this.first = from;
1212 this.oldLast = oldLast < 0 ? from : oldLast;
1213 for (int i = 0; i < groups.length; i++)
1214 groups[i] = -1;
1215 acceptMode = anchor;
1216 boolean result = parentPattern.matchRoot.match(this, from, text);
1217 if (!result)
1218 this.first = -1;
1219 this.oldLast = this.last;
1220 return result;
1221 }
1222
1223 /**
1224 * Returns the end index of the text.
1225 *
1226 * @return the index after the last character in the text
1227 */
1228 int getTextLength() {
1229 return text.length();
1230 }
1231
1232 /**
1233 * Generates a String from this Matcher's input in the specified range.
1234 *
1235 * @param beginIndex the beginning index, inclusive
1236 * @param endIndex the ending index, exclusive
1237 * @return A String generated from this Matcher's input
1238 */
1239 CharSequence getSubSequence(int beginIndex, int endIndex) {
1240 return text.subSequence(beginIndex, endIndex);
1241 }
1242
1243 /**
1244 * Returns this Matcher's input character at index i.
1245 *
1246 * @return A char from the specified index
1247 */
1248 char charAt(int i) {
1249 return text.charAt(i);
1250 }
1251
1252 }