-- 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.0.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 (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, Foreign.Storable.Storable a, System.ByteOrder.Class.Bytes a) => Foreign.Storable.Storable (System.ByteOrder.Fixed b a)