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


-- | Network byte order utilities
--   
--   Peek and poke functions for network byte order.
@package network-byte-order
@version 0.1.7


-- | Peek and poke functions for network byte order.
module Network.ByteOrder

-- | A pointer to <a>Word8</a>.
type Buffer = Ptr Word8

-- | Offset from the current pointer.
type Offset = Int

-- | Size of a buffer.
type BufferSize = Int

-- | Buffer overrun exception.
data BufferOverrun

-- | The buffer size is not enough
BufferOverrun :: BufferOverrun

-- | <pre>
--   &gt;&gt;&gt; let buf = pack [1,2,3,4]
--   
--   &gt;&gt;&gt; unsafeWithByteString buf (poke8 0)
--   
--   &gt;&gt;&gt; unpack buf
--   [0,2,3,4]
--   </pre>
poke8 :: Word8 -> Buffer -> Offset -> IO ()

-- | <pre>
--   &gt;&gt;&gt; let buf = pack [1,2,3,4]
--   
--   &gt;&gt;&gt; unsafeWithByteString buf (poke16 (7*256 + 8))
--   
--   &gt;&gt;&gt; unpack buf
--   [7,8,3,4]
--   </pre>
poke16 :: Word16 -> Buffer -> Offset -> IO ()

-- | <pre>
--   &gt;&gt;&gt; let buf = pack [1,2,3,4]
--   
--   &gt;&gt;&gt; unsafeWithByteString buf (poke24 (6*65536 + 7*256 + 8))
--   
--   &gt;&gt;&gt; unpack buf
--   [6,7,8,4]
--   </pre>
poke24 :: Word32 -> Buffer -> Offset -> IO ()

-- | <pre>
--   &gt;&gt;&gt; let buf = pack [1,2,3,4]
--   
--   &gt;&gt;&gt; unsafeWithByteString buf (poke32 (6*65536 + 7*256 + 8))
--   
--   &gt;&gt;&gt; unpack buf
--   [0,6,7,8]
--   </pre>
poke32 :: Word32 -> Buffer -> Offset -> IO ()

-- | <pre>
--   &gt;&gt;&gt; let buf = pack [1,2,3,4,5,6,7,8]
--   
--   &gt;&gt;&gt; unsafeWithByteString buf (poke64 (6*65536 + 7*256 + 8))
--   
--   &gt;&gt;&gt; unpack buf
--   [0,0,0,0,0,6,7,8]
--   </pre>
poke64 :: Word64 -> Buffer -> Offset -> IO ()

-- | <pre>
--   &gt;&gt;&gt; let buf = pack [1,2,3,4]
--   
--   &gt;&gt;&gt; unsafeWithByteString buf peek8
--   1
--   </pre>
peek8 :: Buffer -> Offset -> IO Word8

-- | <pre>
--   &gt;&gt;&gt; let buf = pack [1,2,3,4]
--   
--   &gt;&gt;&gt; unsafeWithByteString buf peek16
--   258
--   </pre>
peek16 :: Buffer -> Offset -> IO Word16

-- | <pre>
--   &gt;&gt;&gt; let buf = pack [1,2,3,4]
--   
--   &gt;&gt;&gt; unsafeWithByteString buf peek24
--   66051
--   </pre>
peek24 :: Buffer -> Offset -> IO Word32

-- | <pre>
--   &gt;&gt;&gt; let buf = pack [1,2,3,4]
--   
--   &gt;&gt;&gt; unsafeWithByteString buf peek32
--   16909060
--   </pre>
peek32 :: Buffer -> Offset -> IO Word32

-- | <pre>
--   &gt;&gt;&gt; let buf = pack [1,2,3,4,5,6,7,8]
--   
--   &gt;&gt;&gt; unsafeWithByteString buf peek64
--   72623859790382856
--   </pre>
peek64 :: Buffer -> Offset -> IO Word64
peekByteString :: Buffer -> Int -> IO ByteString

-- | <pre>
--   &gt;&gt;&gt; let w = 5 :: Word8
--   
--   &gt;&gt;&gt; unpack $ bytestring8 w
--   [5]
--   </pre>
bytestring8 :: Word8 -> ByteString

-- | <pre>
--   &gt;&gt;&gt; let w = foldl' (\x y -&gt; x * 256 + y) 0 [5,6] :: Word16
--   
--   &gt;&gt;&gt; unpack $ bytestring16 w
--   [5,6]
--   </pre>
bytestring16 :: Word16 -> ByteString

