com.aspose.words

Class VariableCollection

  • java.lang.Object
    • com.aspose.words.VariableCollection
  • All Implemented Interfaces:
    java.lang.Iterable
    public class VariableCollection 
    extends java.lang.Object

A collection of document variables.

Variable names and values are strings.

Variable names are case-insensitive.

Example:

Shows how to work with a document's variable collection.
Document doc = new Document();
VariableCollection variables = doc.getVariables();

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

Assert.assertEquals(3, variables.getCount());

// We can display the values of variables in the document body using DOCVARIABLE fields.
DocumentBuilder builder = new DocumentBuilder(doc);
FieldDocVariable field = (FieldDocVariable) builder.insertField(FieldType.FIELD_DOC_VARIABLE, true);
field.setVariableName("Home address");
field.update();

Assert.assertEquals("123 Main St.", field.getResult());

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

// We will then have to update DOCVARIABLE fields to ensure they display an up-to-date value.
Assert.assertEquals("123 Main St.", field.getResult());

field.update();

Assert.assertEquals("456 Queen St.", field.getResult());

// Verify that the document variables with a certain name or value exist.
Assert.assertTrue(variables.contains("City"));
Assert.assertTrue(IterableUtils.matchesAny(variables, s -> s.getValue() == "London"));

// The collection of variables automatically sorts variables alphabetically by name.
Assert.assertEquals(0, variables.indexOfKey("Bedrooms"));
Assert.assertEquals(1, variables.indexOfKey("City"));
Assert.assertEquals(2, variables.indexOfKey("Home address"));

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

Assert.assertFalse(variables.contains("City"));

// 2 -  By index:
variables.removeAt(1);

Assert.assertFalse(variables.contains("Home address"));

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

Assert.assertEquals(variables.getCount(), 0);

Property Getters/Setters Summary
intgetCount()
Gets the number of elements contained in the collection.
java.lang.Stringget(int index)
void
set(intindex, java.lang.Stringvalue)
           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.
java.lang.Stringget(java.lang.String name)
void
set(java.lang.Stringname, java.lang.Stringvalue)
           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.
 
