All new accumulators must satisfy the Accumulator Concept. Below is a sample class that satisfies the accumulator concept, which simply sums the values of all samples passed into it.

#include <boost/accumulators/framework/accumulator_base.hpp>
#include <boost/accumulators/framework/parameters/sample.hpp>

namespace boost {                           // Putting your accumulators in the
namespace accumulators {                    // impl namespace has some
namespace impl {                            // advantages. See below.

template<typename Sample>
struct sum_accumulator                      // All accumulators should inherit from
  : accumulator_base                        // accumulator_base.
{
    typedef Sample result_type;             // The type returned by result() below.
    
    template<typename Args>                 // The constructor takes an argument pack.
    sum_accumulator(Args const & args)
      : sum(args[sample | Sample()])        // Maybe there is an initial value in the
    {                                       // argument pack. ('sample' is defined in
    }                                       // sample.hpp, included above.)
    
    template<typename Args>                 // The accumulate function is the function
    void operator ()(Args const & args)     // call operator, and it also accepts an
    {                                       // argument pack.
        this->sum += args[sample];
    }
    
    result_type result(dont_care) const     // The result function will also be passed
    {                                       // an argument pack, but we don't use it here,
        return this->sum;                   // so we use "dont_care" as the argument type.
    }
private:
    Sample sum;
};

}}}

Much of the above should be pretty self-explanitory, except for the use of argument packs which may be confusing if you have never used the Boost.Parameter library before. An argument pack is a cluster of values, each of which can be accessed with a key. So args[sample] extracts from the pack the value associated with the sample key. And the cryptic args[sample | Sample()] evaluates to the value associated with the sample key if it exists, or a default-constructed Sample if it doesn't.

The example above demonstrates the most common attributes of an accumulator. There are other optional member functions that have special meaning. In particular:

Accessing Other Accumulators in the Set

Some accumulators depend on other accumulators within the same accumulator set. In those cases, it is necessary to be able to access those other accumulators. To make this possible, the accumulator_set<> passes a reference to itself when invoking the member functions of its contained accumulators. It can be accessed by using the special accumulator key with the argument pack. Consider how we might implement mean_accumulator:

// Mean == (Sum / Count)
template<typename Sample>
struct mean_accumulator : accumulator_base
{
    typedef Sample result_type;
    mean_accumulator(dont_care) {}

    template<typename Args>
    result_type result(Args const &args) const
    {
        return sum(args[accumulator]) / count(args[accumulator]);
    }
};

