memory-0.13: memory and related abstraction stuff

License | BSD-style
Maintainer | Vincent Hanquez <vincent@snarc.org>
Stability | stable
Portability | Good
Safe Haskell | None
Language | Haskell2010

Data.ByteArray

Contents

- ByteArray Classes
- ByteArray built-in types
- ByteArray methods

Description

Simple and efficient byte array types

This module should be imported qualified.

Synopsis

- class ByteArrayAccess ba where
- class (Eq ba, Ord ba, Monoid ba, ByteArrayAccess ba) => ByteArray ba where
- data Bytes
- data ScrubbedBytes
- data MemView = MemView !(Ptr Word8) !Int
- memViewPlus :: MemView -> Int -> MemView
- data View bytes
- view :: ByteArrayAccess bytes => bytes -> Int -> Int -> View bytes
- takeView :: ByteArrayAccess bytes => bytes -> Int -> View bytes
- dropView :: ByteArrayAccess bytes => bytes -> Int -> View bytes
- alloc :: ByteArray ba => Int -> (Ptr p -> IO ()) -> IO ba
- allocAndFreeze :: ByteArray a => Int -> (Ptr p -> IO ()) -> a
- create :: ByteArray ba => Int -> (Ptr p -> IO ()) -> IO ba
- unsafeCreate :: ByteArray a => Int -> (Ptr p -> IO ()) -> a
- pack :: ByteArray a => [Word8] -> a
- unpack :: ByteArrayAccess a => a -> [Word8]
- uncons :: ByteArray a => a -> Maybe (Word8, a)
- empty :: ByteArray a => a
- singleton :: ByteArray a => Word8 -> a
- cons :: ByteArray a => Word8 -> a -> a
- snoc :: ByteArray a => a -> Word8 -> a
- null :: ByteArrayAccess a => a -> Bool
- replicate :: ByteArray ba => Int -> Word8 -> ba
- zero :: ByteArray ba => Int -> ba
- copy :: (ByteArrayAccess bs1, ByteArray bs2) => bs1 -> (Ptr p -> IO ()) -> IO bs2
- take :: ByteArray bs => Int -> bs -> bs
- drop :: ByteArray bs => Int -> bs -> bs
- span :: ByteArray bs => (Word8 -> Bool) -> bs -> (bs, bs)
- convert :: (ByteArrayAccess bin, ByteArray bout) => bin -> bout
- copyRet :: (ByteArrayAccess bs1, ByteArray bs2) => bs1 -> (Ptr p -> IO a) -> IO (a, bs2)
- copyAndFreeze :: (ByteArrayAccess bs1, ByteArray bs2) => bs1 -> (Ptr p -> IO ()) -> bs2
- splitAt :: ByteArray bs => Int -> bs -> (bs, bs)
- xor :: (ByteArrayAccess a, ByteArrayAccess b, ByteArray c) => a -> b -> c
- index :: ByteArrayAccess a => a -> Int -> Word8
- eq :: (ByteArrayAccess bs1, ByteArrayAccess bs2) => bs1 -> bs2 -> Bool
- constEq :: (ByteArrayAccess bs1, ByteArrayAccess bs2) => bs1 -> bs2 -> Bool
- any :: ByteArrayAccess ba => (Word8 -> Bool) -> ba -> Bool
- all :: ByteArrayAccess ba => (Word8 -> Bool) -> ba -> Bool
- append :: ByteArray bs => bs -> bs -> bs
- concat :: (ByteArrayAccess bin, ByteArray bout) => [bin] -> bout

# ByteArray Classes

class ByteArrayAccess ba where #

Class to Access size properties and data of a ByteArray

Minimal complete definition

length, withByteArray

Methods

length :: ba -> Int #

Return the length in bytes of a bytearray

withByteArray :: ba -> (Ptr p -> IO a) -> IO a #

Allow to use using a pointer

Instances

