BitMask.h

Go to the documentation of this file.

#ifndef LARDATAOBJ_UTILITIES_BITMASK_H
#define LARDATAOBJ_UTILITIES_BITMASK_H

// C/C++ standard library
#include <exception>
#include <ostream>
#include <string>

namespace util {

  namespace flags {

    using Index_t = unsigned int;

    namespace details {

      template <unsigned int NBits>
      struct SmallestUIntType;

      template <unsigned int NBits>
      using smallestUInt_t = typename SmallestUIntType<NBits>::type;

      template <typename Storage>
      constexpr unsigned int computePages(unsigned int bits);

      template <typename Storage>
      constexpr Storage makeBits(Index_t index)
      {
        return Storage(1) << index;
      }

    } // namespace details

    //--------------------------------------------------------------------------
    template <typename Storage>
    struct Flag_t {
      using Storage_t = Storage;
      using This_t = Flag_t<Storage>; 

      Storage_t bits; 

      constexpr Flag_t(Index_t flagIndex) : bits(details::makeBits<Storage_t>(flagIndex)) {}

      constexpr Index_t index() const;

      constexpr Flag_t copy() const { return *this; }


      constexpr bool operator==(This_t other) const { return bits == other.bits; }
      constexpr bool operator!=(This_t other) const { return bits != other.bits; }
      constexpr bool operator<(This_t other) const { return bits < other.bits; }
      constexpr bool operator>(This_t other) const { return bits > other.bits; }
      constexpr bool operator<=(This_t other) const { return bits <= other.bits; }
      constexpr bool operator>=(This_t other) const { return bits >= other.bits; }


    }; // Flag_t

    template <typename Storage>
    constexpr bool operator==(Index_t left, Flag_t<Storage> right)
    {
      return left == right.index();
    }
    template <typename Storage>
    constexpr bool operator==(Flag_t<Storage> left, Index_t right)
    {
      return left.index() == right;
    }

    template <typename Storage>
    constexpr bool operator!=(Index_t left, Flag_t<Storage> right)
    {
      return left != right.index();
    }
    template <typename Storage>
    constexpr bool operator!=(Flag_t<Storage> left, Index_t right)
    {
      return left.index() != right;
    }

    template <typename Storage>
    constexpr bool operator<(Index_t left, Flag_t<Storage> right)
    {
      return left < right.index();
    }
    template <typename Storage>
    constexpr bool operator<(Flag_t<Storage> left, Index_t right)
    {
      return left.index() < right;
    }

    template <typename Storage>
    constexpr bool operator>(Index_t left, Flag_t<Storage> right)
    {
      return left > right.index();
    }
    template <typename Storage>
    constexpr bool operator>(Flag_t<Storage> left, Index_t right)
    {
      return left.index() > right;
    }

    template <typename Storage>
    constexpr bool operator<=(Index_t left, Flag_t<Storage> right)
    {
      return left <= right.index();
    }
    template <typename Storage>
    constexpr bool operator<=(Flag_t<Storage> left, Index_t right)
    {
      return left.index() <= right;
    }

    template <typename Storage>
    constexpr bool operator>=(Index_t left, Flag_t<Storage> right)
    {
      return left >= right.index();
    }
    template <typename Storage>
    constexpr bool operator>=(Flag_t<Storage> left, Index_t right)
    {
      return left.index() >= right;
    }


    template <typename Storage>
    std::ostream& operator<<(std::ostream& out, Flag_t<Storage> flag)
    {
      out << '[' << flag.index() << ']';
      return out;
    }

    template <typename Storage>
    std::string to_string(Flag_t<Storage> const flag)
    {
      return std::to_string(flag.index());
    }

    //--------------------------------------------------------------------------
    template <typename Storage>
    struct Bits_t {
      using Storage_t = Storage;
      using This_t = Bits_t<Storage>; 

      using Flag_t = util::flags::Flag_t<Storage_t>;

      Storage_t data = {0}; 

      constexpr Bits_t() = default;

      constexpr Bits_t(Flag_t flag) : data(flag.bits) {}

      explicit constexpr Bits_t(Storage_t bits) : data(bits) {}


      constexpr bool empty() const { return data == Storage_t(0); }

      constexpr bool all(This_t bits) const;

      constexpr bool any(This_t bits) const;

      constexpr bool none(This_t bits) const;

      constexpr bool only(This_t bits) const;



      void set(This_t bits);

      void unset(This_t bits);

      void keepOnly(This_t bits);

