// UniqueId.h

#ifndef UniqueId_H
#define UniqueId_H

// David Adams
// July 2002
//
// An identifier made up of two 32-bit integers. The uniqueness is
// not inherent but is guaranted if new values are only produced
// by appropriately using UniqueIdGenerator.
//
// The first index is known as the collection index and the second
// is the entry index. Identifiers are ordered by collection and
// then entry.
//
// An identifier is considered invalid if its entry is zero.
//
// A collection index of zero flags a test identifier. One should not
// expect that such objects are unique outside the scope of the
// current process.
// 
// XML representation:
//
// UniqueId
//   collection = 123
//   entry = 1

#include <string>
#include <iosfwd>
#include "dataset_util/Text.h"

class XmlElement;

class UniqueId {

public: // typedef

  // 32-bit int
  typedef unsigned long Index;

private:  // data

  Index m_col;
  Index m_ent;

public:  // static functions

  // XML name.
  static const char* xml_name() { return "UniqueId"; }

  // Return DTD with the given name.
  static Text make_dtd(std::string name);

protected:  // functions

  // Write as XML with the specified XML name.
  const XmlElement* xml_with_name(std::string xname) const;

public:  // functions

  // Default constructor.
  UniqueId();

  // Constructor from collection and entry.
  UniqueId(Index col, Index ent);

  // Constructor from string (see to_string()) with or without padding
  // or from a path (see to_path()).
  explicit UniqueId(std::string sid);

  // Constructor from an XML element.
  explicit UniqueId(const XmlElement& ele);

  // Is this a valid index (nonzero entry)?
  bool is_valid() const;

  // Is this a global index or just unique within this process.
  // ID must be valid and have nonzero collection ID.
  bool is_global() const;

  // Return the collection.
  Index collection() const;

  // Return the entry.
  Index entry() const;

  // Return the next entry in the collection.
  // Returns invalid if the collection is exhausted.
  UniqueId next() const;

  // Convert the ID to a string.
  // pad = true to pad with 0.
  // 0000012345-00000024680 instead of 12345-24680).
  std::string to_string(bool pad =false) const;

  // Convert the ID into a path name with format ij/kl/mn/op/qr/st/uv/wx
  // where ijklmnop is the collection and qrstuvwx is the entry, both in
  // hex. This is useful for creating a directories based on unique ID that
  // will not have too many files.
  std::string to_path() const;

  // Convert the ID to a string 
  // Write as xml.
  const XmlElement* xml() const;

};

// Ordering operator.
bool operator<(const UniqueId& lhs, const UniqueId& rhs);

// Equality.
bool operator==(const UniqueId& lhs, const UniqueId& rhs);

// Inequality.
bool operator!=(const UniqueId& lhs, const UniqueId& rhs);

// Convert index to padded string.
// No pad if pad is '\0'.
std::string index_to_string(UniqueId::Index idx, char pad='\0');

// Output stream.
std::ostream& operator<<(std::ostream& lhs, const UniqueId& rhs);

#endif