com.aspose.words
Class Range

java.lang.Object
    extended by com.aspose.words.Range

public class Range 
extends java.lang.Object

Represents a contiguous area in a document.

The document is represented by a tree of nodes and the nodes provide operations to work with the tree, but some operations are easier to perform if the document is treated as a contiguous sequence of text.

Range is a "facade" interface that provide methods that treat the document or portions of the document as "flat" text regardless of the fact that the document nodes are stored in a tree-like object model.

Range does not contain any text or nodes, it is merely a view or "window" over a fragment of a document.


Property Getters/Setters Summary
BookmarkCollectiongetBookmarks()
           Returns a Bookmarks collection that represents all bookmarks in the range.
FormFieldCollectiongetFormFields()
           Returns a FormFields collection that represents all form fields in the range.
java.lang.StringgetText()
           Gets the text of the range.
 
Method Summary
voiddelete()
           Deletes all characters of the range.
intreplace(java.lang.String oldValue, java.lang.String newValue, boolean isMatchCase, boolean isMatchWholeWord)
           Replaces all occurrences of a specified string with another string.
intreplace(java.util.regex.Pattern pattern, ReplaceEvaluator evaluator, boolean isForward)
           Finds all occurrences of a character pattern specified by a regular expression and calls a user defined replace evaluator method.
intreplace(java.util.regex.Pattern pattern, java.lang.String replacement)
           Replaces all occurrences of a character pattern specified by a regular expression with another string.
voidupdateFields()
           Updates the values of document fields in this range.
 

Property Getters/Setters Detail

getText

public java.lang.String getText()
Gets the text of the range.

The returned string includes all control and special characters as described in ControlChar.


getFormFields

public FormFieldCollection getFormFields()
Returns a FormFields collection that represents all form fields in the range.

getBookmarks

public BookmarkCollection getBookmarks()
Returns a Bookmarks collection that represents all bookmarks in the range.

Method Detail

delete

public void delete()
           throws java.lang.Exception
Deletes all characters of the range.

Example:

Shows how to delete a section from a Word document.
// Open Word document.
Document doc = new Document(getMyDir() + "Range.DeleteSection.doc");

// The document contains two sections. Each section has a paragraph of text.
Assert.assertEquals("Hello1\u000cHello2\u000c", doc.getText());

// Delete the first section from the document.
doc.getSections().get(0).getRange().delete();

// Check the first section was deleted by looking at the text of the whole document again.
Assert.assertEquals("Hello2\u000c", doc.getText());

replace

public int replace(java.lang.String oldValue, java.lang.String newValue, boolean isMatchCase, boolean isMatchWholeWord)
           throws java.lang.Exception
Replaces all occurrences of a specified string with another string.

An exception is thrown if a captured or replacement string contain one or more special characters: paragraph break, cell break, section break, field start, field separator, field end, inline picture, drawing object, footnote.

Parameters:
oldValue - A string to be replaced.
newValue - A string to replace all occurrences of oldValue.
isMatchCase - True indicates case-sensitive comparison, false indicates case-insensitive comparision.
isMatchWholeWord - True indicates the oldValue must be a standalone word.
Returns:
The number of replacements made.

Example:

Shows how to replace text in the document footer.
// Open the template document, containing obsolete copyright information in the footer.
Document doc = new Document(getMyDir() + "HeaderFooter.ReplaceText.doc");

HeaderFooterCollection headersFooters = doc.getFirstSection().getHeadersFooters();
HeaderFooter footer = headersFooters.getByHeaderFooterType(HeaderFooterType.FOOTER_PRIMARY);
footer.getRange().replace("(C) 2006 Aspose Pty Ltd.", "Copyright (C) 2008 by Aspose Pty Ltd.", false, false);

doc.save(getMyDir() + "HeaderFooter.ReplaceText Out.doc");

Example:

Simple find and replace operation.
// Open the document.
Document doc = new Document(getMyDir() + "Range.ReplaceSimple.doc");

// Check the document contains what we are about to test.
Assert.assertEquals("Hello _CustomerName_,\r", doc.getFirstSection().getBody().getParagraphs().get(0).getText());

// Replace the text in the document.
doc.getRange().replace("_CustomerName_", "James Bond", false, false);

// Save the modified document.
doc.save(getMyDir() + "Range.ReplaceSimple Out.doc");

replace

public int replace(java.util.regex.Pattern pattern, java.lang.String replacement)
           throws java.lang.Exception
Replaces all occurrences of a character pattern specified by a regular expression with another string.

Replaces the whole match captured by the regular expression.

An exception is thrown if a captured or replacement string contain one or more special characters: paragraph break, cell break, section break, field start, field separator, field end, inline picture, drawing object, footnote.

Parameters:
pattern - A regular expression pattern used to find matches.
replacement - A string to replace all occurrences of oldValue.
Returns:
The number of replacements made.

replace

public int replace(java.util.regex.Pattern pattern, ReplaceEvaluator evaluator, boolean isForward)
           throws java.lang.Exception
Finds all occurrences of a character pattern specified by a regular expression and calls a user defined replace evaluator method.

An exception is thrown if a captured or replacement string contain one or more special characters: paragraph break, cell break, section break, field start, field separator, field end, inline picture, drawing object, footnote.

Parameters:
pattern - A regular expression pattern used to find matches.
evaluator - The user-defined method which evaluates replacement at each step.
isForward - True to replace from the beginning of the range to the end.
Returns:
The number of replacements made.

updateFields

public void updateFields()
                 throws java.lang.Exception
Updates the values of document fields in this range.

When you open, modify and then save a document, Aspose.Words does not update fields automatically, it keeps them intact. Therefore, you would usually want to call this method before saving if you have modified the document programmatically and want to make sure the proper (calculated) field values appear in the saved document.

There is no need to update fields after executing a mail merge because mail merge is a kind of field update and automatically updates all fields in the document.

This method does not update all field types. For the detailed list of supported field types, see the Programmers Guide.

This method does not update fields that are related to the page layout algorithms (e.g. PAGE, PAGES, PAGEREF). The page layout-related fields are updated when you render a document or call Document.updatePageLayout().

To update fields in the whole document use Document.updateFields().


See Also:
          Aspose.Words Documentation - the home page for the Aspose.Words Product Documentation.
          Aspose.Words Support Forum - our preferred method of support.