-- | <pre>
--   &gt;&gt;&gt; let w = foldl' (\x y -&gt; x * 256 + y) 0 [5,6,7,8] :: Word32
--   
--   &gt;&gt;&gt; unpack $ bytestring32 w
--   [5,6,7,8]
--   </pre>
bytestring32 :: Word32 -> ByteString

-- | <pre>
--   &gt;&gt;&gt; let w = foldl' (\x y -&gt; x * 256 + y) 0 [1,2,3,4,5,6,7,8] :: Word64
--   
--   &gt;&gt;&gt; unpack $ bytestring64 w
--   [1,2,3,4,5,6,7,8]
--   </pre>
bytestring64 :: Word64 -> ByteString

-- | <pre>
--   &gt;&gt;&gt; let buf = pack [1,2,3,4,5,6,7,8]
--   
--   &gt;&gt;&gt; word8 buf
--   1
--   </pre>
word8 :: ByteString -> Word8

-- | <pre>
--   &gt;&gt;&gt; let buf = pack [1,2,3,4,5,6,7,8]
--   
--   &gt;&gt;&gt; word16 buf
--   258
--   </pre>
word16 :: ByteString -> Word16

-- | <pre>
--   &gt;&gt;&gt; let buf = pack [1,2,3,4,5,6,7,8]
--   
--   &gt;&gt;&gt; word32 buf
--   16909060
--   </pre>
word32 :: ByteString -> Word32

-- | <pre>
--   &gt;&gt;&gt; let buf = pack [1,2,3,4,5,6,7,8]
--   
--   &gt;&gt;&gt; word64 buf
--   72623859790382856
--   </pre>
word64 :: ByteString -> Word64

-- | Using <a>ByteString</a> as <a>Buffer</a> and call the <a>IO</a> action
--   of the second argument by passing the start point and the offset of
--   the <a>ByteString</a>. Note that if a <a>ByteString</a> is created
--   newly, its offset is 0.
unsafeWithByteString :: ByteString -> (Buffer -> Offset -> IO a) -> IO a

-- | Copying the bytestring to the buffer. This function returns the point
--   where the next copy should start.
--   
--   <pre>
--   &gt;&gt;&gt; let buf = "abc" :: ByteString
--   
--   &gt;&gt;&gt; unsafeWithByteString buf $ \ptr _ -&gt; Network.ByteOrder.copy ptr "ABC" &gt;&gt; return buf
--   "ABC"
--   </pre>
copy :: Buffer -> ByteString -> IO Buffer

-- | Converting the part of buffer to <a>ByteString</a> and executing the
--   action with it.
--   
--   <pre>
--   &gt;&gt;&gt; let buf = "abcdef" :: ByteString
--   
--   &gt;&gt;&gt; unsafeWithByteString buf $ \ptr _-&gt; bufferIO ptr 2 return
--   "ab"
--   </pre>
bufferIO :: Buffer -> Int -> (ByteString -> IO a) -> IO a
class Readable a

-- | Reading one byte as <a>Word8</a> and ff one byte.
read8 :: Readable a => a -> IO Word8

-- | Reading one byte as <a>Int</a> and ff one byte. If buffer overrun
--   occurs, -1 is returned.
readInt8 :: Readable a => a -> IO Int

-- | Fast forward the offset pointer. The boundary is not checked.
ff :: Readable a => a -> Offset -> IO ()

-- | Returning the length of the remaining
remainingSize :: Readable a => a -> IO Int

-- | Executing an action on the current offset pointer.
position :: Readable a => a -> IO Int
withCurrentOffSet :: Readable a => a -> (Buffer -> IO b) -> IO b

-- | Memorizing the current offset pointer.
save :: Readable a => a -> IO ()

-- | Getting how many bytes from the saved offset pinter.
savingSize :: Readable a => a -> IO Int

-- | Moving the offset point to the saved point.
goBack :: Readable a => a -> IO ()

-- | Read only buffer. To ensure that the internal is not modified, this is
--   an abstract data type.
data ReadBuffer

-- | Creating a read buffer with the given buffer.
newReadBuffer :: Buffer -> BufferSize -> IO ReadBuffer

