-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Sets of enumeration values represented by machine words
--   
--   With this package you can create a type safe interface to flag sets.
--   It is intended for interfacing to C libraries via FFI, where Word8,
--   Word16, or Word32 types are commonly used to store bit vectors. E.g.
--   the type <tt>EnumSet Word16 Ordering</tt> represents a flag set stored
--   in a Word16 that supports the flags <tt>LT</tt>, <tt>EQ</tt>,
--   <tt>GT</tt>.
--   
--   This package is similar to the <tt>bitset</tt> package and the
--   <tt>Data.Edison.Coll.EnumSet</tt> module in the <tt>edison</tt>
--   package, however our implementation allows you to choose the embedding
--   type and thus the maximum size of the set.
@package enumset
@version 0.0.3


-- | A bit vector that represents a record in a bit-packed way.
module Data.FlagSet

-- | The basic bit vector data type. It does not provide a lot of
--   functionality, since that could not be done in a safe way.
--   
--   The type <tt>a</tt> identifies the maintained flags. It may be an
--   empty type but it may also be an enumeration of record fields with
--   concrete values. In the latter case you are encouraged to define an
--   <a>Enum</a> instance for this enumeration. Be aware that it is
--   different from <a>Enum</a> of Prelude.
newtype T word a
Cons :: word -> T word a
decons :: T word a -> word
fromMaskedValue :: MaskedValue w a -> T w a
match :: Bits w => T w a -> MaskedValue w a -> Bool
class Enum a
fromEnum :: (Enum a, Bits w) => a -> MaskedValue w a

-- | Compose a flag set from a list of flags. However you may prefer to
--   assemble flags using <a>mconcat</a> or <a>mappend</a> on
--   <a>MaskedValue</a>s.
compose :: (Enum a, Enum a, Bits w) => [a] -> T w a

-- | Decompose a flag set into flags. The flags are generated using the
--   <a>Bounded</a> and <a>Enum</a> instance. We do not recommend to use
--   the result list for further processing, since testing of flags is much
--   faster using <a>match</a>. However you may find it useful to
--   <a>show</a> the list.
decompose :: (Bounded a, Enum a, Enum a, Bits w) => T w a -> [a]

-- | <tt>Mask w a b</tt> describes a field of a <tt>T w a</tt> that has
--   type <tt>Value w b</tt>. On the machine level a <a>Mask</a> value is a
--   vector of bits, where set bits represent the bits belonging to one
--   record field. There must be only one mask value for every pair of
--   types <tt>(a,b)</tt>.
newtype Mask w a b
Mask :: w -> Mask w a b
unmask :: Mask w a b -> w
maskValue :: Mask w a b -> Value w b -> MaskedValue w a

-- | The type parameter <tt>w</tt> is the type of the underlying bit
--   vector. The type parameter <tt>b</tt> is a phantom type, that is
--   specific for a certain range of bits.
newtype Value w b
Value :: w -> Value w b
unvalue :: Value w b -> w

-- | Combines a mask with a value, that matches this mask. In
--   <tt>MaskedValue mask value</tt>, <tt>value</tt> must be a subset of
--   <tt>mask</tt>.
data MaskedValue w a
MaskedValue :: w -> w -> MaskedValue w a
get :: (Enum a, Bits w) => Mask w a b -> T w a -> Value w b

-- | All bits in Value must be contained in the mask. This condition is not
--   checked by <a>put</a>.
--   
--   According to names in <a>Data.Accessor</a> it should be called
--   <tt>set</tt>, but in <a>Data.Bits</a> and thus <a>Data.EnumSet</a>
--   this is already used in the pair <tt>set</tt>/<tt>clear</tt>.
--   <tt>put</tt>/<tt>get</tt> resembles the pair in
--   <a>Control.Monad.State</a> in the <tt>mtl</tt> package.
put :: (Enum a, Bits w) => Mask w a b -> Value w b -> T w a -> T w a
accessor :: (Enum a, Bits w) => Mask w a b -> T (T w a) (Value w b)
instance Eq word => Eq (T word a)
instance Eq w => Eq (Mask w a b)
instance Show w => Show (Mask w a b)
instance Eq w => Eq (Value w b)
instance Show w => Show (Value w b)
instance Eq w => Eq (MaskedValue w a)
instance Show w => Show (MaskedValue w a)
instance Bits w => Monoid (MaskedValue w a)
instance Storable w => Storable (T w a)

