Aspose::Words::VariableCollection class

VariableCollection class

A collection of document variables. To learn more, visit the Work with Document Properties documentation article.

class VariableCollection : public System::Collections::Generic::IEnumerable<System::Collections::Generic::KeyValuePair<System::String, System::String>>

Methods

MethodDescription
Add(const System::String&, const System::String&)Adds a document variable to the collection.
begin()
begin() const
cbegin() const
cend() const
Clear()Removes all elements from the collection.
Contains(const System::String&)Determines whether the collection contains a document variable with the given name.
end()
end() const
get_Count()Gets the number of elements contained in the collection.
GetEnumerator() overrideReturns an enumerator object that can be used to iterate over all variable in the collection.
GetType() const override
idx_get(const System::String&)Gets or a sets a document variable by the case-insensitive name. null values are not allowed as a right hand side of the assignment and will be replaced by empty string.
idx_get(int32_t)Gets or sets a document variable at the specified index. null values are not allowed as a right hand side of the assignment and will be replaced by empty string.
idx_set(const System::String&, const System::String&)Gets or a sets a document variable by the case-insensitive name. null values are not allowed as a right hand side of the assignment and will be replaced by empty string.
idx_set(int32_t, const System::String&)Gets or sets a document variable at the specified index. null values are not allowed as a right hand side of the assignment and will be replaced by empty string.
IndexOfKey(const System::String&)Returns the zero-based index of the specified document variable in the collection.
Is(const System::TypeInfo&) const override
Remove(const System::String&)Removes a document variable with the specified name from the collection.
RemoveAt(int32_t)Removes a document variable at the specified index.
static Type()
virtualizeBeginConstIterator() const override
virtualizeBeginIterator() override
virtualizeEndConstIterator() const override
virtualizeEndIterator() override

Typedefs

TypedefDescription
const_iterator
iterator
iterator_holder_type
virtualized_iterator
virtualized_iterator_element

Remarks

Variable names and values are strings.

Variable names are case-insensitive.

Examples

Shows how to work with a document’s variable collection.

auto doc = MakeObject<Document>();
SharedPtr<VariableCollection> variables = doc->get_Variables();

// Every document has a collection of key/value pair variables, which we can add items to.
variables->Add(u"Home address", u"123 Main St.");
variables->Add(u"City", u"London");
variables->Add(u"Bedrooms", u"3");

ASSERT_EQ(3, variables->get_Count());

// We can display the values of variables in the document body using DOCVARIABLE fields.
auto builder = MakeObject<DocumentBuilder>(doc);
auto field = System::ExplicitCast<FieldDocVariable>(builder->InsertField(FieldType::FieldDocVariable, true));
field->set_VariableName(u"Home address");
field->Update();

ASSERT_EQ(u"123 Main St.", field->get_Result());

// Assigning values to existing keys will update them.
variables->Add(u"Home address", u"456 Queen St.");

// We will then have to update DOCVARIABLE fields to ensure they display an up-to-date value.
ASSERT_EQ(u"123 Main St.", field->get_Result());

field->Update();

ASSERT_EQ(u"456 Queen St.", field->get_Result());

// Verify that the document variables with a certain name or value exist.
ASSERT_TRUE(variables->Contains(u"City"));
ASSERT_TRUE(variables->LINQ_Any([](auto v) { return v.get_Value() == u"London"; }));

// The collection of variables automatically sorts variables alphabetically by name.
ASSERT_EQ(0, variables->IndexOfKey(u"Bedrooms"));
ASSERT_EQ(1, variables->IndexOfKey(u"City"));
ASSERT_EQ(2, variables->IndexOfKey(u"Home address"));

// Enumerate over the collection of variables.
{
    SharedPtr<System::Collections::Generic::IEnumerator<System::Collections::Generic::KeyValuePair<String, String>>> enumerator =
        doc->get_Variables()->GetEnumerator();
    while (enumerator->MoveNext())
    {
        std::cout << "Name: " << enumerator->get_Current().get_Key() << ", Value: " << enumerator->get_Current().get_Value() << std::endl;
    }
}

// Below are three ways of removing document variables from a collection.
// 1 -  By name:
variables->Remove(u"City");

ASSERT_FALSE(variables->Contains(u"City"));

// 2 -  By index:
variables->RemoveAt(1);

ASSERT_FALSE(variables->Contains(u"Home address"));

// 3 -  Clear the whole collection at once:
variables->Clear();

ASSERT_EQ(0, variables->get_Count());

See Also