      void clear() { data = 0; }



      constexpr This_t select(This_t bits) const;

      constexpr This_t exclude(This_t bits) const;

      constexpr This_t combine(This_t bits) const;

      constexpr This_t invert() const;



      constexpr bool operator==(This_t other) const { return data == other.data; }
      constexpr bool operator!=(This_t other) const { return data != other.data; }
      constexpr bool operator<(This_t other) const { return data < other.data; }
      constexpr bool operator>(This_t other) const { return data > other.data; }
      constexpr bool operator<=(This_t other) const { return data <= other.data; }
      constexpr bool operator>=(This_t other) const { return data >= other.data; }


      explicit constexpr operator bool() const { return bool(data); }

      constexpr bool operator!() const { return !data; }

      static void setBits(Storage_t& base, Storage_t bits) { base |= bits; }

      static void onlyBits(Storage_t& base, Storage_t bits) { base &= bits; }

      static void unsetBits(Storage_t& base, Storage_t bits) { onlyBits(base, ~bits); }

    }; // Bits_t


    template <typename Storage>
    constexpr Bits_t<Storage> operator|(Bits_t<Storage> left, Bits_t<Storage> right);

    template <typename Storage>
    constexpr Bits_t<Storage> operator|(Bits_t<Storage> left,
                                        typename Bits_t<Storage>::Flag_t right);

    template <typename Storage>
    constexpr Bits_t<Storage> operator|(typename Bits_t<Storage>::Flag_t left,
                                        Bits_t<Storage> right);

    template <typename Storage>
    constexpr Bits_t<Storage> operator|(Flag_t<Storage> left, Flag_t<Storage> right);

    template <typename Storage>
    constexpr Bits_t<Storage> operator+(Bits_t<Storage> left, Bits_t<Storage> right);

    template <typename Storage>
    constexpr Bits_t<Storage> operator+(Bits_t<Storage> left,
                                        typename Bits_t<Storage>::Flag_t right);

    template <typename Storage>
    constexpr Bits_t<Storage> operator+(typename Bits_t<Storage>::Flag_t left,
                                        Bits_t<Storage> right);

    template <typename Storage>
    constexpr Bits_t<Storage> operator+(Flag_t<Storage> left, Flag_t<Storage> right);


    //--------------------------------------------------------------------------
    namespace errors {


      struct Exception : public std::exception {
        explicit Exception(std::string msg = "Flag error") : message(msg) {}
        virtual const char* what() const noexcept override { return message.c_str(); }
        std::string message;
      }; // Exception

      struct FlagNotDefined : public Exception {
        explicit FlagNotDefined(std::string msg = "Flag undefined-flag error") : Exception(msg) {}
      }; // FlagNotDefined

      struct OutOfRange : public Exception {
        explicit OutOfRange(std::string msg = "Flag out-of-range error") : Exception(msg) {}
      }; // OutOfRange


    } // namespace errors

    struct BitMaskFromValuesTag {}; 

    constexpr BitMaskFromValuesTag maskFromValues{};

    template <typename Storage>
    class BitMask {

      using Storage_t = Storage;

    public:
      using Mask_t = BitMask<Storage>; 

      using FlagIndex_t = util::flags::Index_t; 

      using Bits_t = util::flags::Bits_t<Storage_t>; 

      using Flag_t = typename Bits_t::Flag_t;


      using Exception = errors::Exception;

      using OutOfRangeError = errors::OutOfRange;

      using FlagNotDefinedError = errors::FlagNotDefined;


      static constexpr auto fromValues = maskFromValues;

      // -- BEGIN Constructors from values -------------------------------------

      explicit constexpr BitMask() = default;

      constexpr BitMask(BitMaskFromValuesTag, Storage_t defined);

      constexpr BitMask(BitMaskFromValuesTag, Storage_t defined, Storage_t values);

      constexpr BitMask(BitMaskFromValuesTag, Bits_t values);

      constexpr BitMask(BitMaskFromValuesTag, Bits_t defined, Bits_t values);

      // -- END Constructors from values ---------------------------------------

      // -- BEGIN Constructors combining flags ---------------------------------

      template <typename... Others>
      constexpr BitMask(Flag_t first, Others... others) : BitMask(create(first, others...))
      {}

      template <typename... Others>
      constexpr BitMask(Bits_t first, Others... others) : BitMask(create(first, others...))
      {}