module Data.FlagSet.PackedRecord
getIntByMask :: (Bits w, Integral w, Integral i) => Mask w a b -> T w a -> i
putIntByMask :: (Bits w, Integral w, Integral i) => Mask w a b -> i -> T w a -> T w a
accessorIntByMask :: (Bits w, Integral w, Integral i) => Mask w a b -> T (T w a) i
getIntByRange :: (Bits w, Integral w, Integral i) => Int -> Int -> T w a -> i
putIntByRange :: (Bits w, Integral w, Integral i) => Int -> Int -> i -> T w a -> T w a
accessorIntByRange :: (Bits w, Integral w, Integral i) => Int -> Int -> T (T w a) i


-- | Similar to Data.Edison.Coll.EnumSet but it allows to choose the
--   underlying type for bit storage. This is really a low-level module for
--   type-safe foreign function interfaces.
--   
--   The integer representation of the enumeration type is the bit position
--   of the flag within the bitvector.
module Data.EnumSet
newtype T word index
Cons :: word -> T word index
decons :: T word index -> word
fromEnum :: (Enum a, Bits w) => a -> T w a
fromEnums :: (Enum a, Bits w) => [a] -> T w a
toEnums :: (Enum a, Bits w) => T w a -> [a]
intToEnums :: (Enum a, Integral w) => T w a -> [a]

-- | floor of binary logarithm - Intended for getting the position of a
--   single set bit. This in turn is intended for implementing an
--   <a>Enum</a> instance if you only know masks but no bit positions.
mostSignificantPosition :: (Bits w, Storable w) => T w a -> Int

-- | set a bit - Intended for implementing an <a>Enum</a> instance if you
--   only know masks but no bit positions.
singletonByPosition :: Bits w => Int -> T w a
null :: (Enum a, Bits w) => T w a -> Bool
empty :: (Enum a, Bits w) => T w a
singleton :: (Enum a, Bits w) => a -> T w a
disjoint :: (Enum a, Bits w) => T w a -> T w a -> Bool

-- | <tt>subset a b</tt> is <a>True</a> if <tt>a</tt> is a subset of
--   <tt>b</tt>.
subset :: (Enum a, Bits w) => T w a -> T w a -> Bool
(.&., xor, .|., .-.) :: (Enum a, Bits w) => T w a -> T w a -> T w a
unions :: (Enum a, Bits w) => [T w a] -> T w a

-- | could also be named <tt>member</tt> like in <tt>Set</tt> or
--   <tt>elem</tt> as in '[]'
get :: (Enum a, Bits w) => a -> T w a -> Bool
put :: (Enum a, Bits w) => a -> Bool -> T w a -> T w a
accessor :: (Enum a, Bits w) => a -> T (T w a) Bool

-- | could also be named <tt>insert</tt> like in <tt>Set</tt>
set :: (Enum a, Bits w) => a -> T w a -> T w a

-- | could also be named <tt>delete</tt> like in <tt>Set</tt>
clear :: (Enum a, Bits w) => a -> T w a -> T w a
flip :: (Enum a, Bits w) => a -> T w a -> T w a
fromBool :: (Enum a, Bits w) => a -> Bool -> T w a
instance Eq word => Eq (T word index)
instance (Enum a, Bits w) => Monoid (T w a)
instance (Enum a, Storable w) => Storable (T w a)


-- | Extract and inject an Enum value into an EnumSet.
module Data.EnumSet.PackedEnum

-- | <tt> T w a b</tt> describes a contiguous set of bit indices into the
--   word type <tt>w</tt> where the indices are of type <tt>a</tt> and the
--   set of indices represent a value of type <tt>b</tt>.
data T w a b
Cons :: w -> Int -> T w a b

-- | Extract an enumeration value from the specified index set.
unpack :: (Integral w, Bits w, Enum a, Enum b) => T w a b -> T w a -> b

-- | Create an enumeration set, where an value of type <tt>b</tt> is placed
--   at the specified indices.
pack :: (Bits w, Enum a, Enum b) => T w a b -> b -> T w a

-- | Clear all bits at the specified indices.
clear :: (Bits w, Enum a, Enum b) => T w a b -> T w a -> T w a

-- | Overwrite an enumset at the specified indices with the value of type
--   <tt>b</tt>.
put :: (Bits w, Enum a, Enum b) => T w a b -> b -> T w a -> T w a