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


-- | Portable big-endian and little-endian conversions
--   
--   This library provides an interface to portably work with byte arrays
--   whose contents are known to be of a fixed endianness. There are two
--   ways to use this module. See the <a>System.ByteOrder</a> module for
--   more documentation.
@package byte-order
@version 0.1.2.0

module System.ByteOrder.Class

-- | A byte order that can be interpreted as a conversion function. This
--   class is effectively closed. The only instances are for
--   <a>BigEndian</a> and <a>LittleEndian</a>. It is not possible to write
--   more instances since there are no other inhabitants of
--   <a>ByteOrder</a>.
class FixedOrdering (b :: ByteOrder)
toFixedEndian :: (FixedOrdering b, Bytes a) => a -> a

-- | Types that are represented as a fixed-sized word. For these types, the
--   bytes can be swapped. The instances of this class use byteswapping
--   primitives and compile-time knowledge of native endianness to provide
--   portable endianness conversion functions.
class Bytes a

-- | Convert from a native-endian word to a big-endian word.
toBigEndian :: Bytes a => a -> a

-- | Convert from a native-endian word to a little-endian word.
toLittleEndian :: Bytes a => a -> a
instance System.ByteOrder.Class.FixedOrdering 'GHC.ByteOrder.LittleEndian
instance System.ByteOrder.Class.FixedOrdering 'GHC.ByteOrder.BigEndian
instance System.ByteOrder.Class.Bytes GHC.Word.Word8
instance System.ByteOrder.Class.Bytes GHC.Word.Word16
instance System.ByteOrder.Class.Bytes GHC.Word.Word32
instance System.ByteOrder.Class.Bytes GHC.Word.Word64
instance System.ByteOrder.Class.Bytes GHC.Types.Word
instance System.ByteOrder.Class.Bytes GHC.Int.Int8
instance System.ByteOrder.Class.Bytes GHC.Int.Int16
instance System.ByteOrder.Class.Bytes GHC.Int.Int32
instance System.ByteOrder.Class.Bytes GHC.Int.Int64


-- | This module offers an interface to portably work with byte arrays
--   whose contents are known to be of a fixed endianness. There are two
--   ways to use this module:
--   
--   <ul>
--   <li>Untyped Conversions: The functions <a>toBigEndian</a>,
--   <a>toLittleEndian</a>, <a>fromBigEndian</a>, and
--   <a>fromLittleEndian</a> convert between native-endian words and
--   big/little-endian words. The word resulting from
--   <tt>to(Big|Little)Endian</tt> should be written to a primitive byte
--   array or a pointer afterwards. (There is no other purpose of such a
--   conversion.) Similarly, the argument to
--   <tt>from(Big|Little)Endian</tt> should be a word that was read from a
--   primitive byte array or a pointer. This interface is useful when
--   serializing or deserializing a data structure with fields of varying
--   sizes.</li>
--   <li>Typed Conversions: The type <a>Fixed</a> provides a convenient
--   type-directed interface to working with arrays of homogenous words.
--   This interface is easier to use and should be preferred when
--   possible.</li>
--   </ul>
--   
--   The example at the bottom of this page demonstrates how to use the
--   type-directed interface.
module System.ByteOrder

-- | Byte ordering.
data ByteOrder

-- | most-significant-byte occurs in lowest address.
BigEndian :: ByteOrder

-- | least-significant-byte occurs in lowest address.
LittleEndian :: ByteOrder

-- | A word whose byte order is specified (not platform dependent) when
--   working with <a>Prim</a>, <a>Storable</a>, and <tt>PrimUnaligned</tt>
--   (this last instance is provided alongside the typeclass itself in the
--   <tt>primitive-unaligned</tt> library).
newtype Fixed :: ByteOrder -> Type -> Type
[Fixed] :: forall (b :: ByteOrder) (a :: Type). {getFixed :: a} -> Fixed b a

-- | Types that are represented as a fixed-sized word. For these types, the
--   bytes can be swapped. The instances of this class use byteswapping
--   primitives and compile-time knowledge of native endianness to provide
--   portable endianness conversion functions.
class Bytes a

-- | A byte order that can be interpreted as a conversion function. This
--   class is effectively closed. The only instances are for
--   <a>BigEndian</a> and <a>LittleEndian</a>. It is not possible to write
--   more instances since there are no other inhabitants of
--   <a>ByteOrder</a>.
class FixedOrdering (b :: ByteOrder)

-- | Convert from a native-endian word to a big-endian word.
toBigEndian :: Bytes a => a -> a

-- | Convert from a native-endian word to a little-endian word.
toLittleEndian :: Bytes a => a -> a

-- | Convert from a big-endian word to a native-endian word.
fromBigEndian :: Bytes a => a -> a

-- | Convert from a little-endian word to a native-endian word.
fromLittleEndian :: Bytes a => a -> a

