Copyright	(c) Alice Rixte 2025
License	BSD 3
Maintainer	alice.rixte@u-bordeaux.fr
Stability	stable
Portability	portable Bitmasks for efficient storing of boolean flags
Safe Haskell	None
Language	GHC2021

Data.Bitmask.Internal

Contents

Conversion to and from bits
Check bitmask validity
Bitmask creation
Flag querying
Flag modification

Description

WARNING

This module is considered internal.

The Package Versioning Policy does not apply.

The contents of this module may change in any way whatsoever and without any warning between minor versions of this package.

Authors importing this module are expected to track development closely.

Synopsis

newtype Bitmask w (flag :: k) = Bitmask w
type Bitmask8 = Bitmask Word8 :: k -> Type
type Bitmask16 = Bitmask Word16 :: k -> Type
type Bitmask32 = Bitmask Word32 :: k -> Type
type Bitmask64 = Bitmask Word64 :: k -> Type
fromBits :: forall {k} w (flag :: k). w -> Bitmask w flag
toBits :: forall {k} w (flag :: k). Bitmask w flag -> w
checkBitmask :: forall flag w. (FiniteBits w, Enum flag, Bounded flag) => Bitmask w flag -> Bool
noFlag :: forall {k} w (flag :: k). Bits w => Bitmask w flag
allFlags :: (FiniteBits w, Enum flag) => Bitmask w flag
fromFlags :: (Bits w, Enum flag) => [flag] -> Bitmask w flag
toFlags :: forall flag w. (FiniteBits w, Enum flag, Bounded flag) => Bitmask w flag -> [flag]
fromExceptFlags :: (FiniteBits w, Enum flag) => [flag] -> Bitmask w flag
toExceptFlags :: forall flag w. (FiniteBits w, Enum flag, Bounded flag) => Bitmask w flag -> [flag]
fromFlagsBool :: forall flag w. (Bits w, Enum flag) => [(flag, Bool)] -> Bitmask w flag
toFlagsBool :: forall flag w. (FiniteBits w, Enum flag, Bounded flag) => Bitmask w flag -> [(flag, Bool)]
getFlag :: (Bits w, Enum flag) => flag -> Bitmask w flag -> Bool
getFlags :: (Bits w, Enum flag) => [flag] -> Bitmask w flag -> [Bool]
addFlag :: (Bits w, Enum flag) => flag -> Bitmask w flag -> Bitmask w flag
addFlags :: (Bits w, Enum flag) => [flag] -> Bitmask w flag -> Bitmask w flag
deleteFlag :: (Bits w, Enum flag) => flag -> Bitmask w flag -> Bitmask w flag
deleteFlags :: (Bits w, Enum flag) => [flag] -> Bitmask w flag -> Bitmask w flag
flipFlag :: (Bits w, Enum flag) => flag -> Bitmask w flag -> Bitmask w flag
flipFlags :: (Bits w, Enum flag) => [flag] -> Bitmask w flag -> Bitmask w flag
setFlag :: (Bits w, Enum flag) => flag -> Bool -> Bitmask w flag -> Bitmask w flag
setFlags :: (Bits w, Enum flag) => [(flag, Bool)] -> Bitmask w flag -> Bitmask w flag
modifyFlag :: (Bits w, Enum flag) => flag -> (Bool -> Bool) -> Bitmask w flag -> Bitmask w flag
modifyFlags :: (Bits w, Enum flag) => [flag] -> (Bool -> Bool) -> Bitmask w flag -> Bitmask w flag

Documentation

newtype Bitmask w (flag :: k) Source #

A bitmask that contains boolean flags

The flag type should be an enumeration type (i.e. an instance of Enum).
The w type should be an integral type (e.g. Word8, Word32, etc.) that supports bitwise operations.
The number of bits in w must be at least as many as the number of constructors in flag.

Usage:

data PizzaTopping =
   Cheese
 | Mushrooms
 | Pineapple
 | Ham
 deriving (Show, Eq, Bounded, Enum)

 type PizzaMask = Bitmask8 PizzaTopping Word8

Constructors

Bitmask w

Instances

Instances details

