[boost] [uuid] Interface

12 Dec 2008

      Here is what I see the interface looking like based on feedback 
from the review so far.  It would, of course, be split into 
different header files.

namespace boost {
namespace uuids {

class uuid : boost::totally_ordered<uuid>
{
// no default constructor
private:
  uuid();

public:
  typedef ... value_type; // will only represent one octet
  typedef ... iterator;
  typedef ... const_iterator;
  typedef ... difference_type;
  typedef ... size_type;

  enum variant_type {
    variant_unknown,
    variant_ncs,
    variant_rfc_4122,
    variant_microsoft
   };

  enum version_type {
    version_unknown,
    version_1 = 1,
    version_2 = 2,
    version_3 = 3,
    version_4 = 4,
    version_5 = 5,
    version_time_based = version_1,
    version_dce_security = version_2,
    version_name_based_md5 = version_3,
    version_random_number_based = version_4
    version_name_based_sha1 = version_4
  };

public:
  // valid expression
  // generator() - result type must be convertible to a uuid
  template <typename Generator>
  explicit uuid(Generator & generator);

  // assert(std::distance(begin, end) >= 16);
  template <typename ByteInputIterator>
  uuid(ByteInputIterator begin, ByteInputIterator end);

  iterator begin();
  iterator end();

  const_iterator begin() const;
  const_iterator end() const;

  bool is_nil() const;

  operator unspecified_bool_type() const; // return !is_nil();

  static size_type size(); // always return 16

  bool operator==(uuid const& rhs) const;

  bool operator<(uuid const& rhs) const;

  variant_type variant() const;
  version_type version() const;
};

void swap(uuid & lhs, uuid & rhs);
std::size_t hash_value(uuid const& u);

// removed get/set_showbraces (does anybody want/use them?)
template <typename ch, typename char_traits>
std::basic_ostream<ch, char_traits>& operator<<(std::basic_ostream<ch,
char_traits>& os, uuid const& u);
template <typename ch, typename char_traits>
std::basic_istream<ch, char_traits>& operator>>(std::basic_istream<ch,
char_traits>& os, uuid& u);

class nil_generator // always generates a nil uuid
{
public:
  typedef uuid result_type;
  uuid operator()();
};
uuid nil(); // easy to use function - should it be included?

template <typename RandomGenerator = boost::mt19937>
class random_generator
{
public:
  typedef uuid result_type;

  random_generator();
  explicit random_generator(RandomGenerator & gen);
  explicit random_generator(RandomGenerator * gen);

  uuid operator()();
};

// I guess technically a transformer since it does not have a zero
argument
// operator()
class name_based_generator // uses sha1 hash
{
public:
  typedef uuid result_type;

  explicit name_based_generator(uuid const& namespace_uuid);

  template <typename ch, typename char_traits, typename allocator>
  uuid operator()(std::basic_string<ch, char_traits, allocator> const&
  name);

  uuid operator()(const char* name); // use std::strlen
  uuid operator()(const wchar_t* name); // use std::wcslen

  template <typename ByteInputIterator>
  uuid operator()(ByteInputIterator begin, ByteInputIterator end);
};

class windows_generator // uses UuidCreate
{
public:
  typedef uuid result_type;

  uuid operator()();
};

class linux_generator // used uuid_generate
{
public:
  typedef uuid result_type;

  uuid operator()();
};

// on windows - will typedef to windows_generator
// on linux - will typedef to linix_generator
typedef ... native_generator;

} //namespace uuids

using uuids::uuid; // so nobody has to type boost::uuids::uuid

} //namespace boost

BOOST_CLASS_IMPLEMENTATION(boost::uuids::uuid,
boost::serialization::primitive_type)

/*
uuid Generator concept

Notation:
X - a type that is a model of uuid generator
x - an object of type X

Associated Types:
Result Type - X::result_type - this must be convertable to
boost::uuids::uuid

Valid Expressions:
x() - return a boost::uuids::uuid
*/

Regards,
Andy Tompkins