BitFlag.hpp

Go to the documentation of this file.

/*--------------------------------------------------------------------------------------------
Copyright (c) 2019, NDEVR LLC
tyler.parke@ndevr.org
  __    __   ____     _____ __     __  _______
 |  \  |  | |  __ \  |  ___|\ \   / / |   __  \
 |   \ |  | | |  \ \ | |___  \ \ / /  |  |__)  |
 |  . \|  | | |__/ / | |___   \ V /   |   _   /
 |  |\    |_|_____/__|_____|___\_/____|  | \  \
 |__| \__________________________________|  \__\
 
Subject to the terms of the Enterprise+ Agreement, NDEVR hereby grants 
Licensee a limited, non-exclusive, non-transferable, royalty-free license 
(without the right to sublicense) to use the API solely for the purpose of 
Licensee's internal development efforts to develop applications for which 
the API was provided.
 
The above copyright notice and this permission notice shall be included in all 
copies or substantial portions of the Software.
 
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
 
Library: Base
File: BitFlag
Included in API: True
Author(s): Tyler Parke
 *-----------------------------------------------------------------------------------------**/
#pragma once
#include <NDEVR/BaseValues.h>
#include <NDEVR/LibAssert.h>
namespace NDEVR
{
    /**-----------------------------------------------------------------------------------------
    \brief A bitset that stores 8 bits (elements with only two possible values: 0 or 1, true or false, ...).
 
    The class emulates an array of 8 bool elements, but optimized for space allocation: generally, 
        each element occupies only one bit (which, on most systems, is eight times less than 
        the smallest elemental type: int01).
 
    Each bit position can be accessed individually: for example, for a given bitset named foo, 
        the expression foo[3] accesses its fourth bit, just like a regular array accesses its elements. 
        But because no elemental type is a single bit, operator(bit, value) must be used to set
        values.
 
    Bitsets have the feature of being able to be constructed from and converted to both integer 
        values and binary strings (see its constructor and members to_ulong and to_string). 
        They can also be directly inserted and extracted from streams in binary format 
        (see applicable operators).
    *-----------------------------------------------------------------------------------------**/
    class BitFlag
    {
    public:
        constexpr BitFlag()
            : m_bits(0)
        {}
        constexpr BitFlag(sint04 flags)
            : m_bits(cast<uint01>(flags))
        {
            lib_assert(flags <= 255, "Bad bitflag");
        }
        constexpr BitFlag(uint01 flags)
            : m_bits(flags)
        {}
        explicit constexpr BitFlag(bool flag)
            : m_bits(flag ? 255U : 0U)
        {}
 
        template<class t_type>
        BitFlag(std::initializer_list<t_type> active_list)
            : m_bits(0)
        {
            for (auto i : active_list)
                (*this)(cast<uint01>(i), true);
        }
 
        /**
        \brief Accesses the value at bit position specified by index. Note this function may have more overhead
            than traditional [] since an operation will be used. Can only be a read-only value.
        \param[in] bit_index The index of the bit you wish to access
        \returns The indexed value.
        **/
        constexpr bool operator[](uint01 bit_index) const
        {
            lib_assert(bit_index < 8, "Tried to access large bit value");
            const uint01 mask = cast<uint01>(1U << bit_index);
            return (m_bits & mask) != 0;
        }
 
        /**
        \brief Operator used to set a bit in the bitflag to the given value
        Parameters:
        \param[in] bit_index The index of the bit you wish to set
        \param[in] value The value to set the bit
         **/
        constexpr void operator()(const uint01 bit_index, bool value)
        {
            const uint01 mask = cast<uint01>(1U << bit_index);
            if (value)
                m_bits |= mask;
            else
                m_bits &= ~mask;
        }
 
        /**
        \brief Cast that converts the given to an uint01.
        \returns The result of the operation.
        **/
        constexpr operator uint01() const
        {
            return m_bits;
        }
 
        /**
        \brief Bitwise 'or' assignment operator.
        \param[in] mask The mask.
         **/
        constexpr void operator|=(const BitFlag& mask)
        {
            m_bits |= mask.m_bits;
        }
 
 
        constexpr void operator^=(const BitFlag& mask)
        {
            m_bits ^= mask.m_bits;
        }
 
