BitMask.h

Go to the documentation of this file.

#ifndef LARDATAOBJ_UTILITIES_BITMASK_H
#define LARDATAOBJ_UTILITIES_BITMASK_H


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

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