-- | The byte ordering of the target machine.
targetByteOrder :: ByteOrder
instance GHC.Num.Num a => GHC.Num.Num (System.ByteOrder.Fixed b a)
instance GHC.Real.Real a => GHC.Real.Real (System.ByteOrder.Fixed b a)
instance GHC.Real.Integral a => GHC.Real.Integral (System.ByteOrder.Fixed b a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (System.ByteOrder.Fixed b a)
instance GHC.Enum.Enum a => GHC.Enum.Enum (System.ByteOrder.Fixed b a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (System.ByteOrder.Fixed b a)
instance (System.ByteOrder.Class.FixedOrdering b, Data.Primitive.Types.Prim a, System.ByteOrder.Class.Bytes a) => Data.Primitive.Types.Prim (System.ByteOrder.Fixed b a)
instance (System.ByteOrder.Class.FixedOrdering b, Data.Primitive.ByteArray.Unaligned.PrimUnaligned a, System.ByteOrder.Class.Bytes a) => Data.Primitive.ByteArray.Unaligned.PrimUnaligned (System.ByteOrder.Fixed b a)
instance (System.ByteOrder.Class.FixedOrdering b, Foreign.Storable.Storable a, System.ByteOrder.Class.Bytes a) => Foreign.Storable.Storable (System.ByteOrder.Fixed b a)


-- | This is drop-in replacement for the read, write, and index functions
--   present in <tt>Data.Primitive.ByteArray</tt> and
--   <tt>Data.Primitive.ByteArray.Unaligned</tt>. While the functions from
--   those modules use native byte order, the functions in this one use
--   little-endian byte order (least significant byte first).
module Data.Primitive.ByteArray.LittleEndian

-- | Write a primitive value to the byte array. The offset is given in
--   elements of type <tt>a</tt> rather than in bytes. The least
--   significant byte in the value comes first.
writeByteArray :: (PrimMonad m, Prim a, Bytes a) => MutableByteArray (PrimState m) -> Int -> a -> m ()

-- | Read a primitive value from the byte array, interpreting the first
--   byte as the least significant one. The offset is given in elements of
--   type <tt>a</tt> rather than in bytes.
readByteArray :: (PrimMonad m, Prim a, Bytes a) => MutableByteArray (PrimState m) -> Int -> m a

-- | Read a primitive value from the byte array, interpreting the first
--   byte as the least significant one. The offset is given in elements of
--   type <tt>a</tt> rather than in bytes.
indexByteArray :: (Prim a, Bytes a) => ByteArray -> Int -> a

-- | Write a primitive value to the byte array. The offset is given in
--   bytes rather than in elements of type <tt>a</tt>. The least
--   significant byte in the value comes first.
writeUnalignedByteArray :: (PrimMonad m, PrimUnaligned a, Bytes a) => MutableByteArray (PrimState m) -> Int -> a -> m ()

-- | Read a primitive value from the byte array, interpreting the first
--   byte as the least significant one. The offset is given in bytes rather
--   than in elements of type <tt>a</tt>.
readUnalignedByteArray :: (PrimMonad m, PrimUnaligned a, Bytes a) => MutableByteArray (PrimState m) -> Int -> m a

-- | Read a primitive value from the byte array, interpreting the first
--   byte as the least significant one. The offset is given in bytes rather
--   than in elements of type <tt>a</tt>.
indexUnalignedByteArray :: (PrimUnaligned a, Bytes a) => ByteArray -> Int -> a


-- | This is drop-in replacement for the read, write, and index functions
--   present in <tt>Data.Primitive.ByteArray</tt> and
--   <tt>Data.Primitive.ByteArray.Unaligned</tt>. While the functions from
--   those modules use native byte order, the functions in this one use
--   big-endian byte order (most significant byte first).
module Data.Primitive.ByteArray.BigEndian

-- | Write a primitive value to the byte array. The offset is given in
--   elements of type <tt>a</tt> rather than in bytes. The most significant
--   byte in the value comes first.
writeByteArray :: (PrimMonad m, Prim a, Bytes a) => MutableByteArray (PrimState m) -> Int -> a -> m ()

-- | Read a primitive value from the byte array, interpreting the first
--   byte as the most significant one. The offset is given in elements of
--   type <tt>a</tt> rather than in bytes.
readByteArray :: (PrimMonad m, Prim a, Bytes a) => MutableByteArray (PrimState m) -> Int -> m a

-- | Read a primitive value from the byte array, interpreting the first
--   byte as the most significant one. The offset is given in elements of
--   type <tt>a</tt> rather than in bytes.
indexByteArray :: (Prim a, Bytes a) => ByteArray -> Int -> a

-- | Write a primitive value to the byte array. The offset is given in
--   bytes rather than in elements of type <tt>a</tt>. The most significant
--   byte in the value comes first.
writeUnalignedByteArray :: (PrimMonad m, PrimUnaligned a, Bytes a) => MutableByteArray (PrimState m) -> Int -> a -> m ()

-- | Read a primitive value from the byte array, interpreting the first
--   byte as the most significant one. The offset is given in bytes rather
--   than in elements of type <tt>a</tt>.
readUnalignedByteArray :: (PrimMonad m, PrimUnaligned a, Bytes a) => MutableByteArray (PrimState m) -> Int -> m a

-- | Read a primitive value from the byte array, interpreting the first
--   byte as the most significant one. The offset is given in bytes rather
--   than in elements of type <tt>a</tt>.
indexUnalignedByteArray :: (PrimUnaligned a, Bytes a) => ByteArray -> Int -> a