        /**
        \brief Bitwise 'and' assignment operator.
        \param[in] mask The mask.
         **/
        constexpr void operator&=(const BitFlag& mask)
        {
            m_bits &= mask.m_bits;
        }
 
        /**
        \brief Bitwise 'and' assignment operator.
        \param[in] mask The mask.
         **/
        constexpr void operator&=(uint01 mask)
        {
            m_bits &= mask;
        }
 
        /**
        \brief Bitwise 'and' operator.
        \param[in] mask -  The mask.
        \returns The result of the operation.
         **/
        constexpr BitFlag operator&(const BitFlag& mask) const
        {
            return BitFlag(cast<uint01>(m_bits & mask.m_bits));
        }
 
        /**
        \brief Bitwise 'exclusive or' operator.
        \param[in] mask -  The mask.
        \returns The result of the operation.
         **/
        constexpr BitFlag operator^(const BitFlag& mask) const
        {
            return BitFlag(cast<uint01>(m_bits ^ mask.m_bits));
        }
 
        /**
        \brief Bitwise 'and' operator.
        \param[in] mask -  The mask.
        \returns The result of the operation.
         **/
        constexpr BitFlag operator&(uint01 mask) const
        {
            return BitFlag(cast<uint01>(m_bits & mask));
        }
 
        /**
        \brief Bitwise 'exclusive or' operator.
        \param[in] mask -  The mask.
        \returns The result of the operation.
         **/
        constexpr BitFlag operator^(uint01 mask) const
        {
            return BitFlag(cast<uint01>(m_bits ^ mask));
        }
 
        /**
        \brief Bitwise 'ones complement' operator.
        \returns The result of the operation.
         **/
        constexpr BitFlag operator~() const
        {
            return BitFlag(cast<uint01>(~m_bits));
        }
 
 
        constexpr bool operator!=(const BitFlag& other) const
        {
            return m_bits != other.m_bits;
        }
        constexpr bool operator==(const BitFlag& other) const
        {
            return m_bits == other.m_bits;
        }
 
        /**
                
        \brief Given bit value_a and bit value_b merges the bits such that indices with a mask of false will be set to 
            value_a and values with a bit of mask 0 will be set to b in the returning bitflag.
        \param[in] value_a  A BitFlag to process where values of mask 0 will be used.
        \param[in] value_b A BitFlag to process where values of mask 1 will be used.
        \param[in] mask The mask used to determine which bits will be used.
        \returns A BitFlag consisting of the merging of value_a and value_b as defined by the mask.
         **/
        constexpr static BitFlag merge(const BitFlag& value_a, const BitFlag& value_b, const BitFlag& mask)
        {
            return value_b ^ ((value_b ^ value_a) & mask);
        }
 
        /** 
        \brief Given bit value_a and bit value_b merges the bits such that indices with a value lower than num_of_bits 
            will be set to value_a and values with a bit of mask 0 will be set to b in the returning bitflag
        \param[in] value_a A BitFlag to process where values of mask 0 will be used.
        \param[in] value_b A BitFlag to process where values of mask 1 will be used.
        \param[in] num_of_bits The bits used to use from value_a.
        \returns A BitFlag consisting of the merging of value_a and value_b as defined by the num_of_bits.
         **/
        constexpr static BitFlag merge(const BitFlag& value_a, const BitFlag& value_b, uint01 num_of_bits)
        {
            const uint01 mask = cast<uint01>((1U << (num_of_bits + 1U)) - 1U);
            return value_b ^ ((value_b ^ value_a) & mask);
        }
 
        [[nodiscard]] uint01 bits() const
        {
            return m_bits;
        }
    private:
        /** The bit information. */
        uint01 m_bits;
    };
}
#ifdef _MSC_VER
//Used to help debuging
namespace natvis
{
    struct b4lo { unsigned __int8 v : 4;    unsigned __int8 _ : 4; };  // NOLINT(clang-diagnostic-language-extension-token)
    struct b4hi { unsigned __int8 _ : 4;    unsigned __int8 v : 4; };  // NOLINT(clang-diagnostic-language-extension-token)
    struct b8 { unsigned __int8 _; }; // NOLINT(clang-diagnostic-language-extension-token)
    struct b32 { __int32 _; }; // NOLINT(clang-diagnostic-language-extension-token)
}
#endif