Element API¶

This page documents the API convention for accessing parameters of ADM element classes. Element classes like AudioBlockFormatObjects contain many parameters, each with different types (thanks to using named types). These parameters can be accessed through a common set of templated and overloaded methods defined on elements. Compared to standard accessors methods, this makes it easy to write templates which handle parameters generically.

Note

The classes listed on this page do not actually exist, they just serve to show the API on element classes themselves.

The set of methods which may be defined for each parameter of type Parameter are shown below:

class adm::Element¶

template<typename Parameter> Parameter get()¶: Get the value of a parameter. If the parameter has no default value and has not been set then an error is raised.

void set(Parameter parameter)¶: Set the value of a parameter.

template<typename Parameter> bool has<Parameter>()¶: Returns true if the ADM parameter is set or has a default value, and therefore get() will not raise an error.

template<typename Parameter> void unset<Parameter>()¶: Removes the ADM parameter if it is optional or resets it to the default value if there is one.

template<typename Parameter> bool isDefault<Parameter>()¶: Returns true if the parameter has a default and has not been set; this is useful to see if the default value was specified explicitly in the ADM XML (in which case this would return false), and is used to control whether default values are written out in XML.

bool add(Parameter parameter)¶: For parameters with multiple values, add a new value, ensuring uniqueness. Returns true if the parameter was added, or false if it already had a parameter with this value.

void remove(Parameter parameter)¶: For parameters with multiple values, remove one.

These methods are implemented in some common patterns for parameters which behave in different ways:

template<typename T> class adm::RequiredParameter¶

Required parameters must be specified in the ADM XML.

template<> T get<T>()¶: see Element::get()

void set(T)¶: see Element::set()

template<> bool has<T>()¶: always returns true

template<typename T> class adm::OptionalParameter¶

Optional parameters may or may not be specified.

template<> T get<T>()¶: see Element::get()

void set(T)¶: see Element::set()

template<> bool has<T>()¶: see Element::has()

template<> void unset<T>()¶: see Element::unset()

template<> bool isDefault<T>()¶: always returns false

template<typename T> class adm::DefaultParameter¶

Default parameters may or may not be specified, but have a default defined in the ADM.

template<> T get<T>()¶: see Element::get()

void set(T)¶: see Element::set()

template<> bool has<T>()¶: see Element::has()

template<> void unset<T>()¶: see Element::unset()

template<> bool isDefault<T>()¶: see Element::isDefault()

template<typename VectorT> class adm::VectorParameter¶

Vector parameters have multiple values, and some defined concept of equality.

get and set methods get and set a std::vector<T> holding the parameters, while add and remove add and remove individual values.

using T = VectorT::value_type¶

template<> VectorT get<VectorT>()¶: get a vector of parameters.

void set(VectorT)¶: Set a vector of parameters.

template<> bool has<VectorT>()¶: Have any parameters been set?

template<> void unset<VectorT>()¶: Clear the list of parameters.

template<> bool isDefault<VectorT>()¶: Always returns false.

bool add(T)¶: Add a new value, ensuring uniqueness. Returns true if the parameter was added, or false if it already had a parameter with this value.

void remove(T)¶: Remove a parameter from the list.

template<typename ParameterT> class adm::VariantParameter¶

Variant parameters have a single value, but that value can be one of two or more types, stored in a boost::variant.

This is used for types where there is no obvious conversion between the possible types. For types that just have multiple representations of the same data, a wrapper class is used instead.

Access to the variant type follows one of the above schemes (adm::RequiredParameter, adm::OptionalParameter etc.). In addition, methods are provided for each T in the variant to access the individual types:

template<> T get<T>()¶: Get T; if the parameter is not set, or is not of the specified type, an error is raised.

void set(T)¶: Set the parameter.

template<> bool has<T>()¶: Is the parameter set (or is it defaulted) and is it of the specified type?

template<> void unset<T>()¶: Unset the parameter if it is set and of the specified type. If it’s a different type this does nothing – to unset any type, use the variant type instead.

template<> bool isDefault<T>()¶: Returns true if the variant has the default value, and the default is of the correct type.