-- | Converting <a>ByteString</a> to <a>ReadBuffer</a> and run the action
--   with it.
withReadBuffer :: ByteString -> (ReadBuffer -> IO a) -> IO a

-- | Reading two bytes as <a>Word16</a> and ff two bytes.
--   
--   <pre>
--   &gt;&gt;&gt; withReadBuffer "\x0\x1\x2\x3" $ read16
--   1
--   </pre>
read16 :: Readable a => a -> IO Word16

-- | Reading three bytes as <a>Word32</a> and ff three bytes.
--   
--   <pre>
--   &gt;&gt;&gt; withReadBuffer "\x0\x1\x2\x3" $ read24
--   258
--   </pre>
read24 :: Readable a => a -> IO Word32

-- | Reading four bytes as <a>Word32</a> and ff four bytes.
--   
--   <pre>
--   &gt;&gt;&gt; withReadBuffer "\x0\x1\x2\x3" $ read32
--   66051
--   </pre>
read32 :: Readable a => a -> IO Word32

-- | Reading four bytes as <a>Word64</a> and ff four bytes.
read64 :: Readable a => a -> IO Word64

-- | Extracting <a>ByteString</a> from the current offset. The contents is
--   copied, not shared. Its length is specified by the 2nd argument. If
--   the length is positive, the area after the current pointer is
--   extracted and FF the length finally. If the length is negative, the
--   area before the current pointer is extracted and does not FF.
--   
--   <pre>
--   &gt;&gt;&gt; withReadBuffer "abcdefg" $ \rbuf -&gt; ff rbuf 1 &gt;&gt; extractByteString rbuf 2
--   "bc"
--   </pre>
extractByteString :: Readable a => a -> Int -> IO ByteString

-- | Extracting <a>ShortByteString</a> from the current offset. The
--   contents is copied, not shared. Its length is specified by the 2nd
--   argument. If the length is positive, the area after the current
--   pointer is extracted and FF the length finally. If the length is
--   negative, the area before the current pointer is extracted and does
--   not FF.
--   
--   <pre>
--   &gt;&gt;&gt; withReadBuffer "abcdefg" $ \rbuf -&gt; ff rbuf 2 &gt;&gt; extractShortByteString rbuf 3
--   "cde"
--   </pre>
extractShortByteString :: Readable a => a -> Int -> IO ShortByteString

-- | Read and write buffer.
data WriteBuffer
WriteBuffer :: Buffer -> Buffer -> IORef Buffer -> IORef Buffer -> WriteBuffer
[start] :: WriteBuffer -> Buffer
[limit] :: WriteBuffer -> Buffer
[offset] :: WriteBuffer -> IORef Buffer
[oldoffset] :: WriteBuffer -> IORef Buffer

-- | Creating a write buffer with the given buffer.
newWriteBuffer :: Buffer -> BufferSize -> IO WriteBuffer

-- | Reseting a write buffer.
clearWriteBuffer :: WriteBuffer -> IO ()

-- | Allocate a temporary buffer and copy the result to <a>ByteString</a>.
withWriteBuffer :: BufferSize -> (WriteBuffer -> IO ()) -> IO ByteString

-- | Allocate a temporary buffer and copy the result to <a>ByteString</a>
--   with an additional value.
--   
--   <pre>
--   &gt;&gt;&gt; withWriteBuffer' 1 $ \wbuf -&gt; write8 wbuf 65 &gt;&gt; return 'a'
--   ("A",'a')
--   </pre>
withWriteBuffer' :: BufferSize -> (WriteBuffer -> IO a) -> IO (ByteString, a)

-- | Write one byte and ff one byte. If buffer overrun occurs,
--   <a>BufferOverrun</a> is thrown.
--   
--   <pre>
--   &gt;&gt;&gt; withWriteBuffer 1 $ \wbuf -&gt; write8 wbuf 65
--   "A"
--   </pre>
write8 :: WriteBuffer -> Word8 -> IO ()

-- | Write two bytes and ff one byte. If buffer overrun occurs,
--   <a>BufferOverrun</a> is thrown.
--   
--   <pre>
--   &gt;&gt;&gt; withWriteBuffer 2 $ \wbuf -&gt; write16 wbuf (65 * 256 + 66)
--   "AB"
--   </pre>
write16 :: WriteBuffer -> Word16 -> IO ()