Method Summary
voidadd(java.lang.String name, java.lang.String value)
Adds a document variable to the collection.
voidclear()
Removes all elements from the collection.
booleancontains(java.lang.String name)
Determines whether the collection contains a document variable with the given name.
intindexOfKey(java.lang.String name)
Returns the zero-based index of the specified document variable in the collection.
java.util.Iterator<java.util.Map.Entry<java.lang.String, java.lang.String>>iterator()
Returns an enumerator object that can be used to iterate over all variable in the collection.
voidremove(java.lang.String name)
Removes a document variable with the specified name from the collection.
voidremoveAt(int index)
Removes a document variable at the specified index.
 

    • Property Getters/Setters Detail

      • getCount

        public int getCount()
        
        Gets the number of elements contained in the collection.

        Example:

        Shows how to work with a document's variable collection.
        Document doc = new Document();
        VariableCollection variables = doc.getVariables();
        
        // Every document has a collection of key/value pair variables, which we can add items to.
        variables.add("Home address", "123 Main St.");
        variables.add("City", "London");
        variables.add("Bedrooms", "3");
        
        Assert.assertEquals(3, variables.getCount());
        
        // We can display the values of variables in the document body using DOCVARIABLE fields.
        DocumentBuilder builder = new DocumentBuilder(doc);
        FieldDocVariable field = (FieldDocVariable) builder.insertField(FieldType.FIELD_DOC_VARIABLE, true);
        field.setVariableName("Home address");
        field.update();
        
        Assert.assertEquals("123 Main St.", field.getResult());
        
        // Assigning values to existing keys will update them.
        variables.add("Home address", "456 Queen St.");
        
        // We will then have to update DOCVARIABLE fields to ensure they display an up-to-date value.
        Assert.assertEquals("123 Main St.", field.getResult());
        
        field.update();
        
        Assert.assertEquals("456 Queen St.", field.getResult());
        
        // Verify that the document variables with a certain name or value exist.
        Assert.assertTrue(variables.contains("City"));
        Assert.assertTrue(IterableUtils.matchesAny(variables, s -> s.getValue() == "London"));
        
        // The collection of variables automatically sorts variables alphabetically by name.
        Assert.assertEquals(0, variables.indexOfKey("Bedrooms"));
        Assert.assertEquals(1, variables.indexOfKey("City"));
        Assert.assertEquals(2, variables.indexOfKey("Home address"));
        
        // Below are three ways of removing document variables from a collection.
        // 1 -  By name:
        variables.remove("City");
        
        Assert.assertFalse(variables.contains("City"));
        
        // 2 -  By index:
        variables.removeAt(1);
        
        Assert.assertFalse(variables.contains("Home address"));
        
        // 3 -  Clear the whole collection at once:
        variables.clear();
        
        Assert.assertEquals(variables.getCount(), 0);
      • get/set

        public java.lang.String get(int index) / public void set(int index, java.lang.String value)
        
        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.
        Parameters:
        index - Zero-based index of the document variable.
      • get/set

        public java.lang.String get(java.lang.String name) / public void set(java.lang.String name, java.lang.String value)
        
        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.
    • Method Detail

      • add

        public void add(java.lang.String name, java.lang.String value)
        Adds a document variable to the collection.
        Parameters:
        name - The case-insensitive name of the variable to add.
        value - The value of the variable. The value cannot be null, if value is null empty string will be used instead.

        Example:

        Shows how to work with a document's variable collection.
        Document doc = new Document();
        VariableCollection variables = doc.getVariables();
        
        // Every document has a collection of key/value pair variables, which we can add items to.
        variables.add("Home address", "123 Main St.");
        variables.add("City", "London");
        variables.add("Bedrooms", "3");
        
        Assert.assertEquals(3, variables.getCount());
        
        // We can display the values of variables in the document body using DOCVARIABLE fields.
        DocumentBuilder builder = new DocumentBuilder(doc);
        FieldDocVariable field = (FieldDocVariable) builder.insertField(FieldType.FIELD_DOC_VARIABLE, true);
        field.setVariableName("Home address");
        field.update();
        
        Assert.assertEquals("123 Main St.", field.getResult());
        
        // Assigning values to existing keys will update them.
        variables.add("Home address", "456 Queen St.");
        
        // We will then have to update DOCVARIABLE fields to ensure they display an up-to-date value.
        Assert.assertEquals("123 Main St.", field.getResult());
        
        field.update();
        
        Assert.assertEquals("456 Queen St.", field.getResult());
        
        // Verify that the document variables with a certain name or value exist.
        Assert.assertTrue(variables.contains("City"));
        Assert.assertTrue(IterableUtils.matchesAny(variables, s -> s.getValue() == "London"));
        
        // The collection of variables automatically sorts variables alphabetically by name.
        Assert.assertEquals(0, variables.indexOfKey("Bedrooms"));
        Assert.assertEquals(1, variables.indexOfKey("City"));
        Assert.assertEquals(2, variables.indexOfKey("Home address"));
        
        // Below are three ways of removing document variables from a collection.
        // 1 -  By name:
        variables.remove("City");
        
        Assert.assertFalse(variables.contains("City"));
        
        // 2 -  By index:
        variables.removeAt(1);
        
        Assert.assertFalse(variables.contains("Home address"));
        
        // 3 -  Clear the whole collection at once:
        variables.clear();
        
        Assert.assertEquals(variables.getCount(), 0);
      • clear

        public void clear()
        Removes all elements from the collection.

        Example:

        Shows how to work with a document's variable collection.
        Document doc = new Document();
        VariableCollection variables = doc.getVariables();
        
        // Every document has a collection of key/value pair variables, which we can add items to.
        variables.add("Home address", "123 Main St.");
        variables.add("City", "London");
        variables.add("Bedrooms", "3");
        
        Assert.assertEquals(3, variables.getCount());
        
        // We can display the values of variables in the document body using DOCVARIABLE fields.
        DocumentBuilder builder = new DocumentBuilder(doc);
        FieldDocVariable field = (FieldDocVariable) builder.insertField(FieldType.FIELD_DOC_VARIABLE, true);
        field.setVariableName("Home address");
        field.update();
        
        Assert.assertEquals("123 Main St.", field.getResult());
        
        // Assigning values to existing keys will update them.
        variables.add("Home address", "456 Queen St.");
        
        // We will then have to update DOCVARIABLE fields to ensure they display an up-to-date value.
        Assert.assertEquals("123 Main St.", field.getResult());
        
        field.update();
        
        Assert.assertEquals("456 Queen St.", field.getResult());
        
        // Verify that the document variables with a certain name or value exist.
        Assert.assertTrue(variables.contains("City"));
        Assert.assertTrue(IterableUtils.matchesAny(variables, s -> s.getValue() == "London"));
        
        // The collection of variables automatically sorts variables alphabetically by name.
        Assert.assertEquals(0, variables.indexOfKey("Bedrooms"));
        Assert.assertEquals(1, variables.indexOfKey("City"));
        Assert.assertEquals(2, variables.indexOfKey("Home address"));
        
        // Below are three ways of removing document variables from a collection.
        // 1 -  By name:
        variables.remove("City");
        
        Assert.assertFalse(variables.contains("City"));
        
        // 2 -  By index:
        variables.removeAt(1);
        
        Assert.assertFalse(variables.contains("Home address"));
        
        // 3 -  Clear the whole collection at once:
        variables.clear();
        
        Assert.assertEquals(variables.getCount(), 0);
      • contains

        public boolean contains(java.lang.String name)
        Determines whether the collection contains a document variable with the given name.
        Parameters:
        name - Case-insensitive name of the document variable to locate.
        Returns:
        True if item is found in the collection; otherwise, false.

        Example:

        Shows how to work with a document's variable collection.
        Document doc = new Document();
        VariableCollection variables = doc.getVariables();
        
        // Every document has a collection of key/value pair variables, which we can add items to.
        variables.add("Home address", "123 Main St.");
        variables.add("City", "London");
        variables.add("Bedrooms", "3");
        
        Assert.assertEquals(3, variables.getCount());
        
        // We can display the values of variables in the document body using DOCVARIABLE fields.
        DocumentBuilder builder = new DocumentBuilder(doc);
        FieldDocVariable field = (FieldDocVariable) builder.insertField(FieldType.FIELD_DOC_VARIABLE, true);
        field.setVariableName("Home address");
        field.update();
        
        Assert.assertEquals("123 Main St.", field.getResult());
        
        // Assigning values to existing keys will update them.
        variables.add("Home address", "456 Queen St.");
        
        // We will then have to update DOCVARIABLE fields to ensure they display an up-to-date value.
        Assert.assertEquals("123 Main St.", field.getResult());
        
        field.update();
        
        Assert.assertEquals("456 Queen St.", field.getResult());
        
        // Verify that the document variables with a certain name or value exist.
        Assert.assertTrue(variables.contains("City"));
        Assert.assertTrue(IterableUtils.matchesAny(variables, s -> s.getValue() == "London"));
        
        // The collection of variables automatically sorts variables alphabetically by name.
        Assert.assertEquals(0, variables.indexOfKey("Bedrooms"));
        Assert.assertEquals(1, variables.indexOfKey("City"));
        Assert.assertEquals(2, variables.indexOfKey("Home address"));
        
        // Below are three ways of removing document variables from a collection.
        // 1 -  By name:
        variables.remove("City");
        
        Assert.assertFalse(variables.contains("City"));
        
        // 2 -  By index:
        variables.removeAt(1);
        
        Assert.assertFalse(variables.contains("Home address"));
        
        // 3 -  Clear the whole collection at once:
        variables.clear();
        
        Assert.assertEquals(variables.getCount(), 0);
      • indexOfKey

        public int indexOfKey(java.lang.String name)
        Returns the zero-based index of the specified document variable in the collection.
        Parameters:
        name - The case-insensitive name of the variable.
        Returns:
        The zero based index. Negative value if not found.

        Example:

        Shows how to work with a document's variable collection.
        Document doc = new Document();
        VariableCollection variables = doc.getVariables();
        
        // Every document has a collection of key/value pair variables, which we can add items to.
        variables.add("Home address", "123 Main St.");
        variables.add("City", "London");
        variables.add("Bedrooms", "3");
        
        Assert.assertEquals(3, variables.getCount());
        
        // We can display the values of variables in the document body using DOCVARIABLE fields.
        DocumentBuilder builder = new DocumentBuilder(doc);
        FieldDocVariable field = (FieldDocVariable) builder.insertField(FieldType.FIELD_DOC_VARIABLE, true);
        field.setVariableName("Home address");
        field.update();
        
        Assert.assertEquals("123 Main St.", field.getResult());
        
        // Assigning values to existing keys will update them.
        variables.add("Home address", "456 Queen St.");
        
        // We will then have to update DOCVARIABLE fields to ensure they display an up-to-date value.
        Assert.assertEquals("123 Main St.", field.getResult());
        
        field.update();
        
        Assert.assertEquals("456 Queen St.", field.getResult());
        
        // Verify that the document variables with a certain name or value exist.
        Assert.assertTrue(variables.contains("City"));
        Assert.assertTrue(IterableUtils.matchesAny(variables, s -> s.getValue() == "London"));
        
        // The collection of variables automatically sorts variables alphabetically by name.
        Assert.assertEquals(0, variables.indexOfKey("Bedrooms"));
        Assert.assertEquals(1, variables.indexOfKey("City"));
        Assert.assertEquals(2, variables.indexOfKey("Home address"));
        
        // Below are three ways of removing document variables from a collection.
        // 1 -  By name:
        variables.remove("City");
        
        Assert.assertFalse(variables.contains("City"));
        
        // 2 -  By index:
        variables.removeAt(1);
        
        Assert.assertFalse(variables.contains("Home address"));
        
        // 3 -  Clear the whole collection at once:
        variables.clear();
        
        Assert.assertEquals(variables.getCount(), 0);
      • iterator

        public java.util.Iterator<java.util.Map.Entry<java.lang.String, java.lang.String>> iterator()
        Returns an enumerator object that can be used to iterate over all variable in the collection.

        Example:

        Shows how to work with a document's variable collection.
        Document doc = new Document();
        VariableCollection variables = doc.getVariables();
        
        // Every document has a collection of key/value pair variables, which we can add items to.
        variables.add("Home address", "123 Main St.");
        variables.add("City", "London");
        variables.add("Bedrooms", "3");
        
        Assert.assertEquals(3, variables.getCount());
        
        // We can display the values of variables in the document body using DOCVARIABLE fields.
        DocumentBuilder builder = new DocumentBuilder(doc);
        FieldDocVariable field = (FieldDocVariable) builder.insertField(FieldType.FIELD_DOC_VARIABLE, true);
        field.setVariableName("Home address");
        field.update();
        
        Assert.assertEquals("123 Main St.", field.getResult());
        
        // Assigning values to existing keys will update them.
        variables.add("Home address", "456 Queen St.");
        
        // We will then have to update DOCVARIABLE fields to ensure they display an up-to-date value.
        Assert.assertEquals("123 Main St.", field.getResult());
        
        field.update();
        
        Assert.assertEquals("456 Queen St.", field.getResult());
        
        // Verify that the document variables with a certain name or value exist.
        Assert.assertTrue(variables.contains("City"));
        Assert.assertTrue(IterableUtils.matchesAny(variables, s -> s.getValue() == "London"));
        
        // The collection of variables automatically sorts variables alphabetically by name.
        Assert.assertEquals(0, variables.indexOfKey("Bedrooms"));
        Assert.assertEquals(1, variables.indexOfKey("City"));
        Assert.assertEquals(2, variables.indexOfKey("Home address"));
        
        // Below are three ways of removing document variables from a collection.
        // 1 -  By name:
        variables.remove("City");
        
        Assert.assertFalse(variables.contains("City"));
        
        // 2 -  By index:
        variables.removeAt(1);
        
        Assert.assertFalse(variables.contains("Home address"));
        
        // 3 -  Clear the whole collection at once:
        variables.clear();
        
        Assert.assertEquals(variables.getCount(), 0);
      • remove

        public void remove(java.lang.String name)
        Removes a document variable with the specified name from the collection.
        Parameters:
        name - The case-insensitive name of the variable.

        Example:

        Shows how to work with a document's variable collection.
        Document doc = new Document();
        VariableCollection variables = doc.getVariables();
        
        // Every document has a collection of key/value pair variables, which we can add items to.
        variables.add("Home address", "123 Main St.");
        variables.add("City", "London");
        variables.add("Bedrooms", "3");
        
        Assert.assertEquals(3, variables.getCount());
        
        // We can display the values of variables in the document body using DOCVARIABLE fields.
        DocumentBuilder builder = new DocumentBuilder(doc);
        FieldDocVariable field = (FieldDocVariable) builder.insertField(FieldType.FIELD_DOC_VARIABLE, true);
        field.setVariableName("Home address");
        field.update();
        
        Assert.assertEquals("123 Main St.", field.getResult());
        
        // Assigning values to existing keys will update them.
        variables.add("Home address", "456 Queen St.");
        
        // We will then have to update DOCVARIABLE fields to ensure they display an up-to-date value.
        Assert.assertEquals("123 Main St.", field.getResult());
        
        field.update();
        
        Assert.assertEquals("456 Queen St.", field.getResult());
        
        // Verify that the document variables with a certain name or value exist.
        Assert.assertTrue(variables.contains("City"));
        Assert.assertTrue(IterableUtils.matchesAny(variables, s -> s.getValue() == "London"));
        
        // The collection of variables automatically sorts variables alphabetically by name.
        Assert.assertEquals(0, variables.indexOfKey("Bedrooms"));
        Assert.assertEquals(1, variables.indexOfKey("City"));
        Assert.assertEquals(2, variables.indexOfKey("Home address"));
        
        // Below are three ways of removing document variables from a collection.
        // 1 -  By name:
        variables.remove("City");
        
        Assert.assertFalse(variables.contains("City"));
        
        // 2 -  By index:
        variables.removeAt(1);
        
        Assert.assertFalse(variables.contains("Home address"));
        
        // 3 -  Clear the whole collection at once:
        variables.clear();
        
        Assert.assertEquals(variables.getCount(), 0);
      • removeAt

        public void removeAt(int index)
        Removes a document variable at the specified index.
        Parameters:
        index - The zero based index.

        Example:

        Shows how to work with a document's variable collection.
        Document doc = new Document();
        VariableCollection variables = doc.getVariables();
        
        // Every document has a collection of key/value pair variables, which we can add items to.
        variables.add("Home address", "123 Main St.");
        variables.add("City", "London");
        variables.add("Bedrooms", "3");
        
        Assert.assertEquals(3, variables.getCount());
        
        // We can display the values of variables in the document body using DOCVARIABLE fields.
        DocumentBuilder builder = new DocumentBuilder(doc);
        FieldDocVariable field = (FieldDocVariable) builder.insertField(FieldType.FIELD_DOC_VARIABLE, true);
        field.setVariableName("Home address");
        field.update();
        
        Assert.assertEquals("123 Main St.", field.getResult());
        
        // Assigning values to existing keys will update them.
        variables.add("Home address", "456 Queen St.");
        
        // We will then have to update DOCVARIABLE fields to ensure they display an up-to-date value.
        Assert.assertEquals("123 Main St.", field.getResult());
        
        field.update();
        
        Assert.assertEquals("456 Queen St.", field.getResult());
        
        // Verify that the document variables with a certain name or value exist.
        Assert.assertTrue(variables.contains("City"));
        Assert.assertTrue(IterableUtils.matchesAny(variables, s -> s.getValue() == "London"));
        
        // The collection of variables automatically sorts variables alphabetically by name.
        Assert.assertEquals(0, variables.indexOfKey("Bedrooms"));
        Assert.assertEquals(1, variables.indexOfKey("City"));
        Assert.assertEquals(2, variables.indexOfKey("Home address"));
        
        // Below are three ways of removing document variables from a collection.
        // 1 -  By name:
        variables.remove("City");
        
        Assert.assertFalse(variables.contains("City"));
        
        // 2 -  By index:
        variables.removeAt(1);
        
        Assert.assertFalse(variables.contains("Home address"));
        
        // 3 -  Clear the whole collection at once:
        variables.clear();
        
        Assert.assertEquals(variables.getCount(), 0);