-- 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.1.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.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