Bits w => Bits (Bitmask w flag) Source #
Instance details Defined in Data.Bitmask.Internal Methods (.&.) :: Bitmask w flag -> Bitmask w flag -> Bitmask w flag # (.\|.) :: Bitmask w flag -> Bitmask w flag -> Bitmask w flag # xor :: Bitmask w flag -> Bitmask w flag -> Bitmask w flag # complement :: Bitmask w flag -> Bitmask w flag # shift :: Bitmask w flag -> Int -> Bitmask w flag rotate :: Bitmask w flag -> Int -> Bitmask w flag zeroBits :: Bitmask w flag bit :: Int -> Bitmask w flag setBit :: Bitmask w flag -> Int -> Bitmask w flag clearBit :: Bitmask w flag -> Int -> Bitmask w flag complementBit :: Bitmask w flag -> Int -> Bitmask w flag testBit :: Bitmask w flag -> Int -> Bool bitSizeMaybe :: Bitmask w flag -> Maybe Int bitSize :: Bitmask w flag -> Int isSigned :: Bitmask w flag -> Bool shiftL :: Bitmask w flag -> Int -> Bitmask w flag unsafeShiftL :: Bitmask w flag -> Int -> Bitmask w flag shiftR :: Bitmask w flag -> Int -> Bitmask w flag unsafeShiftR :: Bitmask w flag -> Int -> Bitmask w flag rotateL :: Bitmask w flag -> Int -> Bitmask w flag rotateR :: Bitmask w flag -> Int -> Bitmask w flag popCount :: Bitmask w flag -> Int
Show w => Show (Bitmask w flag) Source #
Instance details Defined in Data.Bitmask.Internal Methods showsPrec :: Int -> Bitmask w flag -> ShowS show :: Bitmask w flag -> String showList :: [Bitmask w flag] -> ShowS
Eq w => Eq (Bitmask w flag) Source #
Instance details Defined in Data.Bitmask.Internal Methods (==) :: Bitmask w flag -> Bitmask w flag -> Bool (/=) :: Bitmask w flag -> Bitmask w flag -> Bool
Ord w => Ord (Bitmask w flag) Source #
Instance details Defined in Data.Bitmask.Internal Methods compare :: Bitmask w flag -> Bitmask w flag -> Ordering (<) :: Bitmask w flag -> Bitmask w flag -> Bool (<=) :: Bitmask w flag -> Bitmask w flag -> Bool (>) :: Bitmask w flag -> Bitmask w flag -> Bool (>=) :: Bitmask w flag -> Bitmask w flag -> Bool max :: Bitmask w flag -> Bitmask w flag -> Bitmask w flag min :: Bitmask w flag -> Bitmask w flag -> Bitmask w flag

type Bitmask8 = Bitmask Word8 :: k -> Type Source #

type Bitmask16 = Bitmask Word16 :: k -> Type Source #

type Bitmask32 = Bitmask Word32 :: k -> Type Source #

type Bitmask64 = Bitmask Word64 :: k -> Type Source #

Conversion to and from bits

fromBits :: forall {k} w (flag :: k). w -> Bitmask w flag Source #

Create a bitmask from raw bits.

toBits :: forall {k} w (flag :: k). Bitmask w flag -> w Source #

Convert a bitmask to raw bits.

Check bitmask validity

checkBitmask :: forall flag w. (FiniteBits w, Enum flag, Bounded flag) => Bitmask w flag -> Bool Source #

Check that a bitmask can represent all flags.

>>> checkBitmask (allFlags :: Bitmask8 PizzaTopping)
True

Bitmask creation

noFlag :: forall {k} w (flag :: k). Bits w => Bitmask w flag Source #

A bitmask with all flags set to False.

>>> getFlag Mushrooms (noFlag :: PizzaMask)
False

allFlags :: (FiniteBits w, Enum flag) => Bitmask w flag Source #

A bitmask with all flags set to True.

>>> getFlag Mushrooms (allFlags :: PizzaMask)
True

fromFlags :: (Bits w, Enum flag) => [flag] -> Bitmask w flag Source #

Create a bitmask from a list of flags to set to True.

>>> hawaiian = fromFlags [Pineapple, Ham, Cheese] :: PizzaMask

toFlags :: forall flag w. (FiniteBits w, Enum flag, Bounded flag) => Bitmask w flag -> [flag] Source #