ByteArrayAccess ByteString # |
Methods length :: ByteString -> Int # withByteArray :: ByteString -> (Ptr p -> IO a) -> IO a #
ByteArrayAccess Bytes # |
Methods length :: Bytes -> Int # withByteArray :: Bytes -> (Ptr p -> IO a) -> IO a #
ByteArrayAccess ScrubbedBytes # |
Methods length :: ScrubbedBytes -> Int # withByteArray :: ScrubbedBytes -> (Ptr p -> IO a) -> IO a #
ByteArrayAccess MemView # |
Methods length :: MemView -> Int # withByteArray :: MemView -> (Ptr p -> IO a) -> IO a #
ByteArrayAccess bytes => ByteArrayAccess (View bytes) # |
Methods length :: View bytes -> Int # withByteArray :: View bytes -> (Ptr p -> IO a) -> IO a #

class (Eq ba, Ord ba, Monoid ba, ByteArrayAccess ba) => ByteArray ba where #

Class to allocate new ByteArray of specific size

Minimal complete definition

allocRet

Methods

allocRet :: Int -> (Ptr p -> IO a) -> IO (a, ba) #

Instances

ByteArray ByteString # |
Methods allocRet :: Int -> (Ptr p -> IO a) -> IO (a, ByteString) #
ByteArray Bytes # |
Methods allocRet :: Int -> (Ptr p -> IO a) -> IO (a, Bytes) #
ByteArray ScrubbedBytes # |
Methods allocRet :: Int -> (Ptr p -> IO a) -> IO (a, ScrubbedBytes) #

# ByteArray built-in types

data Bytes #

Simplest Byte Array

Instances

Eq Bytes # |
Methods (==) :: Bytes -> Bytes -> Bool # (/=) :: Bytes -> Bytes -> Bool #
Ord Bytes # |
Methods compare :: Bytes -> Bytes -> Ordering # (<) :: Bytes -> Bytes -> Bool # (<=) :: Bytes -> Bytes -> Bool # (>) :: Bytes -> Bytes -> Bool # (>=) :: Bytes -> Bytes -> Bool # max :: Bytes -> Bytes -> Bytes # min :: Bytes -> Bytes -> Bytes #
Show Bytes # |
Methods showsPrec :: Int -> Bytes -> ShowS # show :: Bytes -> String # showList :: [Bytes] -> ShowS #
Monoid Bytes # |
Methods mempty :: Bytes # mappend :: Bytes -> Bytes -> Bytes # mconcat :: [Bytes] -> Bytes #
NFData Bytes # |
Methods rnf :: Bytes -> () #
ByteArray Bytes # |
Methods allocRet :: Int -> (Ptr p -> IO a) -> IO (a, Bytes) #
ByteArrayAccess Bytes # |
Methods length :: Bytes -> Int # withByteArray :: Bytes -> (Ptr p -> IO a) -> IO a #

data ScrubbedBytes #

ScrubbedBytes is a memory chunk which have the properties of:

- Being scrubbed after its goes out of scope.
- A Show instance that doesn't actually show any content
- A Eq instance that is constant time

Instances

Eq ScrubbedBytes # |
Methods (==) :: ScrubbedBytes -> ScrubbedBytes -> Bool # (/=) :: ScrubbedBytes -> ScrubbedBytes -> Bool #
Ord ScrubbedBytes # |
Methods compare :: ScrubbedBytes -> ScrubbedBytes -> Ordering # (<) :: ScrubbedBytes -> ScrubbedBytes -> Bool # (<=) :: ScrubbedBytes -> ScrubbedBytes -> Bool # (>) :: ScrubbedBytes -> ScrubbedBytes -> Bool # (>=) :: ScrubbedBytes -> ScrubbedBytes -> Bool # max :: ScrubbedBytes -> ScrubbedBytes -> ScrubbedBytes # min :: ScrubbedBytes -> ScrubbedBytes -> ScrubbedBytes #
Show ScrubbedBytes # |
Methods showsPrec :: Int -> ScrubbedBytes -> ShowS # show :: ScrubbedBytes -> String # showList :: [ScrubbedBytes] -> ShowS #
Monoid ScrubbedBytes # |
Methods mempty :: ScrubbedBytes # mappend :: ScrubbedBytes -> ScrubbedBytes -> ScrubbedBytes # mconcat :: [ScrubbedBytes] -> ScrubbedBytes #
NFData ScrubbedBytes # |
Methods rnf :: ScrubbedBytes -> () #
ByteArray ScrubbedBytes # |
Methods allocRet :: Int -> (Ptr p -> IO a) -> IO (a, ScrubbedBytes) #
ByteArrayAccess ScrubbedBytes # |
Methods length :: ScrubbedBytes -> Int # withByteArray :: ScrubbedBytes -> (Ptr p -> IO a) -> IO a #

