Detailed Description

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.

Examples

Shows how to get plain, unformatted text of a range.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->Write(u"Hello world!");
ASSERT_EQ(u"Hello world!", doc->get_Range()->get_Text().Trim());

#include <Aspose.Words.Cpp/Model/Text/Range.h>

+ Inheritance diagram for Aspose::Words::Range:

Public Member Functions

void Delete ()
 Deletes all characters of the range. More...
 
SharedPtr< BookmarkCollectionget_Bookmarks ()
 Returns a Bookmarks collection that represents all bookmarks in the range. More...
 
SharedPtr< FieldCollectionget_Fields ()
 Returns a Fields collection that represents all fields in the range. More...
 
SharedPtr< FormFieldCollectionget_FormFields ()
 Returns a FormFields collection that represents all form fields in the range. More...
 
String get_Text ()
 Gets the text of the range. More...
 
virtual const TypeInfoGetType () const override
 
virtual bool Is (const TypeInfo &target) const override
 
void NormalizeFieldTypes ()
 Changes field type values FieldType of FieldStart, FieldSeparator, FieldEnd in this range so that they correspond to the field types contained in the field codes. More...
 
int32_t Replace (SharedPtr< Regex > pattern, String replacement)
 Replaces all occurrences of a character pattern specified by a regular expression with another string. More...
 
int32_t Replace (SharedPtr< Regex > pattern, String replacement, SharedPtr< FindReplaceOptions > options)
 Replaces all occurrences of a character pattern specified by a regular expression with another string. More...
 
int32_t Replace (String pattern, String replacement)
 Replaces all occurrences of a character pattern specified by a regular expression with another string. More...
 
int32_t Replace (String pattern, String replacement, SharedPtr< FindReplaceOptions > options)
 Replaces all occurrences of a character pattern specified by a regular expression with another string. More...
 
SharedPtr< DocumentToDocument ()
 Constructs a new fully formed document that contains the range. More...
 
void UnlinkFields ()
 Unlinks fields in this range. More...
 
void UpdateFields ()
 Updates the values of document fields in this range. More...
 
- Public Member Functions inherited from Object
ASPOSECPP_SHARED_API Object ()
 
ASPOSECPP_SHARED_API Object (Object const &x)
 
virtual ASPOSECPP_SHARED_API ~Object ()
 
virtual ASPOSECPP_SHARED_API bool Equals (ptr obj)
 
Detail::SmartPtrCounter * GetCounter ()
 
virtual ASPOSECPP_SHARED_API int GetHashCode () const
 
ASPOSECPP_SHARED_API void Lock ()
 
virtual ASPOSECPP_SHARED_API ptr MemberwiseClone () const
 
Objectoperator= (Object const &x)
 
bool ReferenceEquals (String const &str, std::nullptr_t)
 
bool ReferenceEquals (String const &str1, String const &str2)
 
int RemovedSharedRefs (int count)
 
virtual ASPOSECPP_SHARED_API void SetTemplateWeakPtr (unsigned int argument)
 
int SharedCount () const
 
ObjectSharedRefAdded ()
 
int SharedRefRemovedSafe ()
 
virtual ASPOSECPP_SHARED_API String ToString () const
 
ASPOSECPP_SHARED_API void Unlock ()
 
Detail::SmartPtrCounter * WeakRefAdded ()
 
void WeakRefRemoved ()
 

Static Public Member Functions

static const TypeInfoType ()
 
- Static Public Member Functions inherited from Object
bool Equals (double const &objA, double const &objB)
 
bool Equals (float const &objA, float const &objB)
 
static std::enable_if<!IsSmartPtr< T1 >::value &&!IsSmartPtr< T2 >::value, bool >::type Equals (T1 const &objA, T2 const &objB)
 
static std::enable_if< IsSmartPtr< T1 >::value &&IsSmartPtr< T2 >::value, bool >::type Equals (T1 const &objA, T2 const &objB)
 
static bool ReferenceEquals (ptr const &objA, ptr const &objB)
 
static std::enable_if<!IsSmartPtr< T >::value, bool >::type ReferenceEquals (T const &objA, std::nullptr_t)
 
static std::enable_if<!IsSmartPtr< T >::value, bool >::type ReferenceEquals (T const &objA, T const &objB)
 
static const TypeInfoType ()
 

Additional Inherited Members

- Public Types inherited from Object
typedef SmartPtr< Objectptr
 
typedef System::Details::SharedMembersType shared_members_type
 

Member Function Documentation

◆ Delete()

void Aspose::Words::Range::Delete ( )

Deletes all characters of the range.

Examples

Shows how to delete all characters of a range.

