Introduction to the Java.util.regex Object Model - Special Notes

(Page 10 of 12 )

This appendReplacement method offers a lot of power. As you may know, with great power comes subtle distinctions. By using the expression $d, in which d is a number less than or equal to the number of groups in the previous match, you can actually embed and reorganize subgroups in your search. For example, say your pattern is(James) (Bond):

  Pattern p = Pattern.compile("(James) (Bond)");

and your candidate is My name is Bond. James Bond.

  String candidateString = "My name is Bond. James Bond.";

and you want to insert the middle name Waldo. Your replacement String might look like the following:

String replacement = "$1 Waldo $2";

where $1 refers to the first matching subgroup, James, and $2 refers to the second matching subgroup, Bond.

In this case, the StringBuffer will contain the value My name is Bond. James Waldo Bond.. Listing 2-20 presents a complete working example.

Listing 2-20. Using appendReplacement with Subgroup  
                       Replacements

import java.util.regex.*;
import java.util.*;
/**
 * Demonstrates usage of the
 * Matcher.appendReplacement method, with
 * subgroup replacement.
 */
public class MatcherAppendReplacementGroupExample{
   public static void main(String args[]){ 
       test();
   }
   public static void test(){
      //create a Pattern
       Pattern p = Pattern.compile("(James) (Bond)");
       //create a StringBuffer
       StringBuffer sb =new StringBuffer();
     //create the candidate Strings
     String candidateString =
     "My name is Bond. James Bond.";
     String replacement = "$1 Waldo $2";
     //Attempt to match the first candidate String 
     Matcher matcher = p.matcher(candidateString); 
     matcher.find();
     //populate the StringBufffer 
     matcher.appendReplacement(sb,replacement);
     //display the output for the candidate
     String msg = sb.toString();
     System.out.println( msg );
  }
}

The appendReplacement method will throw an IllegalStateException if a find() has not been called, or if find returns false. It will throw an IndexOutOfBoundsException if the capturing group referred to by $1, $2, and so on doesn’t exist in the part of the pattern currently being scrutinized by the Matcher.

public StringBuffer appendTail(StringBuffer sb)

The appendTail method is a supplement to the appendReplacement method. It simply appends every remaining subsequence from the original candidate string to the StringBuffer. It reads from the append position, which I explained in the appendReplacement section, to the end of the candidate string.

In the appendReplacement example given earlier, you swapped out Smith for Bond in the string My name is Bond. James Bond. I would like a martini.. When you finished, you had a StringBuffer that contained the value My name is Smith. James Smith.

That was as much as the appendReplacement method could accomplish for you, because it’s based on a successful match, and there are no more successful matches to be found after the d in the second occurrence of the word Bond. The state of the Matcher after the second call to appendReplacement is shown in the following image:

 

Correspondingly, the StringBuffer created by using appendReplacement would only have contained the phrase My name is Smith. James Smith. The appendTail method simply appends the rest of the String, namely .I would like a martini. to the StringBufferbuffer. That same StringBuffer is returned.

public String replaceAll(String replacement)

This method is one of my favorite new additions, both for its functionality and for its intuitive application programming interface (API). The replaceAll method simply returns a String that replaces every occurrence of the description with the replacement.

Imagine that you have the String I love ice. Ice is my favorite. Ice Ice Ice., and you want to replace every occurrence of ice or Ice with the word Java. Your first step is to describe the word you want to look for. In this case, because you want to match both uppercase Ice and lowercase ice you’ll use the regex pattern (i|I)ce:

Pattern pattern = Pattern.compile("(i|I)ce");

Next, use the candidate String to get a Matcher:

Matcher matcher = pattern.matcher("I love ice. Ice is my favorite. Ice Ice Ice.");

Finally, make the replacement:

String tmp = matcher.replaceAll("Java");

Now the string tmp holds the value I love Java. Java is my favorite. Java Java Java..Listing 2-21 presents the complete code for this example.

Listing 2-21. replaceAll Method Example

import java.util.regex.*;
import java.util.*;
/**
 * Demonstrates usage of the
 * Matcher.replaceAll method
 */
public class MatcherReplaceAllExample{
  public static void main(String args[]){
     test();
  }
  public static void test(){
     //create a Pattern
      Pattern p = Pattern.compile("(i|I)ce");
     //create the candidate String
     String candidateString =
     "I love ice. Ice is my favorite. Ice Ice Ice.";
     Matcher matcher = p.matcher(candidateString);
     String tmp = matcher.replaceAll("Java");
     System.out.println( tmp );
  }
}

CAUTION  Using this method will change the state of your Matcher object. Specifically, the reset method will be called. Therefore, it’s as if all start, end, group, and find calls hadn’t been called.

Like the appendReplacement method, this replaceAll method can contain references to substrings by using the $ symbol. For details, please see the appendReplacement documentation presented earlier in the chapter.

public String replaceFirst(String replacement)

The replaceFirst method is a more focused version of the                replaceAll method. This method returns a String that replaces the first occurrence of the description with the replacement.

Imagine that you have the candidate I love ice. Ice is my favorite. Ice Ice Ice., and you want to replace the first occurrence of ice or Ice with the word Java. Again, your first step is to describe the word you want to look for. In this case, because you want to match both uppercase Ice and lowercase ice, you use the regex pattern (i|I)ce:

Pattern pattern = Pattern.compile("(i|I)ce");

Next, use the candidate String to get a Matcher:

Matcher matcher = pattern.matcher("I love ice. Ice is my favorite. Ice Ice Ice.");

Finally, make the replacement:

String tmp = matcher.replaceFirst("Java");

The string tmp holds the value I love Java. Ice is my favorite. Ice Ice Ice.. Listing 2-22 presents the complete code for this example.

Listing 2-22. replaceFirst Method Example

import java.util.regex.*;
import java.util.*;
/**
 * Demonstrates usage of the
 * Matcher.replaceFirst method
 */
public class MatcherReplaceFirstExample{
  public static void main(String args[]){
      test();
  }
  public static void test(){
     //create a Pattern
      Pattern p = Pattern.compile("(i|I)ce");
     //create the candidate String
     String candidateString =
     "I love ice. Ice is my favorite. Ice Ice Ice.";
     Matcher matcher = p.matcher(candidateString);
     String tmp = matcher.replaceFirst("Java");
     System.out.println( tmp );
}}

CAUTION  Using this method will change the state of your Matcher object. Specifically, the reset method will be called. Therefore, remember that all start, end, group, and find calls will have to be re-executed.

Like the appendReplacement method, the replaceFirst method can contain references to substring by using the $ symbol. For details, please see the appendReplacement documentation presented earlier in the chapter.

Next: New String Rejex-Friendly Methods >>
 

More Java Articles
More By Apress Publishing

Comments On: Introduction to the Java.util.regex Object Model

>>> Be the FIRST to comment on this article!

Buy this book...

This article is excerpted from chapter three of Java Regular Expressions Taming the Java.util.regex Engine, written by Mehran Habibi (Apress, 2004; ISBN: 1590591070). Check it out at your favorite bookstore. Buy this book now.