data MemView #

A simple abstraction to a piece of memory.

Do beware that garbage collection related to piece of memory could be triggered before this is used.

Only use with the appropriate handler has been used (e.g. withForeignPtr on ForeignPtr)

Constructors

MemView !(Ptr Word8) !Int |

Instances

Eq MemView # |
Methods (==) :: MemView -> MemView -> Bool # (/=) :: MemView -> MemView -> Bool #
Show MemView # |
Methods showsPrec :: Int -> MemView -> ShowS # show :: MemView -> String # showList :: [MemView] -> ShowS #
ByteArrayAccess MemView # |
Methods length :: MemView -> Int # withByteArray :: MemView -> (Ptr p -> IO a) -> IO a #

memViewPlus :: MemView -> Int -> MemView #

Increase the memory view while reducing the size of the window

this is useful as an abtraction to represent the current offset in a buffer, and the remaining bytes left.

data View bytes #

a view on a given bytes

Equality test in constant time

Instances

ByteArrayAccess bytes => Eq (View bytes) # |
Methods (==) :: View bytes -> View bytes -> Bool # (/=) :: View bytes -> View bytes -> Bool #
ByteArrayAccess bytes => Ord (View bytes) # |
Methods compare :: View bytes -> View bytes -> Ordering # (<) :: View bytes -> View bytes -> Bool # (<=) :: View bytes -> View bytes -> Bool # (>) :: View bytes -> View bytes -> Bool # (>=) :: View bytes -> View bytes -> Bool # max :: View bytes -> View bytes -> View bytes # min :: View bytes -> View bytes -> View bytes #
ByteArrayAccess bytes => Show (View bytes) # |
Methods showsPrec :: Int -> View bytes -> ShowS # show :: View bytes -> String # showList :: [View bytes] -> ShowS #
ByteArrayAccess bytes => ByteArrayAccess (View bytes) # |
Methods length :: View bytes -> Int # withByteArray :: View bytes -> (Ptr p -> IO a) -> IO a #

view #

Arguments

:: ByteArrayAccess bytes |
=> bytes | the byte array we put a view on
-> Int | the offset to start the byte array on
-> Int | the size of the view
-> View bytes |

create a view on a given bytearray

This function update the offset and the size in order to guarantee:

- offset >= 0
- size >= 0
- offset < length
- size =< length - offset

takeView #

Arguments

:: ByteArrayAccess bytes |
=> bytes | byte aray
-> Int | size of the view
-> View bytes |

create a view from the given bytearray

dropView #

Arguments

:: ByteArrayAccess bytes |
=> bytes | byte array
-> Int | the number of bytes do dropped before creating the view
-> View bytes |

create a view from the given byte array starting after having dropped the fist n bytes

# ByteArray methods

alloc :: ByteArray ba => Int -> (Ptr p -> IO ()) -> IO ba #

Allocate a new bytearray of specific size, and run the initializer on this memory

allocAndFreeze :: ByteArray a => Int -> (Ptr p -> IO ()) -> a #

similar to `alloc` but hide the allocation and initializer in a pure context