// Insert two sections into a blank document
auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->Write(u"Section 1. ");
builder->InsertBreak(BreakType::SectionBreakContinuous);
builder->Write(u"Section 2.");
// Verify the whole text of the document
ASSERT_EQ(u"Section 1. \fSection 2.", doc->GetText().Trim());
// Delete the first section from the document
doc->get_Sections()->idx_get(0)->get_Range()->Delete();
// Check the first section was deleted by looking at the text of the whole document again
ASSERT_EQ(u"Section 2.", doc->GetText().Trim());

◆ get_Bookmarks()

System::SharedPtr<Aspose::Words::BookmarkCollection> Aspose::Words::Range::get_Bookmarks ( )

Returns a Bookmarks collection that represents all bookmarks in the range.

◆ get_Fields()

System::SharedPtr<Aspose::Words::Fields::FieldCollection> Aspose::Words::Range::get_Fields ( )

Returns a Fields collection that represents all fields in the range.

◆ get_FormFields()

System::SharedPtr<Aspose::Words::Fields::FormFieldCollection> Aspose::Words::Range::get_FormFields ( )

Returns a FormFields collection that represents all form fields in the range.

◆ get_Text()

System::String Aspose::Words::Range::get_Text ( )

Gets the text of the range.

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

Examples

Shows how to get plain, unformatted text of a range.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->Write(u"Hello world!");
ASSERT_EQ(u"Hello world!", doc->get_Range()->get_Text().Trim());

◆ GetType()

virtual const System::TypeInfo& Aspose::Words::Range::GetType ( ) const
overridevirtual

Reimplemented from System::Object.

◆ Is()

virtual bool Aspose::Words::Range::Is ( const System::TypeInfo target) const
overridevirtual

Reimplemented from System::Object.

◆ NormalizeFieldTypes()

void Aspose::Words::Range::NormalizeFieldTypes ( )

Changes field type values FieldType of FieldStart, FieldSeparator, FieldEnd in this range so that they correspond to the field types contained in the field codes.

Use this method after document changes that affect field types.

To change field type values in the whole document use NormalizeFieldTypes.

◆ Replace() [1/4]

int32_t Aspose::Words::Range::Replace ( System::SharedPtr< System::Text::RegularExpressions::Regex pattern,
System::String  replacement 
)

Replaces all occurrences of a character pattern specified by a regular expression with another string.

Replaces the whole match captured by the regular expression.

Method is able to process breaks in both pattern and replacement strings.

You should use special meta-characters if you need to work with breaks:

  • &p - paragraph break
  • &b - section break
  • &m - page break
  • &l - manual line break
Parameters
patternA regular expression pattern used to find matches.
replacementA string to replace all occurrences of pattern.
Returns
The number of replacements made.

◆ Replace() [2/4]

int32_t Aspose::Words::Range::Replace ( System::SharedPtr< System::Text::RegularExpressions::Regex pattern,
System::String  replacement,
System::SharedPtr< Aspose::Words::Replacing::FindReplaceOptions options 
)

Replaces all occurrences of a character pattern specified by a regular expression with another string.

Replaces the whole match captured by the regular expression.

Method is able to process breaks in both pattern and replacement strings.

You should use special meta-characters if you need to work with breaks:

  • &p - paragraph break
  • &b - section break
  • &m - page break
  • &l - manual line break
  • && - & character
Parameters
patternA regular expression pattern used to find matches.
replacementA string to replace all occurrences of pattern.
optionsFindReplaceOptions object to specify additional options.
Returns
The number of replacements made.
Examples

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

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->Writeln(u"sad mad bad");
ASSERT_EQ(u"sad mad bad", doc->GetText().Trim());
auto options = MakeObject<FindReplaceOptions>();
options->set_MatchCase(false);
options->set_FindWholeWordsOnly(false);
doc->get_Range()->Replace(MakeObject<System::Text::RegularExpressions::Regex>(u"[s|m]ad"), u"bad", options);
ASSERT_EQ(u"bad bad bad", doc->GetText().Trim());

◆ Replace() [3/4]

int32_t Aspose::Words::Range::Replace ( System::String  pattern,
System::String  replacement 
)

Replaces all occurrences of a character pattern specified by a regular expression with another string.

Used case-insensitive comparison.

Replaces the whole match captured by the regular expression.

Method is able to process breaks in both pattern and replacement strings.

You should use special meta-characters if you need to work with breaks:

  • &p - paragraph break
  • &b - section break
  • &m - page break
  • &l - manual line break
Parameters
patternA string to be replaced.
replacementA string to replace all occurrences of pattern.
Returns
The number of replacements made.

◆ Replace() [4/4]

int32_t Aspose::Words::Range::Replace ( System::String  pattern,
System::String  replacement,
System::SharedPtr< Aspose::Words::Replacing::FindReplaceOptions options 
)

Replaces all occurrences of a character pattern specified by a regular expression with another string.

Replaces the whole match captured by the regular expression.

