// DatasetSplitter.h

#ifndef dset__DatasetSplitter_H
#define dset__DatasetSplitter_H

// A dataset splitter divides a dataset in a collection of
// datasets which span the original dataset. The meaning of
// span depends on the context. A typical example would be to
// divide an event dataset into datasets for which the union
// of their event ranges was that of the original.
//
// A very imporant application of this class is to split jobs
// for distributed processing.
//
// This is an abtract base.

#include <string>
#include <iosfwd>
#include "dataset_base/Dataset.h"

class XmlElement;

namespace dset {

class DatasetSplitter {

public:  // Typedefs.

  // Pointer to a function to create a splitter from an XML element.
  typedef const DatasetSplitter* (*Creator) (const XmlElement&);

public:  // Static methods.

  // Create a splitter from an XML description.
  // Caller is responsible for managing the splitter.
  // The creator is selected using ele.name().
  static const DatasetSplitter* create(const XmlElement& ele);

  // Register a creator.
  // Returns 0 for success.
  // Fails if name is already used for a different creator.
  static int register_creator(std::string name, Creator pfun);

public:  // Virtual methods

  // Destructor.
  virtual ~DatasetSplitter();

  // Split the input dataset and append the new datasets to  a list
  // of datasets.
  // The number of new datasets is returned.
  virtual DatasetList::size_type
  split_and_append(const Dataset& dst, DatasetList& subdsts) const =0;

  // Write to XML.
  virtual const XmlElement* xml() const =0;

  // Output stream.
  virtual std::ostream& ostr(std::ostream& str) const =0;

public:  // Local methods

  // Split a dataset and return the list of new datasets.
  // Uses split_and_append.
  DatasetList split(const Dataset& dst) const;

};

}  // end namespace dset

// Free functions.
std::ostream&
operator<<(std::ostream& lhs, const dset::DatasetSplitter& rhs);

#endif