Lexicon.h

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// Copyright Network Geographics 2014
 
#pragma once
 
#include <string_view>
#include <initializer_list>
#include <tuple>
#include <functional>
#include <array>
#include <variant>
#include <ctype.h>
 
#include "swoc/swoc_version.h"
#include "swoc/IntrusiveHashMap.h"
#include "swoc/MemArena.h"
#include "swoc/bwf_base.h"
#include "swoc/ext/HashFNV.h"
 
namespace swoc { inline namespace SWOC_VERSION_NS {
namespace detail {
template <typename... Args>
std::string
what(std::string_view const &fmt, Args &&...args) {
  std::string zret;
  return swoc::bwprint_v(zret, fmt, std::forward_as_tuple(args...));
}
 
// Exported because inner classes in template classes cannot be used in partial specialization
// which is required for tuple support. This should be removed next time there is a API changing
// release because tuple access is being deprecated.
template <typename E> struct lexicon_pair_type {
  E _value;
  TextView _name;

  lexicon_pair_type(E value, TextView name) : _value(value), _name(name) {}
};
 
} // namespace detail

template <typename E>
size_t
Lexicon_Hash(E e) {
  static constexpr std::hash<E> hasher;
  return hasher(e);
}

template <typename E> class Lexicon {
  using self_type = Lexicon; 
 
protected:
  struct Item;
 
public:
  using Pair = detail::lexicon_pair_type<E>;
 
  // Deprecated - use the member names now.
  static constexpr auto VALUE_IDX = 0;
  static constexpr auto NAME_IDX = 1;

  using UnknownValueHandler = std::function<TextView(E)>;

  using UnknownNameHandler = std::function<E(TextView)>;

  using Default = std::variant<std::monostate, E, TextView, UnknownNameHandler, UnknownValueHandler>;

  struct Definition {
    const E &value;                               
    std::initializer_list<TextView> const &names; 
  };

  Lexicon();
 
  using with       = std::initializer_list<Pair> const &;
  using with_multi = std::initializer_list<Definition> const &;

  explicit Lexicon(with_multi items, Default handler_1 = Default{}, Default handler_2 = Default{});

  explicit Lexicon(with items, Default handler_1 = Default{}, Default handler_2 = Default{});

  explicit Lexicon(Default handler_1, Default handler_2 = Default{});
 
  Lexicon(self_type &&that) = default;

  TextView operator[](E const &value) const;

  E operator[](TextView const &name) const;

  template <typename... Args> self_type &define(E value, Args &&...names);
 
  // These are really for consistency with constructors, they're not expected to be commonly used.
  self_type &define(E value, const std::initializer_list<TextView> &names);

  self_type &define(const Pair &pair);

  self_type &define(const Definition &init);

  self_type &set_default(Default const &handler);

  size_t count() const;
 
protected:
  class base_iterator {
    using self_type = base_iterator;
 
  public:
    using value_type        = const Pair;                      
    using pointer           = value_type *;                    
    using reference         = value_type &;                    
    using difference_type   = ptrdiff_t;                       
    using iterator_category = std::bidirectional_iterator_tag; 
    base_iterator() = default;
    reference operator*() const;
    pointer operator->() const;
    bool operator==(self_type const &that) const;
    bool operator!=(self_type const &that) const;
 
  protected:
    explicit base_iterator(Item const *item) : _item(item) {}
 
    const Item *_item{nullptr}; 
  };
 
public:
  class value_iterator : public base_iterator {
    using super_type = base_iterator;
    using self_type  = value_iterator;
 
  public:
    using value_type = typename super_type::value_type;
    using pointer    = typename super_type::pointer;
    using reference  = typename super_type::reference;

    value_iterator() = default;

    value_iterator(self_type const &that) = default;

    value_iterator(self_type &&that) = default;

    self_type &operator=(self_type const &that) = default;

    self_type &operator++();

    self_type operator++(int);

    self_type &operator--();

    self_type operator--(int);
 
  protected:
    value_iterator(const Item *item) : super_type(item){}; 
 
    friend Lexicon;
  };
 
  class name_iterator : public base_iterator {
  private:
    using self_type  = name_iterator;
    using super_type = base_iterator;
 
  public:
    name_iterator() = default;

    name_iterator(self_type const &that) = default;

    name_iterator(self_type &&that) = default;

    self_type &operator=(self_type const &that) = default;

    self_type &operator++();

    self_type operator++(int);

    self_type &operator--();

    self_type operator--(int);
 
  protected:
    name_iterator(const Item *item) : super_type(item){}; 
 
    friend Lexicon;
  };

  using const_iterator = value_iterator;
  using iterator = const_iterator;

  const_iterator begin() const;

  const_iterator end() const;

  name_iterator
  begin_names() const {
    return {_by_name.begin()};
  }

  name_iterator
  end_names() const {
    return {_by_name.end()};
  }

  // Helper struct to return to enable container iteration for names.
  struct ByNameHelper {
    self_type const &_lexicon;
    ByNameHelper(self_type const &self) : _lexicon(self) {}
    name_iterator
    begin() const {
      return _lexicon.begin_names();
    }
    name_iterator
    end() const {
      return _lexicon.end_names();
    }
  };

  ByNameHelper
  by_names() const {
    return {*this};
  }
 
protected:
  using NameDefault = std::variant<std::monostate, std::string_view, UnknownValueHandler>;
  using ValueDefault = std::variant<std::monostate, E, UnknownNameHandler>;

  struct NameDefaultVisitor {
    E _value; 

    std::string_view
    operator()(std::monostate const &) const {
      throw std::domain_error("Lexicon: invalid enumeration value");
    }

    std::string_view
    operator()(TextView const &name) const {
      return name;
    }

    std::string_view
    operator()(UnknownValueHandler const &handler) const {
      return handler(_value);
    }
  };

  struct ValueDefaultVisitor {
    std::string_view _name; 

    E
    operator()(std::monostate const &) const {
      throw std::domain_error(detail::what("Lexicon: Unknown name \"{}\"", _name).data());
    }

    E
    operator()(E const &value) const {
      return value;
    }

    E
    operator()(UnknownNameHandler const &handler) const {
      return handler(_name);
    }
  };

  struct Item {
    Item(E value, TextView name);
 
    Pair _payload; 

    // Intrusive list linkage support.
    struct NameLinkage {
      Item *_next{nullptr};
      Item *_prev{nullptr};
 
      static Item *&next_ptr(Item *);
      static Item *&prev_ptr(Item *);
      static std::string_view key_of(Item *);
      static uint32_t hash_of(std::string_view s);
      static bool equal(std::string_view const &lhs, std::string_view const &rhs);
    } _name_link;
 
    // Intrusive linkage for value lookup.
    struct ValueLinkage {
      Item *_next{nullptr};
      Item *_prev{nullptr};
 
      static Item *&next_ptr(Item *);
      static Item *&prev_ptr(Item *);
      static E key_of(Item *);
      static size_t hash_of(E);
      static bool equal(E lhs, E rhs);
    } _value_link;
  };

  TextView localize(TextView const &name);

  MemArena _arena{1024};
  IntrusiveHashMap<typename Item::NameLinkage> _by_name;
  IntrusiveHashMap<typename Item::ValueLinkage> _by_value;
  NameDefault _name_default;   
  ValueDefault _value_default; 
};
 
// ==============
// Implementation
 
// ----
// Item
 
template <typename E> Lexicon<E>::Item::Item(E value, TextView name) : _payload{value, name} {}

template <typename E>
auto
Lexicon<E>::Item::NameLinkage::next_ptr(Item *item) -> Item *& {
  return item->_name_link._next;
}
 
template <typename E>
auto
Lexicon<E>::Item::NameLinkage::prev_ptr(Item *item) -> Item *& {
  return item->_name_link._prev;
}
 
template <typename E>
auto
Lexicon<E>::Item::ValueLinkage::next_ptr(Item *item) -> Item *& {
  return item->_value_link._next;
}
 
template <typename E>
auto
Lexicon<E>::Item::ValueLinkage::prev_ptr(Item *item) -> Item *& {
  return item->_value_link._prev;
}
 
template <typename E>
std::string_view
Lexicon<E>::Item::NameLinkage::key_of(Item *item) {
  return item->_payload._name;
}
 
template <typename E>
E
Lexicon<E>::Item::ValueLinkage::key_of(Item *item) {
  return item->_payload._value;
}
 
template <typename E>
uint32_t
Lexicon<E>::Item::NameLinkage::hash_of(std::string_view s) {
  return Hash32FNV1a().hash_immediate(transform_view_of(&::toupper, s));
}
 
template <typename E>
size_t
Lexicon<E>::Item::ValueLinkage::hash_of(E value) {
  return Lexicon_Hash<E>(value);
}
 
template <typename E>
bool
Lexicon<E>::Item::NameLinkage::equal(std::string_view const &lhs, std::string_view const &rhs) {
  return 0 == strcasecmp(lhs, rhs);
}
 
template <typename E>
bool
Lexicon<E>::Item::ValueLinkage::equal(E lhs, E rhs) {
  return lhs == rhs;
}
 
// -------
// Lexicon
 
template <typename E> Lexicon<E>::Lexicon() {}
 
template <typename E> Lexicon<E>::Lexicon(with_multi items, Default handler_1, Default handler_2) {
  for (auto const &item : items) {
    this->define(item.value, item.names);
  }
 
  for (auto &&h : {handler_1, handler_2}) {
    this->set_default(h);
  }
}
 
template <typename E> Lexicon<E>::Lexicon(with items, Default handler_1, Default handler_2) {
  for (auto const &item : items) {
    this->define(item);
  }
 
  for (auto &&h : {handler_1, handler_2}) {
    this->set_default(h);
  }
}
 
template <typename E> Lexicon<E>::Lexicon(Default handler_1, Default handler_2) {
  for (auto &&h : {handler_1, handler_2}) {
    this->set_default(h);
  }
}
 
template <typename E>
TextView
Lexicon<E>::localize(TextView const &name) {
  auto span = _arena.alloc_span<char>(name.size());
  memcpy(span, name);
  return {span.data(), span.size()};
}
 
template <typename E>
TextView
Lexicon<E>::operator[](E const &value) const {
  if (auto spot = _by_value.find(value); spot != _by_value.end()) {
    return spot->_payload._name;
  }
  return std::visit(NameDefaultVisitor{value}, _name_default);
}
 
template <typename E>
E
Lexicon<E>::operator[](TextView const &name) const {
  if (auto spot = _by_name.find(name); spot != _by_name.end()) {
    return spot->_payload._value;
  }
  return std::visit(ValueDefaultVisitor{name}, _value_default);
}
 
template <typename E>
auto
Lexicon<E>::define(E value, const std::initializer_list<TextView> &names) -> self_type & {
  if (names.size() < 1) {
    throw std::invalid_argument("A defined value must have at least a primary name");
  }
  for (auto const &name : names) {
    if (_by_name.find(name) != _by_name.end()) {
      throw std::invalid_argument(detail::what("Duplicate name '{}' in Lexicon", name));
    }
    auto i = _arena.make<Item>(value, this->localize(name));
    _by_name.insert(i);
    // Only put primary names in the value table.
    if (_by_value.find(value) == _by_value.end()) {
      _by_value.insert(i);
    }
  }
  return *this;
}
 
template <typename E>
template <typename... Args>
auto
Lexicon<E>::define(E value, Args &&...names) -> self_type & {
  static_assert(sizeof...(Args) > 0, "A defined value must have at least a primary name");
  return this->define(value, {std::forward<Args>(names)...});
}
 
template <typename E>
auto
Lexicon<E>::define(const Pair &pair) -> self_type & {
  return this->define(pair._value, pair._name);
}
 
template <typename E>
auto
Lexicon<E>::define(const Definition &init) -> self_type & {
  return this->define(init.value, init.names);
}
 
template <typename E>
auto
Lexicon<E>::set_default(Default const &handler) -> self_type & {
  switch (handler.index()) {
  case 0:
    break;
  case 1:
    _value_default = std::get<1>(handler);
    break;
  case 3:
    _value_default = std::get<3>(handler);
    break;
  case 2:
    _name_default = std::get<2>(handler);
    break;
  case 4:
    _name_default = std::get<4>(handler);
    break;
  }
  return *this;
}
 
template <typename E>
size_t
Lexicon<E>::count() const {
  return _by_value.count();
}
 
template <typename E>
auto
Lexicon<E>::begin() const -> const_iterator {
  return const_iterator{static_cast<const Item *>(_by_value.begin())};
}
 
template <typename E>
auto
Lexicon<E>::end() const -> const_iterator {
  return {};
}
 
// Iterators
 
template <typename E>
auto
Lexicon<E>::base_iterator::operator*() const -> reference {
  return _item->_payload;
}
 
template <typename E>
auto
Lexicon<E>::base_iterator::operator->() const -> pointer {
  return &(_item->_payload);
}
 
template <typename E>
bool
Lexicon<E>::base_iterator::operator==(self_type const &that) const {
  return _item == that._item;
}
 
template <typename E>
bool
Lexicon<E>::base_iterator::operator!=(self_type const &that) const {
  return _item != that._item;
}
 
template <typename E>
auto
Lexicon<E>::value_iterator::operator++() -> self_type & {
  super_type::_item = super_type::_item->_value_link._next;
  return *this;
}
 
template <typename E>
auto
Lexicon<E>::value_iterator::operator++(int) -> self_type {
  self_type tmp{*this};
  ++*this;
  return tmp;
}
 
template <typename E>
auto
Lexicon<E>::value_iterator::operator--() -> self_type & {
  super_type::_item = super_type::_item->_value_link->_prev;
  return *this;
}
 
template <typename E>
auto
Lexicon<E>::value_iterator::operator--(int) -> self_type {
  self_type tmp;
  ++*this;
  return tmp;
}
 
template <typename E>
auto
Lexicon<E>::name_iterator::operator++() -> self_type & {
  super_type::_item = super_type::_item->_name_link._next;
  return *this;
}
 
template <typename E>
auto
Lexicon<E>::name_iterator::operator++(int) -> self_type {
  self_type tmp{*this};
  ++*this;
  return tmp;
}
 
template <typename E>
auto
Lexicon<E>::name_iterator::operator--() -> self_type & {
  super_type::_item = super_type::_item->_name_link->_prev;
  return *this;
}
 
template <typename E>
auto
Lexicon<E>::name_iterator::operator--(int) -> self_type {
  self_type tmp;
  ++*this;
  return tmp;
}
 
template <typename E>
BufferWriter &
bwformat(BufferWriter &w, bwf::Spec const &spec, Lexicon<E> const &lex) {
  bool sep_p = false;
  if (spec._type == 's' || spec._type == 'S') {
    for (auto &&[value, name] : lex) {
      if (sep_p) {
        w.write(',');
      }
      bwformat(w, spec, name);
      sep_p = true;
    }
  } else if (spec.has_numeric_type()) {
    for (auto &&[value, name] : lex) {
      if (sep_p) {
        w.write(',');
      }
      bwformat(w, spec, unsigned(value));
      sep_p = true;
    }
  } else {
    for (auto &&[value, name] : lex) {
      if (sep_p) {
        w.write(',');
      }
      w.print("[{},{}]", name, unsigned(value));
      sep_p = true;
    }
  }
  return w;
}
 
}} // namespace swoc::SWOC_VERSION_NS
 
namespace std {
 
template <size_t IDX, typename E> class tuple_element<IDX, swoc::detail::lexicon_pair_type<E>> {
  static_assert("swoc::Lexicon::Pair tuple index out of range");
};
 
template <typename E> class tuple_element<0, swoc::detail::lexicon_pair_type<E>> {
public:
  using type = E;
};
 
template <typename E> class tuple_element<1, swoc::detail::lexicon_pair_type<E>> {
public:
  using type = swoc::TextView;
};
 
template <size_t IDX, typename E>
auto
get(swoc::detail::lexicon_pair_type<E> const &p) -> typename std::tuple_element<IDX, swoc::detail::lexicon_pair_type<E>>::type {
  if constexpr (IDX == 0) {
    return p._value;
  } else if constexpr (IDX == 1) {
    return p._name;
  }
}
 
} // namespace std