Aspose.Words

Find and Replace Overview

Use Range.Replace to find or replace a particular string within the current range. It returns the number of replacements made, so it is useful for searching strings without replace. An exception is thrown if a captured or replacement string contains one or more special characters: paragraph break, cell break, section break, field start, field separator, field end, inline picture, drawing object, footnote.

The Range.Replace method provides several overloads. Here are the possibilities they provide:

·          You can specify a string to be replaced, a string that will replace all its occurrences, whether the replacement is case-sensitive, and whether only stand-alone words will be affected. Note that a word is defined as being made up of only alpha-numeric characters. If replace is executed with only whole words only being matched and the input string happens to contain symbols, then no phrases will be found.

·          You can pass a regular expression pattern used to find matches and a string that will replace them. This overload replaces the whole match captured by the regular expression.

·          You can pass a regular expression pattern, and an object that implements the IReplacingCallBack interface. This sets out a user-defined method, which evaluates replacement at each step, you can also indicate whether the replacement should be done in a forward or backward direction. It is recommended if you are removing nodes during replacement then the replacement should be executed backwards to avoid any potential issues that may arise when removing nodes during the replacement process.

A class implementing the IReplacingCallBack interface will define a method IReplacingCallBack.Replacing that accepts a ReplacingArgs object providing data for a custom replace operation. The method should return a ReplaceAction enumeration value that specifies what happens to the current match during a replace operation - whether it should be replaced, skipped, or the whole replace operation should be terminated.

The following example shows how to use the aforementioned overloads. The sample class provides methods, each of which uses a Range.Replace overload:

·          Replace1 simply replaces all occurrences of the word "sad" to "bad".

·          Replace2 replaces all occurrences of the words "sad" or "mad" to "bad".

·          Replace3 uses a replace evaluator method to concatenate occurrences of words "sad" or "bad" with the counter value that is incremented each time the new occurrence is found.

Example RangesReplaceString

Shows how to replace all occurrences of word "sad" to "bad".

[Java]

 

Document doc = new Document(getMyDir() + "Document.doc");

doc.getRange().replace("sad", "bad", false, true);

 

 

Example RangesReplaceRegex

Shows how to replace all occurrences of words "sad" or "mad" to "bad".

[Java]

 

Document doc = new Document(getMyDir() + "Document.doc");

doc.getRange().replace(Pattern.compile("[s|m]ad"), "bad");

 

 

Example RangesReplaceWithReplaceEvaluator

Shows how to replace with a custom evaluator.

[Java]

 

public void replaceWithEvaluator() throws Exception

{

    Document doc = new Document(getMyDir() + "Range.ReplaceWithEvaluator.doc");

    doc.getRange().replace(Pattern.compile("[s|m]ad"), new MyReplaceEvaluator(), true);

    doc.save(getMyDir() + "Range.ReplaceWithEvaluator Out.doc");

}

 

private class MyReplaceEvaluator implements IReplacingCallback

{

    /**

     * This is called during a replace operation each time a match is found.

     * This method appends a number to the match string and returns it as a replacement string.

     */

    public int replacing(ReplacingArgs e) throws Exception

    {

        e.setReplacement(e.getMatch().group() + Integer.toString(mMatchNumber));

        mMatchNumber++;

        return ReplaceAction.REPLACE;

    }

 

    private int mMatchNumber;

}