-- | Write three bytes and ff one byte. If buffer overrun occurs,
--   <a>BufferOverrun</a> is thrown.
--   
--   <pre>
--   &gt;&gt;&gt; withWriteBuffer 3 $ \wbuf -&gt; write24 wbuf (65 * 256^(2 :: Int) + 66 * 256 + 67)
--   "ABC"
--   </pre>
write24 :: WriteBuffer -> Word32 -> IO ()

-- | Write four bytes and ff one byte. If buffer overrun occurs,
--   <a>BufferOverrun</a> is thrown.
--   
--   <pre>
--   &gt;&gt;&gt; withWriteBuffer 4 $ \wbuf -&gt; write32 wbuf (65 * 256^(3 :: Int) + 66 * 256^(2 :: Int) + 67 * 256 + 68)
--   "ABCD"
--   </pre>
write32 :: WriteBuffer -> Word32 -> IO ()

-- | Write four bytes and ff one byte. If buffer overrun occurs,
--   <a>BufferOverrun</a> is thrown.
write64 :: WriteBuffer -> Word64 -> IO ()

-- | Copy the content of <a>ByteString</a> and ff its length. If buffer
--   overrun occurs, <a>BufferOverrun</a> is thrown.
--   
--   <pre>
--   &gt;&gt;&gt; withWriteBuffer 3 $ \wbuf -&gt; copyByteString wbuf "ABC"
--   "ABC"
--   </pre>
copyByteString :: WriteBuffer -> ByteString -> IO ()

-- | Copy the content of <a>ShortByteString</a> and ff its length. If
--   buffer overrun occurs, <a>BufferOverrun</a> is thrown.
--   
--   <pre>
--   &gt;&gt;&gt; withWriteBuffer 5 $ \wbuf -&gt; copyShortByteString wbuf "ABCEF"
--   "ABCEF"
--   </pre>
copyShortByteString :: WriteBuffer -> ShortByteString -> IO ()

-- | Shifting the N-bytes area just before the current pointer (the 3rd
--   argument). If the second argument is positive, shift it to right. If
--   it is negative, shift it to left. <a>offset</a> moves as if it is
--   sticky to the area.
--   
--   <pre>
--   &gt;&gt;&gt; withWriteBuffer 16 $ \wbuf -&gt; copyByteString wbuf "ABCD" &gt;&gt; shiftLastN wbuf 1 3
--   "ABBCD"
--   
--   &gt;&gt;&gt; withWriteBuffer 16 $ \wbuf -&gt; copyByteString wbuf "ABCD" &gt;&gt; shiftLastN wbuf 2 3
--   "ABCBCD"
--   
--   &gt;&gt;&gt; withWriteBuffer 16 $ \wbuf -&gt; copyByteString wbuf "ABCDE" &gt;&gt; shiftLastN wbuf (-2) 3 &gt;&gt; ff wbuf 2
--   "CDEDE"
--   </pre>
shiftLastN :: WriteBuffer -> Int -> Int -> IO ()

-- | Copy the area from <a>start</a> to the current pointer to
--   <a>ByteString</a>.
toByteString :: WriteBuffer -> IO ByteString

-- | Copy the area from <a>start</a> to the current pointer to
--   <a>ShortByteString</a>.
toShortByteString :: WriteBuffer -> IO ShortByteString

-- | Getting the offset pointer.
currentOffset :: WriteBuffer -> IO Buffer

-- | 8-bit unsigned integer type
data () => Word8

-- | 16-bit unsigned integer type
data () => Word16

-- | 32-bit unsigned integer type
data () => Word32

-- | 64-bit unsigned integer type
data () => Word64

-- | A space-efficient representation of a <a>Word8</a> vector, supporting
--   many efficient operations.
--   
--   A <a>ByteString</a> contains 8-bit bytes, or by using the operations
--   from <a>Data.ByteString.Char8</a> it can be interpreted as containing
--   8-bit characters.
data () => ByteString
instance GHC.Show.Show Network.ByteOrder.BufferOverrun
instance GHC.Classes.Eq Network.ByteOrder.BufferOverrun
instance Network.ByteOrder.Readable Network.ByteOrder.WriteBuffer
instance GHC.Exception.Type.Exception Network.ByteOrder.BufferOverrun
instance Network.ByteOrder.Readable Network.ByteOrder.ReadBuffer
