Inspired by spreadsheet applications, KeyValue uses five basic types:

The first two types above are C++ built-in types. The other three are library types.

KeyValue introduces value::Nothing to represent empty data.

To maximize portability, KeyValue uses ::std::string and ::boost::posix_time for strings and times, resp. These types are exported to namespace ::keyvalue where they are called string and ptime resp.

The single-value and multi-type container for basic types is value::Variant.

Values assigned to keys are not always given by a single value::Variant. They may be containers of value::Variants. KeyValue provides three such containers:.

Actually, bridge and core library developers do not need to care neither about the containers above. Indeed, they are used exclusively inside KeyValue and at some point are converted to more standard types. More precisely, a value::Single is converted into an appropriate basic type a T while a value::Vector becomes a ::std::vector<T> and a value::Matrix is transformed into ::std::vector<std::vector<T> > .

Class value::Value is a single-value and multi-type container for value::Single, value::Vector or value::Matrix.

return value::Value(value::Single(value::Variant(x)));

return x;

Initially a key is just a string labeling a value. However, there is more inside a key that just a string can model. Consider the key Dates in the introductory example again. The value associated to it is expected to verify certain conditions:

This kind of information on keys is encapsulated by a certain class. In KeyValue terminology, those classes are called real key and belong to namespace ::keyvalue::key.

The class is key::Key is the base for all real keys. More precisely, real keys derive from key::Traits which derives from key::Key.

Actually, key::Traits is a template class depending on a few template parameters:

Key-value pairs are stored in DataSets. This class implements methods getValue() and also find() to retrieve values assigned to keys. Both methods receive a real key and processes all the information about the expected value encapsulated in it. For instance, suppose that the variable today holds the current date and consider a key BirthDates which corresponds to a vector of increasing dates, supposedly, in the past.

An appropriate real key is then:

key::MonotoneBoundedVector<ptime, key::Increasing, key::Leq>
  births("BrithDates", today);

Therefore, if key BirthDates is in a DataSet named data, the result of

data.getValue(births);

is a ::boost::shared_ptr< const ::std::vector<ptime> > such that the elements of the vector pointed by this pointer are in increasing order and before (less than or equal to) today. The caller does not need to check that.

Since the type returned by getValue() depends on the real key it receives, this method is a template function. The same is true for find().

The difference between getValue() and find() concerns what happens when the key is not resolved. The former method throws an exception to indicate the failure while the latter returns a null pointer. In practice, getValue() is used for compulsory keys and find() for optional keys. A typical use of find() is as follows:

bool foo(false);
if (bool* ptr = data.find(key::Single<bool>("Foo")))
  foo = *ptr;

In the code above foo is false unless key Foo is found, in which case, foo gets the given value.

All builders and calculators derive from protocol class Processor. This class declares three pure virtual methods: getName() and two overloads of getResult(). The former method returns the name under which the processor is recognized by key Processor. The first overload of getResult() takes a DataSet parameter while the second one takes a value::Variant. The difference between them is explained below.

In general, the information that processors need to perform their duties is so rich that must be stored in a DataSet. Nevertheless, in some particular cases, a single value::Variant might be enough. For instance, consider a builder that creates a curve given a few points on it. Normally, this processor needs the set of points together with interpolator and extrapolator methods. In this general case, a DataSet is necessary to hold all this information. However, when the curve is known to be constant, then a single number - the constant - is enough. Rather than creating a DataSet to store a single number, it would be more convenient if the processor could accept just this value (or more generally, a value::Variant). This is, indeed, the case.

Actually, builders and calculators are specializations of template classes Builder and Calculator, resp. They depend on a parameter type named either OutputType (for a builder) or Tag (for a calculator). The primary role of this parameter is to distinguish between different specializations. Additionally, in the case of a builder, it also defines the type of object constructed.

The header files of Builder and Calculator implement the two overloads of Processor::getResult(). The first overload forwards the call to either Builder<ObjectType>::getObject() or Calculator<Tag>::getValue(). These methods must be implemented by bridge developers whenever the template classes are used.

As explained earlier, processing a value::Variant does not always make sense. Therefore, the second overload of Processor::getResult() throws an exception. When this processing does make sense, then template classes XBuilder and XCalculator which extend their base classes Builder and Calculator, resp., must be used. Their header files reimplement the second overload of Processor::getResult() forwarding the call to XBuilder<ObjectType>::getObject() and XCalculator<Tag>::getValue(). As before, these two methods must be implemented by bridge developers whenever the extended template classes are used.

The abstract class Message defines the interface for all types of messages. MessageImpl is a template class which implements Message's pure virtual methods. There are six different specializations of MessageImpl with corresponding typedefs:

They define operator&() to append formated data to themselves. A typical use follows:

Info info(1);  // Create a level-1 Info message.
size_t i;
std::vector<double> x;
//...
info & "x[" & i & "] = " & x[i] & '\n';

Similarly, exception::Exception is an abstract class whose pure virtual methods are implemented in template class exception::ExceptionImpl. This template class has a member which is an instance of MessageImpl. The exact type of this instance is provided as a template parameter of exception::Exception. There are two specializations of exception::Exception with corresponding typedefs:

RuntimeError indicates errors that can be detected only at runtime depending on user data. LogicError indicates errors that should be detected at development time. In other terms, a LogicError means a bug and is thrown when a program invariant fails. It is mainly used through macro KV_ASSERT as in

KV_ASSERT(i < getSize(), "Out of bound!");

To keep compatibility with exception handlers catching standard exceptions, RuntimeError derives from ::std::runtime_error while LogicError derives from ::std::logic_error.

Method exception::ExceptionImpl::operator&() provides the same functionality of MessageImpl::operator&(). Example:

if (price <= 0.0)
  throw RuntimeError() & "Invalid price. Expecting a positive number. Got " &
    price;

Other more specific exception classes are implemented to indicate errors that need special treatment. They all derive from either RuntimeError or LogicError.