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 and 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 theIReplacingCallback
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 examples show how to use the aforementioned overloads. The sample class provides methods, each of which uses aRange.Replace
overload:
Example 1 simply replaces all occurrences of the word "sad" to "bad".
Example 2 replaces all occurrences of the words "sad" or "mad" to "bad".
Example 3 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 1: Replace One Word with Another
Shows how to replace all occurrences of word "sad" to "bad". You can download template file of this example from here.
Example 2: Replace Two Similar Words with One Other
Shows how to replace all occurrences of words "sad" or "mad" to "bad". You can download template file of this example from here.
Example 3: Use a Custom Evaluator
Shows how to replace with a custom evaluator. You can download template file of this example from here.
// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
private class MyReplaceEvaluator : 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.
///
ReplaceAction IReplacingCallback.Replacing(ReplacingArgs e)
{
e.Replacement = e.Match.ToString() + mMatchNumber.ToString();
mMatchNumber++;
return ReplaceAction.Replace;
}
private int mMatchNumber;
}
view raw Examples-CSharp-Programming-Documents-Find-Replace-ReplaceWithEvaluator-MyReplaceEvaluator.cs hosted with ❤ by GitHub
How to Find and Highlight Text
This section describes how to programmatically find and highlight a word or a phrase in a document using Aspose.Words. It might seem easy to simply find the string of text in a document and change its formatting, but the main difficulty is that due to formatting, the match string could be spread over several runs of text. Consider the following example. The phrase “Hello World!” if formatted and consists of three different runs: Hello is italic, World is bold, and the exclamation mark is regular text:
Hello World!
In addition to formatting, bookmarks in the middle of text will split it into more runs.) The above example is represented in Aspose.Words using the following objects:
Run
(
Run.Text
= “Hello”,
Font.Italic
= true)
Run (Run.Text = “World”,
Font.Bold
= true)
Run (Run.Text = “!”)
This article provides a solution designed to handle the described case – if necessary it collects the word (or phrase) from several runs, while skipping non-run nodes.
The Code
The sample code will open a document and find any instance of the text “your document”. A replace handler is set up to handle the logic to be applied to each resulting match found. In this case the resulting runs are split around the txt and the resulting runs highlighted. Below example finds and highlights all instances of a particular word or a phrase in a Word document. You can download template file of this example from here.
// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
// The path to the documents directory.
string dataDir = RunExamples.GetDataDir_FindAndReplace();
string fileName = "TestFile.doc";
Document doc = new Document(dataDir + fileName);
FindReplaceOptions options = new FindReplaceOptions();
options.ReplacingCallback = new ReplaceEvaluatorFindAndHighlight();
options.Direction = FindReplaceDirection.Backward;
// We want the "your document" phrase to be highlighted.
Regex regex = new Regex("your document", RegexOptions.IgnoreCase);
doc.Range.Replace(regex, "", options);
dataDir = dataDir + RunExamples.GetOutputFilePath(fileName);
// Save the output document.
doc.Save(dataDir);
view raw Examples-CSharp-Programming-Documents-Find-Replace-FindAndHighlight-FindAndHighlight.cs hosted with ❤ by GitHub
// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
private class ReplaceEvaluatorFindAndHighlight : IReplacingCallback
{
///
/// This method is called by the Aspose.Words find and replace engine for each match.
/// This method highlights the match string, even if it spans multiple runs.
///
ReplaceAction IReplacingCallback.Replacing(ReplacingArgs e)
{
// This is a Run node that contains either the beginning or the complete match.
Node currentNode = e.MatchNode;
// The first (and may be the only) run can contain text before the match,
// In this case it is necessary to split the run.
if (e.MatchOffset > 0)
currentNode = SplitRun((Run)currentNode, e.MatchOffset);
// This array is used to store all nodes of the match for further highlighting.
ArrayList runs = new ArrayList();
// Find all runs that contain parts of the match string.
int remainingLength = e.Match.Value.Length;
while (
(remainingLength > 0) &&
(currentNode != null) &&
(currentNode.GetText().Length <= remainingLength))
{
runs.Add(currentNode);
remainingLength = remainingLength - currentNode.GetText().Length;
// Select the next Run node.
// Have to loop because there could be other nodes such as BookmarkStart etc.
do
{
currentNode = currentNode.NextSibling;
}
while ((currentNode != null) && (currentNode.NodeType != NodeType.Run));
}
// Split the last run that contains the match if there is any text left.
if ((currentNode != null) && (remainingLength > 0))
{
SplitRun((Run)currentNode, remainingLength);
runs.Add(currentNode);
}
// Now highlight all runs in the sequence.
foreach (Run run in runs)
run.Font.HighlightColor = Color.Yellow;
// Signal to the replace engine to do nothing because we have already done all what we wanted.
return ReplaceAction.Skip;
}
}
view raw Examples-CSharp-Programming-Documents-Find-Replace-FindAndHighlight-ReplaceEvaluatorFindAndHighlight.cs hosted with ❤ by GitHub
// For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-.NET
///
/// Splits text of the specified run into two runs.
/// Inserts the new run just after the specified run.
///
private static Run SplitRun(Run run, int position)
{
Run afterRun = (Run)run.Clone(true);
afterRun.Text = run.Text.Substring(position);
run.Text = run.Text.Substring(0, position);
run.ParentNode.InsertAfter(afterRun, run);
return afterRun;
}
view raw Examples-CSharp-Programming-Documents-Find-Replace-FindAndHighlight-SplitRun.cs hosted with ❤ by GitHub