Convert a bitmask to a list of flags that are set to True.

>>> toFlags hawaiian
[Cheese,Pineapple,Ham]

fromExceptFlags :: (FiniteBits w, Enum flag) => [flag] -> Bitmask w flag Source #

Create a bitmask from a list of flags to set to False

>>> veggie = fromExceptFlags [Ham] :: PizzaMask

toExceptFlags :: forall flag w. (FiniteBits w, Enum flag, Bounded flag) => Bitmask w flag -> [flag] Source #

Convert a bitmask to a list of flags that are set to False.

>>> toExceptFlags veggie
[Ham]

fromFlagsBool :: forall flag w. (Bits w, Enum flag) => [(flag, Bool)] -> Bitmask w flag Source #

Convert an association list of flags and boolean values to a bitmask.

>>> funghi = fromFlagsBool [(Cheese, True), (Ham, False), (Mushrooms, True)] :: PizzaMask

toFlagsBool :: forall flag w. (FiniteBits w, Enum flag, Bounded flag) => Bitmask w flag -> [(flag, Bool)] Source #

Convert a bitmask to an association list of flags and boolean values.

>>> toFlagsBool funghi
[(Cheese,True),(Mushrooms,True),(Pineapple,False),(Ham,False)]

Flag querying

getFlag :: (Bits w, Enum flag) => flag -> Bitmask w flag -> Bool Source #

Get a flag from a bitmask.

>>> getFlag Mushrooms hawaiian
False

getFlags :: (Bits w, Enum flag) => [flag] -> Bitmask w flag -> [Bool] Source #

Get multiple flags from a bitmask.

>>> getFlags [Cheese, Mushrooms] hawaiian
[True,False]

Flag modification

addFlag :: (Bits w, Enum flag) => flag -> Bitmask w flag -> Bitmask w flag Source #

Add a flag to a bitmask (set it to True).

>>> margherita = addFlag Cheese (noFlag :: PizzaMask)

addFlags :: (Bits w, Enum flag) => [flag] -> Bitmask w flag -> Bitmask w flag Source #

Add multiple flags to a bitmask (set them to True).

>>> hawaiian = addFlags [Pineapple, Ham] margherita

deleteFlag :: (Bits w, Enum flag) => flag -> Bitmask w flag -> Bitmask w flag Source #

Remove a flag from a bitmask (set it to False).

>>> veggie = deleteFlag Ham (allFlags :: PizzaMask)

deleteFlags :: (Bits w, Enum flag) => [flag] -> Bitmask w flag -> Bitmask w flag Source #

Remove multiple flags from a bitmask (set them to False).

>>> picky = deleteFlags [Pineapple, Ham] (allFlags :: PizzaMask)

flipFlag :: (Bits w, Enum flag) => flag -> Bitmask w flag -> Bitmask w flag Source #

Flip a flag in a bitmask.

>>> margherita = flipFlag Cheese (noFlag :: PizzaMask)

flipFlags :: (Bits w, Enum flag) => [flag] -> Bitmask w flag -> Bitmask w flag Source #

Flip multiple flags in a bitmask.

>>> funghi = flipFlags [Mushrooms, Ham, Pineapple] hawaiian

setFlag :: (Bits w, Enum flag) => flag -> Bool -> Bitmask w flag -> Bitmask w flag Source #

Set a flag in a bitmask.

>>> funghi = setFlag Mushrooms True margherita

setFlags :: (Bits w, Enum flag) => [(flag, Bool)] -> Bitmask w flag -> Bitmask w flag Source #

Set multiple flags in a bitmask.

>>> hawaiian = setFlags [(Ham, True), (Pineapple, True)] margherita

modifyFlag :: (Bits w, Enum flag) => flag -> (Bool -> Bool) -> Bitmask w flag -> Bitmask w flag Source #

Modify a flag in a bitmask.

>>> veggie = modifyFlag Ham not (allFlags :: PizzaMask)

modifyFlags :: (Bits w, Enum flag) => [flag] -> (Bool -> Bool) -> Bitmask w flag -> Bitmask w flag Source #

Modify multiple flags in a bitmask.

>>> picky = modifyFlags [Pineapple, Ham] not (allFlags :: PizzaMask)