mean depends on the sum and count accumulators. (We'll see in the next section how to specify these dependencies.) The result of the mean accumulator is merely the result of the sum accumulator divided by the result of the count accumulator. Consider how we write that: sum(args[accumulator]) / count(args[accumulator]). The expression args[accumulator] evaluates to a reference to the accumulator_set<> that contains this mean_accumulator. It also contains the sum and count accumulators, and we can access their results with the extractors defined for those features: sum and count.

All the member functions that accept an argument pack have access to the enclosing accumulator_set<> via the accumulator key, including the constructor. The accumulators within the set are constructed in an order determined by their interdependencies. As a result, it is safe for an accumulator to access one on which it depends during construction.

Infix Notation and the Numeric Operators Sub-Library

Although not necessary, it can be a good idea to put your accumulator implementations in the boost::accumulators::impl namespace. This namespace pulls in any operators defined in the boost::numeric::operators namespace with a using directive. The Numeric Operators Sub-Library defines some additional overloads that will make your accumulators work with all sorts of data types.

Consider mean_accumulator defined above. It divides the sum of the samples by the count. The type of the count is std::size_t. What if the sample type doesn't define division by std::size_t? That's the case for std::complex<>. You might think that if the sample type is std::complex<>, the code would not work, but in fact it does. That's because Numeric Operators Sub-Library defines an overloaded operator/ for std::complex<> and std::size_t. This operator is defined in the boost::numeric::operators namespace and will be found within the boost::accumulators::impl namespace. That's why it's a good idea to put your accumulators there.

Droppable Accumulators

The term "droppable" refers to an accumulator that can be removed from the accumulator_set<>. You can request that an accumulator be made droppable by using the droppable<> class template.

// calculate sum and count, make sum droppable:
accumulator_set< double, features< tag::count, droppable<tag::sum> > > acc;

// add some data
acc(3.0);
acc(2.0);

// drop the sum (sum is 5 here)
acc.drop<tag::sum>();

// add more data
acc(1.0);

// This will display "3" and "5"
std::cout << count(acc) << ' ' << sum(acc);    

Any accumulators that get added to an accumulator set in order to satisfy dependencies on droppable accumulators are themselves droppable. Consider the following accumulator:

// Sum is not droppable. Mean is droppable. Count, brought in to 
// satisfy mean's dependencies, is implicitly droppable, too.
accumulator_set< double, features< tag::sum, droppable<tag::mean> > > acc;

mean depends on sum and count. Since mean is droppable, so too is count. However, we have explictitly requested that sum be not droppable, so it isn't. Had we left tag::sum out of the above declaration, the sum accumulator would have been implicitly droppable.

A droppable accumulator is reference counted, and is only really dropped after all the accumulators that depend on it have been dropped. This can lead to some surprising behavior in some situations.

// calculate sum and mean, make mean droppable. 
accumulator_set< double, features< tag::sum, droppable<tag::mean> > > acc;

// add some data
acc(1.0);
acc(2.0);

// drop the mean. mean's reference count
// drops to 0, so it's really dropped. So
// too, count's reference count drops to 0
// and is really dropped.
acc.drop<tag::mean>();

// add more data. Sum continues to accumulate!
acc(3.0);

// This will display "6 2 3"
std::cout << sum(acc) << ' '
          << count(acc) << ' '    
          << mean(acc);

Note that at the point at which mean is dropped, sum is 3, count is 2, and therefore mean is 1.5. But since sum continues to accumulate even after mean has been dropped, the value of mean continues to change. If you want to remember the value of mean at the point it is dropped, you should save its value into a local variable.

The following rules more precisely specify how droppable and non-droppable accumulators behave within an accumulator set.

And as an optimization:

Once we have implemented an accumulator, we must define a feature for it so that users can specify the feature when declaring an accumulator_set<>. We typically put the features into a nested namespace, so that later we can define an extractor of the same name. All features must satisfy the Feature Concept. Using depends_on<> makes satisfying the concept simple. Below is an example of a feature definition.

namespace boost { namespace accumulators { namespace tag {

struct mean                         // Features should inherit from
  : depends_on< count, sum >        // depends_on<> to specify dependencies
{
    // Define a nested typedef called 'impl' that specifies which
    // accumulator implements this feature. 
    typedef impl::mean_accumulator< mpl::_1 > impl;
};

}}}

The only two things we must do to define the mean feature is to specify the dependencies with depends_on<> and define the nested impl typedef. Even features that have no dependencies should inherit from depends_on<>. The nested impl type must be an MPL Lambda Expression. The result of mpl::apply< impl, sample-type, weight-type >::type must be be the type of the accumulator that implements this feature. The use of MPL placeholders like mpl::_1 make it especially easy to make a template such as mean_accumulator<> an MPL Lambda Expression. Here, mpl::_1 will be replaced with the sample type. Had we used mpl::_2, it would have been replaced with the weight type.

What about accumulator types that are not templates? If you have a foo_accumulator which is a plain struct and not a template, you could turn it into an MPL Lambda Expression using mpl::always<>, like this:

// An MPL lambda expression that always evaluates to
// foo_accumulator:
typedef mpl::always< foo_accumulator > impl;

If you are ever unsure, or if you are not comfortable with MPL lambda expressions, you could always define impl explicitly:

// Same as 'typedef mpl::always< foo_accumulator > impl;'
struct impl
{
    template< typename Sample, typename Weight >
    struct apply
    {
        typedef foo_accumulator type;
    };
};

Here, impl is a binary MPL Metafunction Class, which is a kind of MPL Lambda Expression. The nested apply<> template is part of the metafunction class protocol and tells MPL how to to build the accumulator type given the sample and weight types.

All features must also provide a nested is_weight_accumulator typedef. It must be either mpl::true_ or mpl::false_. depends_on<> provides a default of mpl::false_ for all features that inherit from it, but that can be overridden (or hidden, technically speaking) in the derived type. When the feature represents an accumulation of information about the weights instead of the samples, we can mark this feature as such with typedef mpl::true_ is_weight_accumulator;. The weight accumulators are made external if the weight type is specified using the external<> template.

Now that we have an accumulator and a feature, the only thing lacking is a way to get results from the accumulator set. The Accumulators Framework provides the extractor<> class template to make it simple to define an extractor for your feature. Here's an extractor for the mean feature we defined above:

namespace boost {
namespace accumulators {                // By convention, we put extractors
namespace extract {                     // in the 'extract' namespace

extractor< tag::mean > const mean = {}; // Simply define our extractor with
                                        // our feature tag, like this.
}
using extract::mean;                    // Pull the extractor into the
                                        // enclosing namespace.
}}                                            

Once defined, the mean extractor can be used to extract the result of the tag::mean feature from an accumulator_set<>.

Parameterized features complicate this simple picture. Consider the moment feature, for calculating the N-th moment, where N is specified as a template parameter:

// An accumulator set for calculating the N-th moment, for N == 2 ...
accumulator_set< double, features< tag::moment<2> > > acc;

// ... add some data ...

// Display the 2nd moment ...
std::cout << "2nd moment is " << moment<2>(acc) << std::endl;

In the expression moment<2>(acc), what is moment? It cannot be an object -- the syntax of C++ will not allow it. Clearly, if we want to provide this syntax, we must make moment a function template. Here's what the definition of the moment extractor looks like:

namespace boost {
namespace accumulators {                // By convention, we put extractors
namespace extract {                     // in the 'extract' namespace

template<int N, typename AccumulatorSet>
typename mpl::apply<AccumulatorSet, tag::moment<N> >::type::result_type
moment