com.aspose.words
Class VariableCollection

java.lang.Object
    extended by 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();

// Documents have a variable collection to which name/value pairs can be added
variables.add("Home address", "123 Main St.");
variables.add("City", "London");
variables.add("Bedrooms", "3");

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

// Variables can be referenced and have their values presented in the document by 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.");

// DOCVARIABLE fields also need to be updated in order to show an accurate up to date value
field.update();

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

// The existence of variables can be looked up either by name or value like this
Assert.assertTrue(variables.contains("City"));

// Variables are automatically sorted in alphabetical order
Assert.assertEquals(0, variables.indexOfKey("Bedrooms"));
Assert.assertEquals(1, variables.indexOfKey("City"));
Assert.assertEquals(2, variables.indexOfKey("Home address"));

// Variables can be removed either by name or index, or the entire collection can be cleared at once
variables.remove("City");

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

variables.removeAt(1);

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

variables.clear();

Property Getters/Setters Summary
intgetCount()
           Gets the number of elements contained in the collection.
java.lang.Stringget(int index)
voidset(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.
java.lang.Stringget(java.lang.String name)
voidset(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 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();

// Documents have a variable collection to which name/value pairs can be added
variables.add("Home address", "123 Main St.");
variables.add("City", "London");
variables.add("Bedrooms", "3");

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

// Variables can be referenced and have their values presented in the document by 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.");

// DOCVARIABLE fields also need to be updated in order to show an accurate up to date value
field.update();

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

// The existence of variables can be looked up either by name or value like this
Assert.assertTrue(variables.contains("City"));

// Variables are automatically sorted in alphabetical order
Assert.assertEquals(0, variables.indexOfKey("Bedrooms"));
Assert.assertEquals(1, variables.indexOfKey("City"));
Assert.assertEquals(2, variables.indexOfKey("Home address"));

// Variables can be removed either by name or index, or the entire collection can be cleared at once
variables.remove("City");

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

variables.removeAt(1);

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

variables.clear();

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();

// Documents have a variable collection to which name/value pairs can be added
variables.add("Home address", "123 Main St.");
variables.add("City", "London");
variables.add("Bedrooms", "3");

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

// Variables can be referenced and have their values presented in the document by 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.");

// DOCVARIABLE fields also need to be updated in order to show an accurate up to date value
field.update();

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

// The existence of variables can be looked up either by name or value like this
Assert.assertTrue(variables.contains("City"));

// Variables are automatically sorted in alphabetical order
Assert.assertEquals(0, variables.indexOfKey("Bedrooms"));
Assert.assertEquals(1, variables.indexOfKey("City"));
Assert.assertEquals(2, variables.indexOfKey("Home address"));

// Variables can be removed either by name or index, or the entire collection can be cleared at once
variables.remove("City");

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

variables.removeAt(1);

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

variables.clear();

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();

// Documents have a variable collection to which name/value pairs can be added
variables.add("Home address", "123 Main St.");
variables.add("City", "London");
variables.add("Bedrooms", "3");

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

// Variables can be referenced and have their values presented in the document by 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.");

// DOCVARIABLE fields also need to be updated in order to show an accurate up to date value
field.update();

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

// The existence of variables can be looked up either by name or value like this
Assert.assertTrue(variables.contains("City"));

// Variables are automatically sorted in alphabetical order
Assert.assertEquals(0, variables.indexOfKey("Bedrooms"));
Assert.assertEquals(1, variables.indexOfKey("City"));
Assert.assertEquals(2, variables.indexOfKey("Home address"));

// Variables can be removed either by name or index, or the entire collection can be cleared at once
variables.remove("City");

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

variables.removeAt(1);

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

variables.clear();

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();

// Documents have a variable collection to which name/value pairs can be added
variables.add("Home address", "123 Main St.");
variables.add("City", "London");
variables.add("Bedrooms", "3");

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

// Variables can be referenced and have their values presented in the document by 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.");

// DOCVARIABLE fields also need to be updated in order to show an accurate up to date value
field.update();

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

// The existence of variables can be looked up either by name or value like this
Assert.assertTrue(variables.contains("City"));

// Variables are automatically sorted in alphabetical order
Assert.assertEquals(0, variables.indexOfKey("Bedrooms"));
Assert.assertEquals(1, variables.indexOfKey("City"));
Assert.assertEquals(2, variables.indexOfKey("Home address"));

// Variables can be removed either by name or index, or the entire collection can be cleared at once
variables.remove("City");

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

variables.removeAt(1);

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

variables.clear();

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();

// Documents have a variable collection to which name/value pairs can be added
variables.add("Home address", "123 Main St.");
variables.add("City", "London");
variables.add("Bedrooms", "3");

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

// Variables can be referenced and have their values presented in the document by 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.");

// DOCVARIABLE fields also need to be updated in order to show an accurate up to date value
field.update();

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

// The existence of variables can be looked up either by name or value like this
Assert.assertTrue(variables.contains("City"));

// Variables are automatically sorted in alphabetical order
Assert.assertEquals(0, variables.indexOfKey("Bedrooms"));
Assert.assertEquals(1, variables.indexOfKey("City"));
Assert.assertEquals(2, variables.indexOfKey("Home address"));

// Variables can be removed either by name or index, or the entire collection can be cleared at once
variables.remove("City");

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

variables.removeAt(1);

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

variables.clear();

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();

// Documents have a variable collection to which name/value pairs can be added
variables.add("Home address", "123 Main St.");
variables.add("City", "London");
variables.add("Bedrooms", "3");

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

// Variables can be referenced and have their values presented in the document by 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.");

// DOCVARIABLE fields also need to be updated in order to show an accurate up to date value
field.update();

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

// The existence of variables can be looked up either by name or value like this
Assert.assertTrue(variables.contains("City"));

// Variables are automatically sorted in alphabetical order
Assert.assertEquals(0, variables.indexOfKey("Bedrooms"));
Assert.assertEquals(1, variables.indexOfKey("City"));
Assert.assertEquals(2, variables.indexOfKey("Home address"));

// Variables can be removed either by name or index, or the entire collection can be cleared at once
variables.remove("City");

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

variables.removeAt(1);

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

variables.clear();

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();

// Documents have a variable collection to which name/value pairs can be added
variables.add("Home address", "123 Main St.");
variables.add("City", "London");
variables.add("Bedrooms", "3");

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

// Variables can be referenced and have their values presented in the document by 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.");

// DOCVARIABLE fields also need to be updated in order to show an accurate up to date value
field.update();

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

// The existence of variables can be looked up either by name or value like this
Assert.assertTrue(variables.contains("City"));

// Variables are automatically sorted in alphabetical order
Assert.assertEquals(0, variables.indexOfKey("Bedrooms"));
Assert.assertEquals(1, variables.indexOfKey("City"));
Assert.assertEquals(2, variables.indexOfKey("Home address"));

// Variables can be removed either by name or index, or the entire collection can be cleared at once
variables.remove("City");

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

variables.removeAt(1);

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

variables.clear();

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();

// Documents have a variable collection to which name/value pairs can be added
variables.add("Home address", "123 Main St.");
variables.add("City", "London");
variables.add("Bedrooms", "3");

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

// Variables can be referenced and have their values presented in the document by 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.");

// DOCVARIABLE fields also need to be updated in order to show an accurate up to date value
field.update();

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

// The existence of variables can be looked up either by name or value like this
Assert.assertTrue(variables.contains("City"));

// Variables are automatically sorted in alphabetical order
Assert.assertEquals(0, variables.indexOfKey("Bedrooms"));
Assert.assertEquals(1, variables.indexOfKey("City"));
Assert.assertEquals(2, variables.indexOfKey("Home address"));

// Variables can be removed either by name or index, or the entire collection can be cleared at once
variables.remove("City");

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

variables.removeAt(1);

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

variables.clear();

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