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: Parke
Namespace that wraps all Logic created by Tyler Parke
 *-----------------------------------------------------------------------------------------------**/
 
namespace NDEVR
{
    /**--------------------------------------------------------------------------------------------------
    Class: BitFlag
    
    \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).
    
    Author: Tyler Parke
    
    Date: 2017-11-17
     *-----------------------------------------------------------------------------------------------**/
 
    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);
        }
 
        /**--------------------------------------------------------------------------------------------------
        Fn: constexpr bool BitFlag::operator[](uint01 index) const
        
        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.
        
        Author: Tyler Parke
        
        Date: 2017-11-17
        
        Parameters:
        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;
        }
 
        /**--------------------------------------------------------------------------------------------------
        Fn: constexpr void BitFlag::operator()(const uint01 index, bool value)
        
        Operator used to set a bit in the bitflag to the given value
        
        Author: Tyler Parke
        
        Date: 2017-11-17
        
        Parameters:
        index -     The index of the bit you wish to set
        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;
        }
        /**--------------------------------------------------------------------------------------------------
        Fn: constexpr operator BitFlag::uint01() const
 
        Cast that converts the given  to an uint01.
 
        Author: Tyler Parke
 
        Date: 2017-11-17
 
        Returns: The result of the operation.
        *-----------------------------------------------------------------------------------------------**/
 
        constexpr operator uint01() const
        {
            return m_bits;
        }
 
        /**--------------------------------------------------------------------------------------------------
        Fn: constexpr void BitFlag::operator|=(const BitFlag& mask)
        
        Bitwise 'or' assignment operator.
        
        Author: Tyler Parke
        
        Date: 2017-11-17
        
        Parameters:
        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;
        }
 
        /**--------------------------------------------------------------------------------------------------
        Fn: constexpr void BitFlag::operator&=(const BitFlag& mask)
        
        Bitwise 'and' assignment operator.
        
        Author: Tyler Parke
        
        Date: 2017-11-17
        
        Parameters:
        mask -  The mask.
         *-----------------------------------------------------------------------------------------------**/
 
        constexpr void operator&=(const BitFlag& mask)
        {
            m_bits &= mask.m_bits;
        }
 
        /**--------------------------------------------------------------------------------------------------
        Fn: constexpr void BitFlag::operator&=(uint01 mask)
        
        Bitwise 'and' assignment operator.
        
        Author: Tyler Parke
        
        Date: 2017-11-17
        
        Parameters:
        mask -  The mask.
         *-----------------------------------------------------------------------------------------------**/
 
        constexpr void operator&=(uint01 mask)
        {
            m_bits &= mask;
        }
 
        /**--------------------------------------------------------------------------------------------------
        Fn: constexpr BitFlag BitFlag::operator&(const BitFlag& mask) const
        
        Bitwise 'and' operator.
        
        Author: Tyler Parke
        
        Date: 2017-11-17
        
        Parameters:
        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));
        }
 
        /**--------------------------------------------------------------------------------------------------
        Fn: constexpr BitFlag BitFlag::operator^(const BitFlag& mask) const
        
        Bitwise 'exclusive or' operator.
        
        Author: Tyler Parke
        
        Date: 2017-11-17
        
        Parameters:
        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));
        }
 
        /**--------------------------------------------------------------------------------------------------
        Fn: constexpr BitFlag BitFlag::operator&(uint01 mask) const
        
        Bitwise 'and' operator.
        
        Author: Tyler Parke
        
        Date: 2017-11-17
        
        Parameters:
        mask -  The mask.
        
        Returns: The result of the operation.
         *-----------------------------------------------------------------------------------------------**/
 
        constexpr BitFlag operator&(uint01 mask) const
        {
            return BitFlag(cast<uint01>(m_bits & mask));
        }
 
        /**--------------------------------------------------------------------------------------------------
        Fn: constexpr BitFlag BitFlag::operator^(uint01 mask) const
        
        Bitwise 'exclusive or' operator.
        
        Author: Tyler Parke
        
        Date: 2017-11-17
        
        Parameters:
        mask -  The mask.
        
        Returns: The result of the operation.
         *-----------------------------------------------------------------------------------------------**/
 
        constexpr BitFlag operator^(uint01 mask) const
        {
            return BitFlag(cast<uint01>(m_bits ^ mask));
        }
 
        /**--------------------------------------------------------------------------------------------------
        Fn: constexpr BitFlag BitFlag::operator~() const
        
        Bitwise 'ones complement' operator.
        
        Author: Tyler Parke
        
        Date: 2017-11-17
        
        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;
        }
 
        /**--------------------------------------------------------------------------------------------------
        Fn: constexpr static BitFlag BitFlag::merge(const BitFlag& value_a, const BitFlag& value_b,
        const BitFlag& mask)
        
        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
        
        Author: Tyler Parke
        
        Date: 2017-11-17
        
        Parameters:
        value_a -       A BitFlag to process where values of mask 0 will be used.
        value_b -       A BitFlag to process where values of mask 1 will be used.
        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);
        }
 
        /**--------------------------------------------------------------------------------------------------
        Fn: constexpr static BitFlag BitFlag::merge(const BitFlag& value_a, const BitFlag& value_b,
        const BitFlag& mask)
        
        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
        
        Author: Tyler Parke
        
        Date: 2017-11-17
        
        Parameters:
        value_a -       A BitFlag to process where values of mask 0 will be used.
        value_b -       A BitFlag to process where values of mask 1 will be used.
        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& a, const BitFlag& b, uint01 num_of_bits)
        {
            const uint01 mask = cast<uint01>((1U << (num_of_bits + 1U)) - 1U);
            return b ^ ((b ^ 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