FindReplaceOptions
Contents
[
Hide
]Inheritance: java.lang.Object
public class FindReplaceOptions
Specifies options for find/replace operations.
To learn more, visit the Find and Replace documentation article.
Examples:
Shows how to toggle case sensitivity when performing a find-and-replace operation.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Ruby bought a ruby necklace.");
// We can use a "FindReplaceOptions" object to modify the find-and-replace process.
FindReplaceOptions options = new FindReplaceOptions();
// Set the "MatchCase" flag to "true" to apply case sensitivity while finding strings to replace.
// Set the "MatchCase" flag to "false" to ignore character case while searching for text to replace.
options.setMatchCase(matchCase);
doc.getRange().replace("Ruby", "Jade", options);
Assert.assertEquals(matchCase ? "Jade bought a ruby necklace." : "Jade bought a Jade necklace.",
doc.getText().trim());
Shows how to toggle standalone word-only find-and-replace operations.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Jackson will meet you in Jacksonville.");
// We can use a "FindReplaceOptions" object to modify the find-and-replace process.
FindReplaceOptions options = new FindReplaceOptions();
// Set the "FindWholeWordsOnly" flag to "true" to replace the found text if it is not a part of another word.
// Set the "FindWholeWordsOnly" flag to "false" to replace all text regardless of its surroundings.
options.setFindWholeWordsOnly(findWholeWordsOnly);
doc.getRange().replace("Jackson", "Louis", options);
Assert.assertEquals(
findWholeWordsOnly ? "Louis will meet you in Jacksonville." : "Louis will meet you in Louisville.",
doc.getText().trim());
Constructors
| Constructor | Description |
|---|---|
| FindReplaceOptions() | Initializes a new instance of the FindReplaceOptions class with default settings. |
| FindReplaceOptions(int direction) | Initializes a new instance of this class. |
| FindReplaceOptions(IReplacingCallback replacingCallback) | Initializes a new instance of the FindReplaceOptions class with the specified replacing callback. |
| FindReplaceOptions(int direction, IReplacingCallback replacingCallback) | Initializes a new instance of this class. |
Methods
| Method | Description |
|---|---|
| getApplyFont() | Text formatting applied to new content. |
| getApplyParagraphFormat() | Paragraph formatting applied to new content. |
| getDirection() | Selects direction for replace. |
| getFindWholeWordsOnly() | True indicates the oldValue must be a standalone word. |
| getIgnoreDeleted() | Gets a boolean value indicating either to ignore text inside delete revisions. |
| getIgnoreFieldCodes() | Gets a boolean value indicating either to ignore text inside field codes. |
| getIgnoreFields() | Gets a boolean value indicating either to ignore text inside fields. |
| getIgnoreFootnotes() | Gets a boolean value indicating either to ignore footnotes. |
| getIgnoreInserted() | Gets a boolean value indicating either to ignore text inside insert revisions. |
| getIgnoreShapes() | Gets or sets a boolean value indicating either to ignore shapes within a text. |
| getIgnoreStructuredDocumentTags() | Gets a boolean value indicating either to ignore content of StructuredDocumentTag. |
| getLegacyMode() | Gets a boolean value indicating that old find/replace algorithm is used. |
| getMatchCase() | True indicates case-sensitive comparison, false indicates case-insensitive comparison. |
| getReplacingCallback() | The user-defined method which is called before every replace occurrence. |
| getSmartParagraphBreakReplacement() | Gets or sets a boolean value indicating either it is allowed to replace paragraph break when there is no next sibling paragraph. |
| getUseLegacyOrder() | True indicates that a text search is performed sequentially from top to bottom considering the text boxes. |
| getUseSubstitutions() | Gets a boolean value indicating whether to recognize and use substitutions within replacement patterns. |
| setDirection(int value) | Selects direction for replace. |
| setFindWholeWordsOnly(boolean value) | True indicates the oldValue must be a standalone word. |
| setIgnoreDeleted(boolean value) | Sets a boolean value indicating either to ignore text inside delete revisions. |
| setIgnoreFieldCodes(boolean value) | Sets a boolean value indicating either to ignore text inside field codes. |
| setIgnoreFields(boolean value) | Sets a boolean value indicating either to ignore text inside fields. |
| setIgnoreFootnotes(boolean value) | Sets a boolean value indicating either to ignore footnotes. |
| setIgnoreInserted(boolean value) | Sets a boolean value indicating either to ignore text inside insert revisions. |
| setIgnoreShapes(boolean value) | Gets or sets a boolean value indicating either to ignore shapes within a text. |
| setIgnoreStructuredDocumentTags(boolean value) | Sets a boolean value indicating either to ignore content of StructuredDocumentTag. |
| setLegacyMode(boolean value) | Sets a boolean value indicating that old find/replace algorithm is used. |
| setMatchCase(boolean value) | True indicates case-sensitive comparison, false indicates case-insensitive comparison. |
| setReplacingCallback(IReplacingCallback value) | The user-defined method which is called before every replace occurrence. |
| setSmartParagraphBreakReplacement(boolean value) | Gets or sets a boolean value indicating either it is allowed to replace paragraph break when there is no next sibling paragraph. |
| setUseLegacyOrder(boolean value) | True indicates that a text search is performed sequentially from top to bottom considering the text boxes. |
| setUseSubstitutions(boolean value) | Sets a boolean value indicating whether to recognize and use substitutions within replacement patterns. |
FindReplaceOptions()
public FindReplaceOptions()
Initializes a new instance of the FindReplaceOptions class with default settings.
Examples:
Shows how to recognize and use substitutions within replacement patterns.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.write("Jason gave money to Paul.");
String regex = "([A-z]+) gave money to ([A-z]+)";
FindReplaceOptions options = new FindReplaceOptions();
options.setUseSubstitutions(true);
// Using legacy mode does not support many advanced features, so we need to set it to 'false'.
options.setLegacyMode(false);
doc.getRange().replace(Pattern.compile(regex), "$2 took money from $1", options);
Assert.assertEquals(doc.getText(), "Paul took money from Jason.\f");
FindReplaceOptions(int direction)
public FindReplaceOptions(int direction)
Initializes a new instance of this class.
Parameters:
| Parameter | Type | Description |
|---|---|---|
| direction | int |
FindReplaceOptions(IReplacingCallback replacingCallback)
public FindReplaceOptions(IReplacingCallback replacingCallback)
Initializes a new instance of the FindReplaceOptions class with the specified replacing callback.
Examples:
Shows how to track the order in which a text replacement operation traverses nodes.
public void order(boolean differentFirstPageHeaderFooter) throws Exception {
Document doc = new Document(getMyDir() + "Header and footer types.docx");
Section firstPageSection = doc.getFirstSection();
ReplaceLog logger = new ReplaceLog();
FindReplaceOptions options = new FindReplaceOptions();
{
options.setReplacingCallback(logger);
}
// Using a different header/footer for the first page will affect the search order.
firstPageSection.getPageSetup().setDifferentFirstPageHeaderFooter(differentFirstPageHeaderFooter);
doc.getRange().replace(Pattern.compile("(header|footer)"), "", options);
if (differentFirstPageHeaderFooter)
Assert.assertEquals("First headerFirst footerSecond headerSecond footerThird headerThird footer",
logger.Text().replace("\r", ""));
else
Assert.assertEquals("Third headerFirst headerThird footerFirst footerSecond headerSecond footer",
logger.Text().replace("\r", ""));
}
public static Object[][] orderDataProvider() throws Exception {
return new Object[][]
{
{false},
{true},
};
}
///
/// During a find-and-replace operation, records the contents of every node that has text that the operation 'finds',
/// in the state it is in before the replacement takes place.
/// This will display the order in which the text replacement operation traverses nodes.
///
private static class ReplaceLog implements IReplacingCallback {
public int replacing(ReplacingArgs args) {
mTextBuilder.append(args.getMatchNode().getText());
return ReplaceAction.SKIP;
}
public String Text() {
return mTextBuilder.toString();
}
private final StringBuilder mTextBuilder = new StringBuilder();
}
Parameters:
| Parameter | Type | Description |
|---|---|---|
| replacingCallback | IReplacingCallback | The callback to use for replacing found text. |
FindReplaceOptions(int direction, IReplacingCallback replacingCallback)
public FindReplaceOptions(int direction, IReplacingCallback replacingCallback)
Initializes a new instance of this class.
Parameters:
| Parameter | Type | Description |
|---|---|---|
| direction | int | |
| replacingCallback | IReplacingCallback |
getApplyFont()
public Font getApplyFont()
Text formatting applied to new content.
Examples:
Shows how to apply a different font to new content via FindReplaceOptions.
public void convertNumbersToHexadecimal() throws Exception {
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.getFont().setName("Arial");
builder.writeln("Numbers that the find-and-replace operation will convert to hexadecimal and highlight:\n" +
"123, 456, 789 and 17379.");
// We can use a "FindReplaceOptions" object to modify the find-and-replace process.
FindReplaceOptions options = new FindReplaceOptions();
// Set the "HighlightColor" property to a background color that we want to apply to the operation's resulting text.
options.getApplyFont().setHighlightColor(Color.GRAY);
NumberHexer numberHexer = new NumberHexer();
options.setReplacingCallback(numberHexer);
int replacementCount = doc.getRange().replace(Pattern.compile("[0-9]+"), "", options);
System.out.println(numberHexer.getLog());
Assert.assertEquals(4, replacementCount);
Assert.assertEquals("Numbers that the find-and-replace operation will convert to hexadecimal and highlight:\r" +
"0x123, 0x456, 0x789 and 0x17,379.", doc.getText().trim());
}
///
/// Replaces numeric find-and-replacement matches with their hexadecimal equivalents.
/// Maintains a log of every replacement.
///
private static class NumberHexer implements IReplacingCallback {
public int replacing(ReplacingArgs args) {
mCurrentReplacementNumber++;
int number = Integer.parseInt(args.getMatch().group(0));
args.setReplacement(MessageFormat.format("0x{0}", number));
mLog.append(MessageFormat.format("Match #{0}", mCurrentReplacementNumber));
mLog.append(MessageFormat.format("\tOriginal value:\t{0}", args.getMatch().group(0)));
mLog.append(MessageFormat.format("\tReplacement:\t{0}", args.getReplacement()));
mLog.append(MessageFormat.format("\tOffset in parent {0} node:\t{1}", args.getMatchNode().getNodeType(), args.getMatchOffset()));
return ReplaceAction.REPLACE;
}
public String getLog() {
return mLog.toString();
}
private int mCurrentReplacementNumber;
private final StringBuilder mLog = new StringBuilder();
}
Returns: Font - The corresponding Font value.
getApplyParagraphFormat()
public ParagraphFormat getApplyParagraphFormat()
Paragraph formatting applied to new content.
Examples:
Shows how to add formatting to paragraphs in which a find-and-replace operation has found matches.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Every paragraph that ends with a full stop like this one will be right aligned.");
builder.writeln("This one will not!");
builder.write("This one also will.");
ParagraphCollection paragraphs = doc.getFirstSection().getBody().getParagraphs();
Assert.assertEquals(ParagraphAlignment.LEFT, paragraphs.get(0).getParagraphFormat().getAlignment());
Assert.assertEquals(ParagraphAlignment.LEFT, paragraphs.get(1).getParagraphFormat().getAlignment());
Assert.assertEquals(ParagraphAlignment.LEFT, paragraphs.get(2).getParagraphFormat().getAlignment());
// We can use a "FindReplaceOptions" object to modify the find-and-replace process.
FindReplaceOptions options = new FindReplaceOptions();
// Set the "Alignment" property to "ParagraphAlignment.Right" to right-align every paragraph
// that contains a match that the find-and-replace operation finds.
options.getApplyParagraphFormat().setAlignment(ParagraphAlignment.RIGHT);
// Replace every full stop that is right before a paragraph break with an exclamation point.
int count = doc.getRange().replace(".&p", "!&p", options);
Assert.assertEquals(2, count);
Assert.assertEquals(ParagraphAlignment.RIGHT, paragraphs.get(0).getParagraphFormat().getAlignment());
Assert.assertEquals(ParagraphAlignment.LEFT, paragraphs.get(1).getParagraphFormat().getAlignment());
Assert.assertEquals(ParagraphAlignment.RIGHT, paragraphs.get(2).getParagraphFormat().getAlignment());
Assert.assertEquals("Every paragraph that ends with a full stop like this one will be right aligned!\r" +
"This one will not!\r" +
"This one also will!", doc.getText().trim());
Returns: ParagraphFormat - The corresponding ParagraphFormat value.
getDirection()
public int getDirection()
Selects direction for replace. Default value is FindReplaceDirection.FORWARD.
Examples:
Shows how to determine which direction a find-and-replace operation traverses the document in.
public void direction(int findReplaceDirection) throws Exception {
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert three runs which we can search for using a regex pattern.
// Place one of those runs inside a text box.
builder.writeln("Match 1.");
builder.writeln("Match 2.");
builder.writeln("Match 3.");
builder.writeln("Match 4.");
// We can use a "FindReplaceOptions" object to modify the find-and-replace process.
FindReplaceOptions options = new FindReplaceOptions();
// Assign a custom callback to the "ReplacingCallback" property.
TextReplacementRecorder callback = new TextReplacementRecorder();
options.setReplacingCallback(callback);
// Set the "Direction" property to "FindReplaceDirection.Backward" to get the find-and-replace
// operation to start from the end of the range, and traverse back to the beginning.
// Set the "Direction" property to "FindReplaceDirection.Forward" to get the find-and-replace
// operation to start from the beginning of the range, and traverse to the end.
options.setDirection(findReplaceDirection);
doc.getRange().replace(Pattern.compile("Match \\d*"), "Replacement", options);
Assert.assertEquals("Replacement.\r" +
"Replacement.\r" +
"Replacement.\r" +
"Replacement.", doc.getText().trim());
switch (findReplaceDirection) {
case FindReplaceDirection.FORWARD:
Assert.assertEquals(new String[]{"Match 1", "Match 2", "Match 3", "Match 4"}, callback.getMatches().toArray());
break;
case FindReplaceDirection.BACKWARD:
Assert.assertEquals(new String[]{"Match 4", "Match 3", "Match 2", "Match 1"}, callback.getMatches().toArray());
break;
}
}
public static Object[][] directionDataProvider() {
return new Object[][]
{
{FindReplaceDirection.BACKWARD},
{FindReplaceDirection.FORWARD},
};
}
///
/// Records all matches that occur during a find-and-replace operation in the order that they take place.
///
private static class TextReplacementRecorder implements IReplacingCallback {
public int replacing(ReplacingArgs e) {
mMatches.add(e.getMatch().group(0));
return ReplaceAction.REPLACE;
}
public ArrayList getMatches() {
return mMatches;
}
private final ArrayList mMatches = new ArrayList();
}
Returns: int - The corresponding int value. The returned value is one of FindReplaceDirection constants.
getFindWholeWordsOnly()
public boolean getFindWholeWordsOnly()
True indicates the oldValue must be a standalone word.
Examples:
Shows how to toggle standalone word-only find-and-replace operations.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Jackson will meet you in Jacksonville.");
// We can use a "FindReplaceOptions" object to modify the find-and-replace process.
FindReplaceOptions options = new FindReplaceOptions();
// Set the "FindWholeWordsOnly" flag to "true" to replace the found text if it is not a part of another word.
// Set the "FindWholeWordsOnly" flag to "false" to replace all text regardless of its surroundings.
options.setFindWholeWordsOnly(findWholeWordsOnly);
doc.getRange().replace("Jackson", "Louis", options);
Assert.assertEquals(
findWholeWordsOnly ? "Louis will meet you in Jacksonville." : "Louis will meet you in Louisville.",
doc.getText().trim());
Returns: boolean - The corresponding boolean value.
getIgnoreDeleted()
public boolean getIgnoreDeleted()
Gets a boolean value indicating either to ignore text inside delete revisions. The default value is false .
Examples:
Shows how to include or ignore text inside delete revisions during a find-and-replace operation.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Hello world!");
builder.writeln("Hello again!");
// Start tracking revisions and remove the second paragraph, which will create a delete revision.
// That paragraph will persist in the document until we accept the delete revision.
doc.startTrackRevisions("John Doe", new Date());
doc.getFirstSection().getBody().getParagraphs().get(1).remove();
doc.stopTrackRevisions();
Assert.assertTrue(doc.getFirstSection().getBody().getParagraphs().get(1).isDeleteRevision());
// We can use a "FindReplaceOptions" object to modify the find and replace process.
FindReplaceOptions options = new FindReplaceOptions();
// Set the "IgnoreDeleted" flag to "true" to get the find-and-replace
// operation to ignore paragraphs that are delete revisions.
// Set the "IgnoreDeleted" flag to "false" to get the find-and-replace
// operation to also search for text inside delete revisions.
options.setIgnoreDeleted(ignoreTextInsideDeleteRevisions);
doc.getRange().replace("Hello", "Greetings", options);
Assert.assertEquals(
ignoreTextInsideDeleteRevisions
? "Greetings world!\rHello again!"
: "Greetings world!\rGreetings again!", doc.getText().trim());
Returns: boolean - A boolean value indicating either to ignore text inside delete revisions.
getIgnoreFieldCodes()
public boolean getIgnoreFieldCodes()
Gets a boolean value indicating either to ignore text inside field codes. The default value is false .
Remarks:
This option affects only field codes (it does not ignore nodes between NodeType.FIELD_SEPARATOR and NodeType.FIELD_END).
To ignore whole field, please use corresponding option getIgnoreFields() / setIgnoreFields(boolean).
Examples:
Shows how to ignore text inside field codes.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertField("INCLUDETEXT", "Test IT!");
FindReplaceOptions options = new FindReplaceOptions(); {options.setIgnoreFieldCodes(ignoreFieldCodes);}
// Replace 'T' in document ignoring text inside field code or not.
doc.getRange().replace(Pattern.compile("T"), "*", options);
System.out.println(doc.getText());
Assert.assertEquals(
ignoreFieldCodes
? "INCLUDETEXT*est I*!"
: "INCLUDE*EX**est I*!", doc.getText().trim());
Returns: boolean - A boolean value indicating either to ignore text inside field codes.
getIgnoreFields()
public boolean getIgnoreFields()
Gets a boolean value indicating either to ignore text inside fields. The default value is false .
Remarks:
This option affects whole field (all nodes between NodeType.FIELD_START and NodeType.FIELD_END).
To ignore only field codes, please use corresponding option getIgnoreFieldCodes() / setIgnoreFieldCodes(boolean).
Examples:
Shows how to ignore text inside fields.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Hello world!");
builder.insertField("QUOTE", "Hello again!");
// We can use a "FindReplaceOptions" object to modify the find-and-replace process.
FindReplaceOptions options = new FindReplaceOptions();
// Set the "IgnoreFields" flag to "true" to get the find-and-replace
// operation to ignore text inside fields.
// Set the "IgnoreFields" flag to "false" to get the find-and-replace
// operation to also search for text inside fields.
options.setIgnoreFields(ignoreTextInsideFields);
doc.getRange().replace("Hello", "Greetings", options);
Assert.assertEquals(
ignoreTextInsideFields
? "Greetings world!\rQUOTEHello again!"
: "Greetings world!\rQUOTEGreetings again!", doc.getText().trim());
Returns: boolean - A boolean value indicating either to ignore text inside fields.
getIgnoreFootnotes()
public boolean getIgnoreFootnotes()
Gets a boolean value indicating either to ignore footnotes. The default value is false .
Examples:
Shows how to ignore footnotes during a find-and-replace operation.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.write("Lorem ipsum dolor sit amet, consectetur adipiscing elit.");
builder.insertFootnote(FootnoteType.FOOTNOTE, "Lorem ipsum dolor sit amet, consectetur adipiscing elit.");
builder.insertParagraph();
builder.write("Lorem ipsum dolor sit amet, consectetur adipiscing elit.");
builder.insertFootnote(FootnoteType.ENDNOTE, "Lorem ipsum dolor sit amet, consectetur adipiscing elit.");
// Set the "IgnoreFootnotes" flag to "true" to get the find-and-replace
// operation to ignore text inside footnotes.
// Set the "IgnoreFootnotes" flag to "false" to get the find-and-replace
// operation to also search for text inside footnotes.
FindReplaceOptions options = new FindReplaceOptions();
{
options.setIgnoreFootnotes(isIgnoreFootnotes);
}
doc.getRange().replace("Lorem ipsum", "Replaced Lorem ipsum", options);
Returns: boolean - A boolean value indicating either to ignore footnotes.
getIgnoreInserted()
public boolean getIgnoreInserted()
Gets a boolean value indicating either to ignore text inside insert revisions. The default value is false .
Examples:
Shows how to include or ignore text inside insert revisions during a find-and-replace operation.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Hello world!");
// Start tracking revisions and insert a paragraph. That paragraph will be an insert revision.
doc.startTrackRevisions("John Doe", new Date());
builder.writeln("Hello again!");
doc.stopTrackRevisions();
Assert.assertTrue(doc.getFirstSection().getBody().getParagraphs().get(1).isInsertRevision());
// We can use a "FindReplaceOptions" object to modify the find-and-replace process.
FindReplaceOptions options = new FindReplaceOptions();
// Set the "IgnoreInserted" flag to "true" to get the find-and-replace
// operation to ignore paragraphs that are insert revisions.
// Set the "IgnoreInserted" flag to "false" to get the find-and-replace
// operation to also search for text inside insert revisions.
options.setIgnoreInserted(ignoreTextInsideInsertRevisions);
doc.getRange().replace("Hello", "Greetings", options);
Assert.assertEquals(
ignoreTextInsideInsertRevisions
? "Greetings world!\rHello again!"
: "Greetings world!\rGreetings again!", doc.getText().trim());
Returns: boolean - A boolean value indicating either to ignore text inside insert revisions.
getIgnoreShapes()
public boolean getIgnoreShapes()
Gets or sets a boolean value indicating either to ignore shapes within a text.
The default value is false .
Returns: boolean - The corresponding boolean value.
getIgnoreStructuredDocumentTags()
public boolean getIgnoreStructuredDocumentTags()
Gets a boolean value indicating either to ignore content of StructuredDocumentTag. The default value is false .
Remarks:
When this option is set to true , the content of StructuredDocumentTag will be treated as a simple text.
Otherwise, StructuredDocumentTag will be processed as standalone Story and replacing pattern will be searched separately for each StructuredDocumentTag, so that if pattern crosses a StructuredDocumentTag, then replacement will not be performed for such pattern.
Examples:
Shows how to ignore content of tags from replacement.
Document doc = new Document(getMyDir() + "Structured document tags.docx");
// This paragraph contains SDT.
Paragraph p = (Paragraph)doc.getFirstSection().getBody().getChild(NodeType.PARAGRAPH, 2, true);
String textToSearch = p.toString(SaveFormat.TEXT).trim();
FindReplaceOptions options = new FindReplaceOptions();
options.setIgnoreStructuredDocumentTags(true);
doc.getRange().replace(textToSearch, "replacement", options);
doc.save(getArtifactsDir() + "StructuredDocumentTag.IgnoreStructuredDocumentTags.docx");
Returns: boolean - A boolean value indicating either to ignore content of StructuredDocumentTag.
getLegacyMode()
public boolean getLegacyMode()
Gets a boolean value indicating that old find/replace algorithm is used.
Remarks:
Use this flag if you need exactly the same behavior as before advanced find/replace feature was introduced. Note that old algorithm does not support advanced features such as replace with breaks, apply formatting and so on.
Examples:
Shows how to recognize and use substitutions within replacement patterns.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.write("Jason gave money to Paul.");
String regex = "([A-z]+) gave money to ([A-z]+)";
FindReplaceOptions options = new FindReplaceOptions();
options.setUseSubstitutions(true);
// Using legacy mode does not support many advanced features, so we need to set it to 'false'.
options.setLegacyMode(false);
doc.getRange().replace(Pattern.compile(regex), "$2 took money from $1", options);
Assert.assertEquals(doc.getText(), "Paul took money from Jason.\f");
Returns: boolean - A boolean value indicating that old find/replace algorithm is used.
getMatchCase()
public boolean getMatchCase()
True indicates case-sensitive comparison, false indicates case-insensitive comparison.
Examples:
Shows how to toggle case sensitivity when performing a find-and-replace operation.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Ruby bought a ruby necklace.");
// We can use a "FindReplaceOptions" object to modify the find-and-replace process.
FindReplaceOptions options = new FindReplaceOptions();
// Set the "MatchCase" flag to "true" to apply case sensitivity while finding strings to replace.
// Set the "MatchCase" flag to "false" to ignore character case while searching for text to replace.
options.setMatchCase(matchCase);
doc.getRange().replace("Ruby", "Jade", options);
Assert.assertEquals(matchCase ? "Jade bought a ruby necklace." : "Jade bought a Jade necklace.",
doc.getText().trim());
Returns: boolean - The corresponding boolean value.
getReplacingCallback()
public IReplacingCallback getReplacingCallback()
The user-defined method which is called before every replace occurrence.
Examples:
Shows how to replace all occurrences of a regular expression pattern with another string, while tracking all such replacements.
public void replaceWithCallback() throws Exception {
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Our new location in New York City is opening tomorrow. " +
"Hope to see all our NYC-based customers at the opening!");
// We can use a "FindReplaceOptions" object to modify the find-and-replace process.
FindReplaceOptions options = new FindReplaceOptions();
// Set a callback that tracks any replacements that the "Replace" method will make.
TextFindAndReplacementLogger logger = new TextFindAndReplacementLogger();
options.setReplacingCallback(logger);
doc.getRange().replace(Pattern.compile("New York City|NYC"), "Washington", options);
Assert.assertEquals("Our new location in (Old value:\"New York City\") Washington is opening tomorrow. " +
"Hope to see all our (Old value:\"NYC\") Washington-based customers at the opening!", doc.getText().trim());
Assert.assertEquals("\"New York City\" converted to \"Washington\" 20 characters into a 21 node." +
"\"NYC\" converted to \"Washington\" 42 characters into a 21 node.", logger.getLog().trim());
}
///
/// Maintains a log of every text replacement done by a find-and-replace operation
/// and notes the original matched text's value.
///
private static class TextFindAndReplacementLogger implements IReplacingCallback {
public int replacing(ReplacingArgs args) {
mLog.append(MessageFormat.format("\"{0}\" converted to \"{1}\" {2} characters into a {3} node.", args.getMatch().group(0), args.getReplacement(), args.getMatchOffset(), args.getMatchNode().getNodeType()));
args.setReplacement(MessageFormat.format("(Old value:\"{0}\") {1}", args.getMatch().group(0), args.getReplacement()));
return ReplaceAction.REPLACE;
}
public String getLog() {
return mLog.toString();
}
private final StringBuilder mLog = new StringBuilder();
}
Shows how to apply a different font to new content via FindReplaceOptions.
public void convertNumbersToHexadecimal() throws Exception {
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.getFont().setName("Arial");
builder.writeln("Numbers that the find-and-replace operation will convert to hexadecimal and highlight:\n" +
"123, 456, 789 and 17379.");
// We can use a "FindReplaceOptions" object to modify the find-and-replace process.
FindReplaceOptions options = new FindReplaceOptions();
// Set the "HighlightColor" property to a background color that we want to apply to the operation's resulting text.
options.getApplyFont().setHighlightColor(Color.GRAY);
NumberHexer numberHexer = new NumberHexer();
options.setReplacingCallback(numberHexer);
int replacementCount = doc.getRange().replace(Pattern.compile("[0-9]+"), "", options);
System.out.println(numberHexer.getLog());
Assert.assertEquals(4, replacementCount);
Assert.assertEquals("Numbers that the find-and-replace operation will convert to hexadecimal and highlight:\r" +
"0x123, 0x456, 0x789 and 0x17,379.", doc.getText().trim());
}
///
/// Replaces numeric find-and-replacement matches with their hexadecimal equivalents.
/// Maintains a log of every replacement.
///
private static class NumberHexer implements IReplacingCallback {
public int replacing(ReplacingArgs args) {
mCurrentReplacementNumber++;
int number = Integer.parseInt(args.getMatch().group(0));
args.setReplacement(MessageFormat.format("0x{0}", number));
mLog.append(MessageFormat.format("Match #{0}", mCurrentReplacementNumber));
mLog.append(MessageFormat.format("\tOriginal value:\t{0}", args.getMatch().group(0)));
mLog.append(MessageFormat.format("\tReplacement:\t{0}", args.getReplacement()));
mLog.append(MessageFormat.format("\tOffset in parent {0} node:\t{1}", args.getMatchNode().getNodeType(), args.getMatchOffset()));
return ReplaceAction.REPLACE;
}
public String getLog() {
return mLog.toString();
}
private int mCurrentReplacementNumber;
private final StringBuilder mLog = new StringBuilder();
}
Returns: IReplacingCallback - The corresponding IReplacingCallback value.
getSmartParagraphBreakReplacement()
public boolean getSmartParagraphBreakReplacement()
Gets or sets a boolean value indicating either it is allowed to replace paragraph break when there is no next sibling paragraph.
The default value is false .
Remarks:
This option allows to replace paragraph break when there is no next sibling paragraph to which all child nodes can be moved, by finding any (not necessarily sibling) next paragraph after the paragraph being replaced.
Examples:
Shows how to remove paragraph from a table cell with a nested table.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create table with paragraph and inner table in first cell.
builder.startTable();
builder.insertCell();
builder.write("TEXT1");
builder.startTable();
builder.insertCell();
builder.endTable();
builder.endTable();
builder.writeln();
FindReplaceOptions options = new FindReplaceOptions();
// When the following option is set to 'true', Aspose.Words will remove paragraph's text
// completely with its paragraph mark. Otherwise, Aspose.Words will mimic Word and remove
// only paragraph's text and leaves the paragraph mark intact (when a table follows the text).
options.setSmartParagraphBreakReplacement(isSmartParagraphBreakReplacement);
doc.getRange().replace("TEXT1&p", "", options);
doc.save(getArtifactsDir() + "Table.RemoveParagraphTextAndMark.docx");
Returns: boolean - The corresponding boolean value.
getUseLegacyOrder()
public boolean getUseLegacyOrder()
True indicates that a text search is performed sequentially from top to bottom considering the text boxes. Default value is false .
Examples:
Shows how to change the searching order of nodes when performing a find-and-replace text operation.
public void useLegacyOrder(boolean useLegacyOrder) throws Exception {
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert three runs which we can search for using a regex pattern.
// Place one of those runs inside a text box.
builder.writeln("[tag 1]");
Shape textBox = builder.insertShape(ShapeType.TEXT_BOX, 100.0, 50.0);
builder.writeln("[tag 2]");
builder.moveTo(textBox.getFirstParagraph());
builder.write("[tag 3]");
// We can use a "FindReplaceOptions" object to modify the find-and-replace process.
FindReplaceOptions options = new FindReplaceOptions();
// Assign a custom callback to the "ReplacingCallback" property.
TextReplacementTracker callback = new TextReplacementTracker();
options.setReplacingCallback(callback);
// If we set the "UseLegacyOrder" property to "true", the
// find-and-replace operation will go through all the runs outside of a text box
// before going through the ones inside a text box.
// If we set the "UseLegacyOrder" property to "false", the
// find-and-replace operation will go over all the runs in a range in sequential order.
options.setUseLegacyOrder(useLegacyOrder);
doc.getRange().replace("\[tag d*\]", "", options);
}
public static Object[][] useLegacyOrderDataProvider() {
return new Object[][]
{
{true},
{false},
};
}
///
/// Records the order of all matches that occur during a find-and-replace operation.
///
private static class TextReplacementTracker implements IReplacingCallback {
public int replacing(ReplacingArgs e) {
mMatches.add(e.getMatch().group(1));
return ReplaceAction.REPLACE;
}
public ArrayList getMatches() {
return mMatches;
}
private ArrayList mMatches;
}
Returns: boolean - The corresponding boolean value.
getUseSubstitutions()
public boolean getUseSubstitutions()
Gets a boolean value indicating whether to recognize and use substitutions within replacement patterns. The default value is false .
Remarks:
For the details on substitution elements please refer to: https://docs.microsoft.com/en-us/dotnet/standard/base-types/substitutions-in-regular-expressions.
Examples:
Shows how to recognize and use substitutions within replacement patterns.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.write("Jason gave money to Paul.");
String regex = "([A-z]+) gave money to ([A-z]+)";
FindReplaceOptions options = new FindReplaceOptions();
options.setUseSubstitutions(true);
// Using legacy mode does not support many advanced features, so we need to set it to 'false'.
options.setLegacyMode(false);
doc.getRange().replace(Pattern.compile(regex), "$2 took money from $1", options);
Assert.assertEquals(doc.getText(), "Paul took money from Jason.\f");
Shows how to replace the text with substitutions.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("John sold a car to Paul.");
builder.writeln("Jane sold a house to Joe.");
// We can use a "FindReplaceOptions" object to modify the find-and-replace process.
FindReplaceOptions options = new FindReplaceOptions();
// Set the "UseSubstitutions" property to "true" to get
// the find-and-replace operation to recognize substitution elements.
// Set the "UseSubstitutions" property to "false" to ignore substitution elements.
options.setUseSubstitutions(useSubstitutions);
doc.getRange().replace(Pattern.compile("([A-z]+) sold a ([A-z]+) to ([A-z]+)"), "$3 bought a $2 from $1", options);
Assert.assertEquals(
useSubstitutions
? "Paul bought a car from John.\rJoe bought a house from Jane."
: "$3 bought a $2 from $1.\r$3 bought a $2 from $1.", doc.getText().trim());
Returns: boolean - A boolean value indicating whether to recognize and use substitutions within replacement patterns.
setDirection(int value)
public void setDirection(int value)
Selects direction for replace. Default value is FindReplaceDirection.FORWARD.
Examples:
Shows how to determine which direction a find-and-replace operation traverses the document in.
public void direction(int findReplaceDirection) throws Exception {
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert three runs which we can search for using a regex pattern.
// Place one of those runs inside a text box.
builder.writeln("Match 1.");
builder.writeln("Match 2.");
builder.writeln("Match 3.");
builder.writeln("Match 4.");
// We can use a "FindReplaceOptions" object to modify the find-and-replace process.
FindReplaceOptions options = new FindReplaceOptions();
// Assign a custom callback to the "ReplacingCallback" property.
TextReplacementRecorder callback = new TextReplacementRecorder();
options.setReplacingCallback(callback);
// Set the "Direction" property to "FindReplaceDirection.Backward" to get the find-and-replace
// operation to start from the end of the range, and traverse back to the beginning.
// Set the "Direction" property to "FindReplaceDirection.Forward" to get the find-and-replace
// operation to start from the beginning of the range, and traverse to the end.
options.setDirection(findReplaceDirection);
doc.getRange().replace(Pattern.compile("Match \\d*"), "Replacement", options);
Assert.assertEquals("Replacement.\r" +
"Replacement.\r" +
"Replacement.\r" +
"Replacement.", doc.getText().trim());
switch (findReplaceDirection) {
case FindReplaceDirection.FORWARD:
Assert.assertEquals(new String[]{"Match 1", "Match 2", "Match 3", "Match 4"}, callback.getMatches().toArray());
break;
case FindReplaceDirection.BACKWARD:
Assert.assertEquals(new String[]{"Match 4", "Match 3", "Match 2", "Match 1"}, callback.getMatches().toArray());
break;
}
}
public static Object[][] directionDataProvider() {
return new Object[][]
{
{FindReplaceDirection.BACKWARD},
{FindReplaceDirection.FORWARD},
};
}
///
/// Records all matches that occur during a find-and-replace operation in the order that they take place.
///
private static class TextReplacementRecorder implements IReplacingCallback {
public int replacing(ReplacingArgs e) {
mMatches.add(e.getMatch().group(0));
return ReplaceAction.REPLACE;
}
public ArrayList getMatches() {
return mMatches;
}
private final ArrayList mMatches = new ArrayList();
}
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | int | The corresponding int value. The value must be one of FindReplaceDirection constants. |
setFindWholeWordsOnly(boolean value)
public void setFindWholeWordsOnly(boolean value)
True indicates the oldValue must be a standalone word.
Examples:
Shows how to toggle standalone word-only find-and-replace operations.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Jackson will meet you in Jacksonville.");
// We can use a "FindReplaceOptions" object to modify the find-and-replace process.
FindReplaceOptions options = new FindReplaceOptions();
// Set the "FindWholeWordsOnly" flag to "true" to replace the found text if it is not a part of another word.
// Set the "FindWholeWordsOnly" flag to "false" to replace all text regardless of its surroundings.
options.setFindWholeWordsOnly(findWholeWordsOnly);
doc.getRange().replace("Jackson", "Louis", options);
Assert.assertEquals(
findWholeWordsOnly ? "Louis will meet you in Jacksonville." : "Louis will meet you in Louisville.",
doc.getText().trim());
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | boolean | The corresponding boolean value. |
setIgnoreDeleted(boolean value)
public void setIgnoreDeleted(boolean value)
Sets a boolean value indicating either to ignore text inside delete revisions. The default value is false .
Examples:
Shows how to include or ignore text inside delete revisions during a find-and-replace operation.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Hello world!");
builder.writeln("Hello again!");
// Start tracking revisions and remove the second paragraph, which will create a delete revision.
// That paragraph will persist in the document until we accept the delete revision.
doc.startTrackRevisions("John Doe", new Date());
doc.getFirstSection().getBody().getParagraphs().get(1).remove();
doc.stopTrackRevisions();
Assert.assertTrue(doc.getFirstSection().getBody().getParagraphs().get(1).isDeleteRevision());
// We can use a "FindReplaceOptions" object to modify the find and replace process.
FindReplaceOptions options = new FindReplaceOptions();
// Set the "IgnoreDeleted" flag to "true" to get the find-and-replace
// operation to ignore paragraphs that are delete revisions.
// Set the "IgnoreDeleted" flag to "false" to get the find-and-replace
// operation to also search for text inside delete revisions.
options.setIgnoreDeleted(ignoreTextInsideDeleteRevisions);
doc.getRange().replace("Hello", "Greetings", options);
Assert.assertEquals(
ignoreTextInsideDeleteRevisions
? "Greetings world!\rHello again!"
: "Greetings world!\rGreetings again!", doc.getText().trim());
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | boolean | A boolean value indicating either to ignore text inside delete revisions. |
setIgnoreFieldCodes(boolean value)
public void setIgnoreFieldCodes(boolean value)
Sets a boolean value indicating either to ignore text inside field codes. The default value is false .
Remarks:
This option affects only field codes (it does not ignore nodes between NodeType.FIELD_SEPARATOR and NodeType.FIELD_END).
To ignore whole field, please use corresponding option getIgnoreFields() / setIgnoreFields(boolean).
Examples:
Shows how to ignore text inside field codes.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertField("INCLUDETEXT", "Test IT!");
FindReplaceOptions options = new FindReplaceOptions(); {options.setIgnoreFieldCodes(ignoreFieldCodes);}
// Replace 'T' in document ignoring text inside field code or not.
doc.getRange().replace(Pattern.compile("T"), "*", options);
System.out.println(doc.getText());
Assert.assertEquals(
ignoreFieldCodes
? "INCLUDETEXT*est I*!"
: "INCLUDE*EX**est I*!", doc.getText().trim());
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | boolean | A boolean value indicating either to ignore text inside field codes. |
setIgnoreFields(boolean value)
public void setIgnoreFields(boolean value)
Sets a boolean value indicating either to ignore text inside fields. The default value is false .
Remarks:
This option affects whole field (all nodes between NodeType.FIELD_START and NodeType.FIELD_END).
To ignore only field codes, please use corresponding option getIgnoreFieldCodes() / setIgnoreFieldCodes(boolean).
Examples:
Shows how to ignore text inside fields.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Hello world!");
builder.insertField("QUOTE", "Hello again!");
// We can use a "FindReplaceOptions" object to modify the find-and-replace process.
FindReplaceOptions options = new FindReplaceOptions();
// Set the "IgnoreFields" flag to "true" to get the find-and-replace
// operation to ignore text inside fields.
// Set the "IgnoreFields" flag to "false" to get the find-and-replace
// operation to also search for text inside fields.
options.setIgnoreFields(ignoreTextInsideFields);
doc.getRange().replace("Hello", "Greetings", options);
Assert.assertEquals(
ignoreTextInsideFields
? "Greetings world!\rQUOTEHello again!"
: "Greetings world!\rQUOTEGreetings again!", doc.getText().trim());
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | boolean | A boolean value indicating either to ignore text inside fields. |
setIgnoreFootnotes(boolean value)
public void setIgnoreFootnotes(boolean value)
Sets a boolean value indicating either to ignore footnotes. The default value is false .
Examples:
Shows how to ignore footnotes during a find-and-replace operation.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.write("Lorem ipsum dolor sit amet, consectetur adipiscing elit.");
builder.insertFootnote(FootnoteType.FOOTNOTE, "Lorem ipsum dolor sit amet, consectetur adipiscing elit.");
builder.insertParagraph();
builder.write("Lorem ipsum dolor sit amet, consectetur adipiscing elit.");
builder.insertFootnote(FootnoteType.ENDNOTE, "Lorem ipsum dolor sit amet, consectetur adipiscing elit.");
// Set the "IgnoreFootnotes" flag to "true" to get the find-and-replace
// operation to ignore text inside footnotes.
// Set the "IgnoreFootnotes" flag to "false" to get the find-and-replace
// operation to also search for text inside footnotes.
FindReplaceOptions options = new FindReplaceOptions();
{
options.setIgnoreFootnotes(isIgnoreFootnotes);
}
doc.getRange().replace("Lorem ipsum", "Replaced Lorem ipsum", options);
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | boolean | A boolean value indicating either to ignore footnotes. |
setIgnoreInserted(boolean value)
public void setIgnoreInserted(boolean value)
Sets a boolean value indicating either to ignore text inside insert revisions. The default value is false .
Examples:
Shows how to include or ignore text inside insert revisions during a find-and-replace operation.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Hello world!");
// Start tracking revisions and insert a paragraph. That paragraph will be an insert revision.
doc.startTrackRevisions("John Doe", new Date());
builder.writeln("Hello again!");
doc.stopTrackRevisions();
Assert.assertTrue(doc.getFirstSection().getBody().getParagraphs().get(1).isInsertRevision());
// We can use a "FindReplaceOptions" object to modify the find-and-replace process.
FindReplaceOptions options = new FindReplaceOptions();
// Set the "IgnoreInserted" flag to "true" to get the find-and-replace
// operation to ignore paragraphs that are insert revisions.
// Set the "IgnoreInserted" flag to "false" to get the find-and-replace
// operation to also search for text inside insert revisions.
options.setIgnoreInserted(ignoreTextInsideInsertRevisions);
doc.getRange().replace("Hello", "Greetings", options);
Assert.assertEquals(
ignoreTextInsideInsertRevisions
? "Greetings world!\rHello again!"
: "Greetings world!\rGreetings again!", doc.getText().trim());
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | boolean | A boolean value indicating either to ignore text inside insert revisions. |
setIgnoreShapes(boolean value)
public void setIgnoreShapes(boolean value)
Gets or sets a boolean value indicating either to ignore shapes within a text.
The default value is false .
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | boolean | The corresponding boolean value. |
setIgnoreStructuredDocumentTags(boolean value)
public void setIgnoreStructuredDocumentTags(boolean value)
Sets a boolean value indicating either to ignore content of StructuredDocumentTag. The default value is false .
Remarks:
When this option is set to true , the content of StructuredDocumentTag will be treated as a simple text.
Otherwise, StructuredDocumentTag will be processed as standalone Story and replacing pattern will be searched separately for each StructuredDocumentTag, so that if pattern crosses a StructuredDocumentTag, then replacement will not be performed for such pattern.
Examples:
Shows how to ignore content of tags from replacement.
Document doc = new Document(getMyDir() + "Structured document tags.docx");
// This paragraph contains SDT.
Paragraph p = (Paragraph)doc.getFirstSection().getBody().getChild(NodeType.PARAGRAPH, 2, true);
String textToSearch = p.toString(SaveFormat.TEXT).trim();
FindReplaceOptions options = new FindReplaceOptions();
options.setIgnoreStructuredDocumentTags(true);
doc.getRange().replace(textToSearch, "replacement", options);
doc.save(getArtifactsDir() + "StructuredDocumentTag.IgnoreStructuredDocumentTags.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | boolean | A boolean value indicating either to ignore content of StructuredDocumentTag. |
setLegacyMode(boolean value)
public void setLegacyMode(boolean value)
Sets a boolean value indicating that old find/replace algorithm is used.
Remarks:
Use this flag if you need exactly the same behavior as before advanced find/replace feature was introduced. Note that old algorithm does not support advanced features such as replace with breaks, apply formatting and so on.
Examples:
Shows how to recognize and use substitutions within replacement patterns.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.write("Jason gave money to Paul.");
String regex = "([A-z]+) gave money to ([A-z]+)";
FindReplaceOptions options = new FindReplaceOptions();
options.setUseSubstitutions(true);
// Using legacy mode does not support many advanced features, so we need to set it to 'false'.
options.setLegacyMode(false);
doc.getRange().replace(Pattern.compile(regex), "$2 took money from $1", options);
Assert.assertEquals(doc.getText(), "Paul took money from Jason.\f");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | boolean | A boolean value indicating that old find/replace algorithm is used. |
setMatchCase(boolean value)
public void setMatchCase(boolean value)
True indicates case-sensitive comparison, false indicates case-insensitive comparison.
Examples:
Shows how to toggle case sensitivity when performing a find-and-replace operation.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Ruby bought a ruby necklace.");
// We can use a "FindReplaceOptions" object to modify the find-and-replace process.
FindReplaceOptions options = new FindReplaceOptions();
// Set the "MatchCase" flag to "true" to apply case sensitivity while finding strings to replace.
// Set the "MatchCase" flag to "false" to ignore character case while searching for text to replace.
options.setMatchCase(matchCase);
doc.getRange().replace("Ruby", "Jade", options);
Assert.assertEquals(matchCase ? "Jade bought a ruby necklace." : "Jade bought a Jade necklace.",
doc.getText().trim());
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | boolean | The corresponding boolean value. |
setReplacingCallback(IReplacingCallback value)
public void setReplacingCallback(IReplacingCallback value)
The user-defined method which is called before every replace occurrence.
Examples:
Shows how to replace all occurrences of a regular expression pattern with another string, while tracking all such replacements.
public void replaceWithCallback() throws Exception {
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("Our new location in New York City is opening tomorrow. " +
"Hope to see all our NYC-based customers at the opening!");
// We can use a "FindReplaceOptions" object to modify the find-and-replace process.
FindReplaceOptions options = new FindReplaceOptions();
// Set a callback that tracks any replacements that the "Replace" method will make.
TextFindAndReplacementLogger logger = new TextFindAndReplacementLogger();
options.setReplacingCallback(logger);
doc.getRange().replace(Pattern.compile("New York City|NYC"), "Washington", options);
Assert.assertEquals("Our new location in (Old value:\"New York City\") Washington is opening tomorrow. " +
"Hope to see all our (Old value:\"NYC\") Washington-based customers at the opening!", doc.getText().trim());
Assert.assertEquals("\"New York City\" converted to \"Washington\" 20 characters into a 21 node." +
"\"NYC\" converted to \"Washington\" 42 characters into a 21 node.", logger.getLog().trim());
}
///
/// Maintains a log of every text replacement done by a find-and-replace operation
/// and notes the original matched text's value.
///
private static class TextFindAndReplacementLogger implements IReplacingCallback {
public int replacing(ReplacingArgs args) {
mLog.append(MessageFormat.format("\"{0}\" converted to \"{1}\" {2} characters into a {3} node.", args.getMatch().group(0), args.getReplacement(), args.getMatchOffset(), args.getMatchNode().getNodeType()));
args.setReplacement(MessageFormat.format("(Old value:\"{0}\") {1}", args.getMatch().group(0), args.getReplacement()));
return ReplaceAction.REPLACE;
}
public String getLog() {
return mLog.toString();
}
private final StringBuilder mLog = new StringBuilder();
}
Shows how to apply a different font to new content via FindReplaceOptions.
public void convertNumbersToHexadecimal() throws Exception {
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.getFont().setName("Arial");
builder.writeln("Numbers that the find-and-replace operation will convert to hexadecimal and highlight:\n" +
"123, 456, 789 and 17379.");
// We can use a "FindReplaceOptions" object to modify the find-and-replace process.
FindReplaceOptions options = new FindReplaceOptions();
// Set the "HighlightColor" property to a background color that we want to apply to the operation's resulting text.
options.getApplyFont().setHighlightColor(Color.GRAY);
NumberHexer numberHexer = new NumberHexer();
options.setReplacingCallback(numberHexer);
int replacementCount = doc.getRange().replace(Pattern.compile("[0-9]+"), "", options);
System.out.println(numberHexer.getLog());
Assert.assertEquals(4, replacementCount);
Assert.assertEquals("Numbers that the find-and-replace operation will convert to hexadecimal and highlight:\r" +
"0x123, 0x456, 0x789 and 0x17,379.", doc.getText().trim());
}
///
/// Replaces numeric find-and-replacement matches with their hexadecimal equivalents.
/// Maintains a log of every replacement.
///
private static class NumberHexer implements IReplacingCallback {
public int replacing(ReplacingArgs args) {
mCurrentReplacementNumber++;
int number = Integer.parseInt(args.getMatch().group(0));
args.setReplacement(MessageFormat.format("0x{0}", number));
mLog.append(MessageFormat.format("Match #{0}", mCurrentReplacementNumber));
mLog.append(MessageFormat.format("\tOriginal value:\t{0}", args.getMatch().group(0)));
mLog.append(MessageFormat.format("\tReplacement:\t{0}", args.getReplacement()));
mLog.append(MessageFormat.format("\tOffset in parent {0} node:\t{1}", args.getMatchNode().getNodeType(), args.getMatchOffset()));
return ReplaceAction.REPLACE;
}
public String getLog() {
return mLog.toString();
}
private int mCurrentReplacementNumber;
private final StringBuilder mLog = new StringBuilder();
}
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | IReplacingCallback | The corresponding IReplacingCallback value. |
setSmartParagraphBreakReplacement(boolean value)
public void setSmartParagraphBreakReplacement(boolean value)
Gets or sets a boolean value indicating either it is allowed to replace paragraph break when there is no next sibling paragraph.
The default value is false .
Remarks:
This option allows to replace paragraph break when there is no next sibling paragraph to which all child nodes can be moved, by finding any (not necessarily sibling) next paragraph after the paragraph being replaced.
Examples:
Shows how to remove paragraph from a table cell with a nested table.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Create table with paragraph and inner table in first cell.
builder.startTable();
builder.insertCell();
builder.write("TEXT1");
builder.startTable();
builder.insertCell();
builder.endTable();
builder.endTable();
builder.writeln();
FindReplaceOptions options = new FindReplaceOptions();
// When the following option is set to 'true', Aspose.Words will remove paragraph's text
// completely with its paragraph mark. Otherwise, Aspose.Words will mimic Word and remove
// only paragraph's text and leaves the paragraph mark intact (when a table follows the text).
options.setSmartParagraphBreakReplacement(isSmartParagraphBreakReplacement);
doc.getRange().replace("TEXT1&p", "", options);
doc.save(getArtifactsDir() + "Table.RemoveParagraphTextAndMark.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | boolean | The corresponding boolean value. |
setUseLegacyOrder(boolean value)
public void setUseLegacyOrder(boolean value)
True indicates that a text search is performed sequentially from top to bottom considering the text boxes. Default value is false .
Examples:
Shows how to change the searching order of nodes when performing a find-and-replace text operation.
public void useLegacyOrder(boolean useLegacyOrder) throws Exception {
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert three runs which we can search for using a regex pattern.
// Place one of those runs inside a text box.
builder.writeln("[tag 1]");
Shape textBox = builder.insertShape(ShapeType.TEXT_BOX, 100.0, 50.0);
builder.writeln("[tag 2]");
builder.moveTo(textBox.getFirstParagraph());
builder.write("[tag 3]");
// We can use a "FindReplaceOptions" object to modify the find-and-replace process.
FindReplaceOptions options = new FindReplaceOptions();
// Assign a custom callback to the "ReplacingCallback" property.
TextReplacementTracker callback = new TextReplacementTracker();
options.setReplacingCallback(callback);
// If we set the "UseLegacyOrder" property to "true", the
// find-and-replace operation will go through all the runs outside of a text box
// before going through the ones inside a text box.
// If we set the "UseLegacyOrder" property to "false", the
// find-and-replace operation will go over all the runs in a range in sequential order.
options.setUseLegacyOrder(useLegacyOrder);
doc.getRange().replace("\[tag d*\]", "", options);
}
public static Object[][] useLegacyOrderDataProvider() {
return new Object[][]
{
{true},
{false},
};
}
///
/// Records the order of all matches that occur during a find-and-replace operation.
///
private static class TextReplacementTracker implements IReplacingCallback {
public int replacing(ReplacingArgs e) {
mMatches.add(e.getMatch().group(1));
return ReplaceAction.REPLACE;
}
public ArrayList getMatches() {
return mMatches;
}
private ArrayList mMatches;
}
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | boolean | The corresponding boolean value. |
setUseSubstitutions(boolean value)
public void setUseSubstitutions(boolean value)
Sets a boolean value indicating whether to recognize and use substitutions within replacement patterns. The default value is false .
Remarks:
For the details on substitution elements please refer to: https://docs.microsoft.com/en-us/dotnet/standard/base-types/substitutions-in-regular-expressions.
Examples:
Shows how to recognize and use substitutions within replacement patterns.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.write("Jason gave money to Paul.");
String regex = "([A-z]+) gave money to ([A-z]+)";
FindReplaceOptions options = new FindReplaceOptions();
options.setUseSubstitutions(true);
// Using legacy mode does not support many advanced features, so we need to set it to 'false'.
options.setLegacyMode(false);
doc.getRange().replace(Pattern.compile(regex), "$2 took money from $1", options);
Assert.assertEquals(doc.getText(), "Paul took money from Jason.\f");
Shows how to replace the text with substitutions.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("John sold a car to Paul.");
builder.writeln("Jane sold a house to Joe.");
// We can use a "FindReplaceOptions" object to modify the find-and-replace process.
FindReplaceOptions options = new FindReplaceOptions();
// Set the "UseSubstitutions" property to "true" to get
// the find-and-replace operation to recognize substitution elements.
// Set the "UseSubstitutions" property to "false" to ignore substitution elements.
options.setUseSubstitutions(useSubstitutions);
doc.getRange().replace(Pattern.compile("([A-z]+) sold a ([A-z]+) to ([A-z]+)"), "$3 bought a $2 from $1", options);
Assert.assertEquals(
useSubstitutions
? "Paul bought a car from John.\rJoe bought a house from Jane."
: "$3 bought a $2 from $1.\r$3 bought a $2 from $1.", doc.getText().trim());
Parameters:
| Parameter | Type | Description |
|---|---|---|
| value | boolean | A boolean value indicating whether to recognize and use substitutions within replacement patterns. |