      // NOTE: if the first argument passed as reference prevent constexpr,
      //       two separate constructors will be needed;
      //       also note that this works as copy constructor as well
      template <typename Second, typename... Others>
      constexpr BitMask(Mask_t first, Second second, Others... others)
        : BitMask(create(first, second, others...))
      {}

      // -- END Constructors combining flags -----------------------------------

      // -- BEGIN Access to flags ----------------------------------------------

      constexpr bool isDefined(Flag_t flag) const;

      constexpr bool isDefined(Bits_t bits) const;

      constexpr bool isUndefined(Flag_t flag) const;

      constexpr bool isUndefined(Bits_t bits) const;

      constexpr bool get(Flag_t flag) const;

      constexpr bool isSet(Flag_t flag) const;

      constexpr bool isUnset(Flag_t flag) const;

      constexpr bool all(Bits_t bits) const;

      constexpr bool any(Bits_t bits) const;

      constexpr bool none(Bits_t bits) const;

      constexpr bool anySet(Mask_t const& mask) const;

      constexpr bool noneSet(Mask_t const& mask) const;

      constexpr bool match(Mask_t const& mask) const;

      // -- END Access to flags ------------------------------------------------

      // -- BEGIN Setting flags ------------------------------------------------

      template <typename Flag, typename... OtherFlags>
      void set(Flag first, OtherFlags... others)
      {
        setImpl(first, others...);
      }

      template <typename BeginIter, typename EndIter>
      void rangeSet(BeginIter begin, EndIter end);

      template <typename Flag, typename... OtherFlags>
      void unset(Flag first, OtherFlags... others)
      {
        unsetImpl(first, others...);
      }

      template <typename BeginIter, typename EndIter>
      void rangeUnset(BeginIter begin, EndIter end);

      template <typename Flag, typename... OtherFlags>
      void remove(Flag first, OtherFlags... others)
      {
        undefineImpl(first, others...);
      }

      void clear()
      {
        presence.clear();
        values.clear();
      }

      // -- END Setting flags --------------------------------------------------

      // -- BEGIN Number of flags ----------------------------------------------

      static constexpr size_t capacity();

      // -- END Number of flags ------------------------------------------------

      constexpr bool operator==(Mask_t const& other) const
      {
        return (values == other.values) && (presence == other.presence);
      }

      constexpr bool operator!=(Mask_t const& other) const
      {
        return (values != other.values) || (presence != other.presence);
      }

      template <typename Stream>
      void dump(Stream&& out, unsigned int nBits) const;

      template <typename Stream>
      void dump(Stream&& out) const
      {
        dump(std::forward<Stream>(out), capacity());
      }

      // -- BEGIN Static mask manipulation -------------------------------------

      template <typename... Args>
      static constexpr Mask_t create(Args... args);

      static constexpr Mask_t mergeIntoMask(Mask_t baseMask, Mask_t mask);

      static constexpr Mask_t mergeIntoMask(Mask_t baseMask, Bits_t bits);

      static constexpr Mask_t mergeIntoMask(Mask_t baseMask, Flag_t flag);

      static constexpr Mask_t combineWithMask(Mask_t A, Mask_t B);

      static constexpr Mask_t combineWithMask(Mask_t baseMask, Bits_t bits);

      static constexpr Mask_t combineWithMask(Mask_t baseMask, Flag_t flag);

      static constexpr Mask_t intersectWithMask(Mask_t A, Mask_t B);

      static constexpr Mask_t intersectWithMask(Mask_t baseMask, Bits_t bits);

      static constexpr Mask_t intersectWithMask(Mask_t baseMask, Flag_t flag);

      static constexpr Mask_t unsetMask(Mask_t baseMask, Mask_t mask);

      static constexpr Mask_t unsetMask(Mask_t baseMask, Bits_t bits);

      static constexpr Mask_t unsetMask(Mask_t baseMask, Flag_t flag);

      static constexpr Mask_t negateMask(Mask_t mask);

      static constexpr Mask_t negateMask(Bits_t bits);

      static constexpr Mask_t negateMask(Flag_t flag);

      // -- END Static mask manipulation ---------------------------------------

    private:
      Bits_t values;   
      Bits_t presence; 

      // Storage details
      // We store values and definition information in two different bit
      // buckets; the same Flag_t pattern is good for both.

      void defineSingle(Flag_t flag);

      void undefineSingle(Flag_t flag);

      void undefineImpl() {}

      template <typename... Flags>
      void undefineImpl(Flag_t flag, Flags... others);

      void setImpl() {}

      template <typename... Flags>
      void setImpl(Flag_t flag, Flags... others);