Method is able to process breaks in both pattern and replacement strings.

You should use special meta-characters if you need to work with breaks:

  • &p - paragraph break
  • &b - section break
  • &m - page break
  • &l - manual line break
  • && - & character
Parameters
patternA string to be replaced.
replacementA string to replace all occurrences of pattern.
optionsFindReplaceOptions object to specify additional options.
Returns
The number of replacements made.
Examples

Shows how to replace text in the document footer.

// Open the template document, containing obsolete copyright information in the footer
auto doc = MakeObject<Document>(MyDir + u"Footer.docx");
SharedPtr<HeaderFooterCollection> headersFooters = doc->get_FirstSection()->get_HeadersFooters();
SharedPtr<HeaderFooter> footer = headersFooters->idx_get(HeaderFooterType::FooterPrimary);
auto options = MakeObject<FindReplaceOptions>();
options->set_MatchCase(false);
options->set_FindWholeWordsOnly(false);
int currentYear = System::DateTime::get_Now().get_Year();
footer->get_Range()->Replace(u"(C) 2006 Aspose Pty Ltd.", String::Format(u"Copyright (C) {0} by Aspose Pty Ltd.", currentYear), options);
doc->Save(ArtifactsDir + u"HeaderFooter.ReplaceText.docx");

Simple find and replace operation.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->Writeln(u"Hello _CustomerName_,");
// Check the document contains what we are about to test
System::Console::WriteLine(doc->get_FirstSection()->get_Body()->get_Paragraphs()->idx_get(0)->GetText());
auto options = MakeObject<FindReplaceOptions>();
options->set_MatchCase(false);
options->set_FindWholeWordsOnly(false);
doc->get_Range()->Replace(u"_CustomerName_", u"James Bond", options);
doc->Save(ArtifactsDir + u"Range.ReplaceSimple.docx");

Shows how to replace all instances of String of text in a table and cell.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Create a table and give it conditional styling on border colors based on the row being the first or last
SharedPtr<Table> table = builder->StartTable();
builder->InsertCell();
builder->Write(u"Carrots");
builder->InsertCell();
builder->Write(u"30");
builder->EndRow();
builder->InsertCell();
builder->Write(u"Potatoes");
builder->InsertCell();
builder->Write(u"50");
builder->EndTable();
auto options = MakeObject<FindReplaceOptions>();
options->set_MatchCase(true);
options->set_FindWholeWordsOnly(true);
// Replace any instances of our String in the entire table
table->get_Range()->Replace(u"Carrots", u"Eggs", options);
// Replace any instances of our String in the last cell of the table only
table->get_LastRow()->get_LastCell()->get_Range()->Replace(u"50", u"20", options);
doc->Save(ArtifactsDir + u"Table.ReplaceCellText.docx");

◆ ToDocument()

System::SharedPtr<Aspose::Words::Document> Aspose::Words::Range::ToDocument ( )

Constructs a new fully formed document that contains the range.

◆ Type()

static const System::TypeInfo& Aspose::Words::Range::Type ( )
static

◆ UnlinkFields()

void Aspose::Words::Range::UnlinkFields ( )

Unlinks fields in this range.

Replaces all the fields in this range with their most recent results.

To unlink fields in the whole document use UnlinkFields.

Examples

Shows how to unlink all fields in range.

auto doc = MakeObject<Document>(MyDir + u"Linked fields.docx");
auto newSection = System::DynamicCast<Section>(System::StaticCast<Node>(doc->get_Sections()->idx_get(0))->Clone(true));
doc->get_Sections()->Add(newSection);
doc->get_Sections()->idx_get(1)->get_Range()->UnlinkFields();

◆ UpdateFields()

void Aspose::Words::Range::UpdateFields ( )

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 UpdatePageLayout.

To update fields in the whole document use UpdateFields.

Examples

Shows how to update document fields in the body of the first section only.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Insert a field that will display the value in the document's body text
auto field = System::DynamicCast<FieldDocProperty>(builder->InsertField(u" DOCPROPERTY Category"));
// Set the value of the property that should be displayed by the field
doc->get_BuiltInDocumentProperties()->set_Category(u"MyCategory");
// Some field types need to be explicitly updated before they can display their expected values
ASSERT_EQ(String::Empty, field->get_Result());
// Update all the fields in the first section of the document, which includes the field we just inserted
doc->get_FirstSection()->get_Range()->UpdateFields();
ASSERT_EQ(u"MyCategory", field->get_Result());
static ASPOSECPP_SHARED_API DateTime get_Now()
static ASPOSECPP_SHARED_API void WriteLine()
ASPOSECPP_SHARED_API int get_Year() const
@ FooterPrimary
Primary footer, also used for odd numbered pages.
@ SectionBreakContinuous
Specifies start of new section on the same page as the previous section.