create :: ByteArray ba => Int -> (Ptr p -> IO ()) -> IO ba #

Allocate a new bytearray of specific size, and run the initializer on this memory

unsafeCreate :: ByteArray a => Int -> (Ptr p -> IO ()) -> a #

similar to `create` but hide the allocation and initializer in a pure context

pack :: ByteArray a => [Word8] -> a #

Pack a list of bytes into a bytearray

unpack :: ByteArrayAccess a => a -> [Word8] #

Un-pack a bytearray into a list of bytes

uncons :: ByteArray a => a -> Maybe (Word8, a) #

returns the first byte, and the remaining bytearray if the bytearray is not null

empty :: ByteArray a => a #

Create an empty byte array

singleton :: ByteArray a => Word8 -> a #

Create a byte array from a single byte

cons :: ByteArray a => Word8 -> a -> a #

prepend a single byte to a byte array

snoc :: ByteArray a => a -> Word8 -> a #

append a single byte to a byte array

null :: ByteArrayAccess a => a -> Bool #

Check if a byte array is empty

replicate :: ByteArray ba => Int -> Word8 -> ba #

Create a bytearray of a specific size containing a repeated byte value

zero :: ByteArray ba => Int -> ba #

Create a bytearray of a specific size initialized to 0

copy :: (ByteArrayAccess bs1, ByteArray bs2) => bs1 -> (Ptr p -> IO ()) -> IO bs2 #

Duplicate a bytearray into another bytearray, and run an initializer on it

take :: ByteArray bs => Int -> bs -> bs #

Take the first `n` byte of a bytearray

drop :: ByteArray bs => Int -> bs -> bs #

drop the first `n` byte of a bytearray

span :: ByteArray bs => (Word8 -> Bool) -> bs -> (bs, bs) #

Split a bytearray at the point where `pred` becomes invalid

convert :: (ByteArrayAccess bin, ByteArray bout) => bin -> bout #

Convert a bytearray to another type of bytearray

copyRet :: (ByteArrayAccess bs1, ByteArray bs2) => bs1 -> (Ptr p -> IO a) -> IO (a, bs2) #

Similar to `copy` but also provide a way to return a value from the initializer

copyAndFreeze :: (ByteArrayAccess bs1, ByteArray bs2) => bs1 -> (Ptr p -> IO ()) -> bs2 #

Similiar to `copy` but expect the resulting bytearray in a pure context

splitAt :: ByteArray bs => Int -> bs -> (bs, bs) #

Split a bytearray at a specific length in two bytearray

xor :: (ByteArrayAccess a, ByteArrayAccess b, ByteArray c) => a -> b -> c #

Create a xor of bytes between a and b.

the returns byte array is the size of the smallest input.

index :: ByteArrayAccess a => a -> Int -> Word8 #

return a specific byte indexed by a number from 0 in a bytearray

unsafe, no bound checking are done

eq :: (ByteArrayAccess bs1, ByteArrayAccess bs2) => bs1 -> bs2 -> Bool #

Check if two bytearray are equals

This is not constant time, as soon some byte differs the function will returns. use `constEq` in sensitive context where timing matters.

constEq :: (ByteArrayAccess bs1, ByteArrayAccess bs2) => bs1 -> bs2 -> Bool #

A constant time equality test for 2 ByteArrayAccess values.

If values are of 2 different sizes, the function will abort early without comparing any bytes.

compared to == , this function will go over all the bytes present before yielding a result even when knowing the overall result early in the processing.

any :: ByteArrayAccess ba => (Word8 -> Bool) -> ba -> Bool #

Check if any element of a byte array satisfies a predicate

all :: ByteArrayAccess ba => (Word8 -> Bool) -> ba -> Bool #

Check if all elements of a byte array satisfy a predicate

append :: ByteArray bs => bs -> bs -> bs #

append one bytearray to the other

concat :: (ByteArrayAccess bin, ByteArray bout) => [bin] -> bout #

Concatenate bytearray into a larger bytearray