      void setSingle(Flag_t flag);

      void unsetImpl() {}

      constexpr Bits_t definedOnly() const;

      template <typename... Flags>
      void unsetImpl(Flag_t flag, Flags... others);

      void unsetSingle(Flag_t flag);

      static constexpr bool testBits(Storage_t data, Storage_t bits) { return data & bits; }

      static constexpr bool testBitmask(Storage_t data, Storage_t mask)
      {
        return (data & mask) == mask;
      }

      static constexpr bool testUnsetBitmask(Storage_t data, Storage_t mask)
      {
        return (data & ~mask) == data;
      }

    }; // BitMask<>

    template <typename Stream, typename Storage>
    Stream& operator<<(Stream&& out, BitMask<Storage> const& mask)
    {
      mask.dump(std::forward<Stream>(out));
      return out;
    }

    // -- BEGIN Flag and mask management ---------------------------------------

    template <typename Storage>
    constexpr BitMask<Storage> operator|(BitMask<Storage> left, BitMask<Storage> right);

    template <typename Storage>
    constexpr BitMask<Storage> operator|(BitMask<Storage> left,
                                         typename BitMask<Storage>::Bits_t right);

    template <typename Storage>
    constexpr BitMask<Storage> operator|(typename BitMask<Storage>::Bits_t left,
                                         BitMask<Storage> right);

    // operator|(Bits_t, Bits_t) is still a Bits_t

    template <typename Storage>
    constexpr BitMask<Storage> operator&(BitMask<Storage> left, BitMask<Storage> right);

    template <typename Storage>
    constexpr BitMask<Storage> operator&(BitMask<Storage> left,
                                         typename BitMask<Storage>::Bits_t right);

    template <typename Storage>
    constexpr BitMask<Storage> operator&(typename BitMask<Storage>::Bits_t left,
                                         BitMask<Storage> right);

    template <typename Storage>
    constexpr BitMask<Storage> operator&(Bits_t<Storage> left, Bits_t<Storage> right);

    template <typename Storage>
    constexpr BitMask<Storage> operator+(BitMask<Storage> baseMask, BitMask<Storage> mask);

    template <typename Storage>
    constexpr BitMask<Storage> operator+(BitMask<Storage> baseMask,
                                         typename BitMask<Storage>::Bits_t bits);

    template <typename Storage>
    constexpr BitMask<Storage> operator+(typename BitMask<Storage>::Bits_t baseBits,
                                         BitMask<Storage> mask);

    // operator+(Bits_t, Bits_t) is still a Bits_t

    template <typename Storage>
    constexpr BitMask<Storage> operator-(BitMask<Storage> baseMask, BitMask<Storage> mask);

    template <typename Storage>
    constexpr BitMask<Storage> operator-(BitMask<Storage> baseMask,
                                         typename BitMask<Storage>::Bits_t bits);

    template <typename Storage>
    constexpr BitMask<Storage> operator-(typename BitMask<Storage>::Bits_t baseBits,
                                         BitMask<Storage> mask);

    template <typename Storage>
    constexpr BitMask<Storage> operator-(Bits_t<Storage> baseBits, Bits_t<Storage> bits);

    template <typename Storage>
    constexpr BitMask<Storage> operator+(BitMask<Storage> mask);

    template <typename Storage>
    constexpr BitMask<Storage> operator+(Bits_t<Storage> bits);

    template <typename Storage>
    constexpr BitMask<Storage> operator-(Bits_t<Storage> bits);

    template <typename Storage>
    constexpr BitMask<Storage> operator-(Flag_t<Storage> flag);

    template <typename Storage>
    constexpr BitMask<Storage> operator~(BitMask<Storage> mask);

    /*
    template <typename Storage>
    constexpr BitMask<Storage> operator~ (Bits_t<Storage> bits);
    */

    template <typename Storage>
    constexpr BitMask<Storage> Set(Flag_t<Storage> flag);

    template <typename Storage>
    constexpr BitMask<Storage> Unset(Flag_t<Storage> flag);

    // -- END Flag and mask management -----------------------------------------

    template <typename Storage>
    constexpr BitMask<Storage> makeMask(Bits_t<Storage> bits);

  } // namespace flags

} // namespace util

//------------------------------------------------------------------------------
//---  template implementation
//---

#include "lardataobj/Utilities/BitMask.tcc"

//------------------------------------------------------------------------------

#endif // LARDATAOBJ_UTILITIES_BITMASK_H