ram-0.19.0: 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
  - length :: ba -> Int
  - withByteArray :: ba -> (Ptr p -> IO a) -> IO a
  - copyByteArrayToPtr :: ba -> Ptr p -> IO ()
- class (Eq ba, Ord ba, Monoid ba, ByteArrayAccess ba) => ByteArray ba where
  - allocRet :: Int -> (Ptr p -> IO a) -> IO (a, ba)
- data Bytes
- data ScrubbedBytes
- data MemView = MemView !(Ptr Word8) !Int
- 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
- index :: ByteArrayAccess a => a -> Int -> Word8
- concat :: (ByteArrayAccess bin, ByteArray bout) => [bin] -> bout
- empty :: ByteArray a => a
- uncons :: ByteArray a => a -> Maybe (Word8, a)
- null :: ByteArrayAccess a => a -> Bool
- replicate :: ByteArray ba => Int -> Word8 -> ba
- take :: ByteArray bs => Int -> bs -> bs
- drop :: ByteArray bs => Int -> bs -> bs
- splitAt :: ByteArray bs => Int -> bs -> (bs, bs)
- span :: ByteArray bs => (Word8 -> Bool) -> bs -> (bs, bs)
- reverse :: ByteArray bs => bs -> bs
- any :: ByteArrayAccess ba => (Word8 -> Bool) -> ba -> Bool
- all :: ByteArrayAccess ba => (Word8 -> Bool) -> ba -> Bool
- xor :: (ByteArrayAccess a, ByteArrayAccess b, ByteArray c) => a -> b -> c
- singleton :: ByteArray a => Word8 -> a
- cons :: ByteArray a => Word8 -> a -> a
- append :: ByteArray bs => bs -> bs -> bs
- unsafeCreate :: ByteArray a => Int -> (Ptr p -> IO ()) -> a
- create :: ByteArray ba => Int -> (Ptr p -> IO ()) -> IO ba
- pack :: ByteArray a => [Word8] -> a
- unpack :: ByteArrayAccess a => a -> [Word8]
- snoc :: ByteArray a => a -> Word8 -> a
- copy :: (ByteArrayAccess bs1, ByteArray bs2) => bs1 -> (Ptr p -> IO ()) -> IO bs2
- eq :: (ByteArrayAccess bs1, ByteArrayAccess bs2) => bs1 -> bs2 -> Bool
- alloc :: ByteArray ba => Int -> (Ptr p -> IO ()) -> IO ba
- allocAndFreeze :: ByteArray a => Int -> (Ptr p -> IO ()) -> a
- copyRet :: (ByteArrayAccess bs1, ByteArray bs2) => bs1 -> (Ptr p -> IO a) -> IO (a, bs2)
- copyAndFreeze :: (ByteArrayAccess bs1, ByteArray bs2) => bs1 -> (Ptr p -> IO ()) -> bs2
- zero :: ByteArray ba => Int -> ba
- convert :: (ByteArrayAccess bin, ByteArray bout) => bin -> bout
- constEq :: (ByteArrayAccess bs1, ByteArrayAccess bs2) => bs1 -> bs2 -> Bool

# ByteArray Classes

class ByteArrayAccess ba where Source #

Class to Access size properties and data of a ByteArray

Minimal complete definition

length, withByteArray

Methods

length :: ba -> Int Source #

Return the length in bytes of a bytearray

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

Allow to use using a pointer

copyByteArrayToPtr :: ba -> Ptr p -> IO () Source #

Copy the data of a bytearray to a ptr

#### Instances

Instances details

ByteArrayAccess Bytes Source # |
Instance details Defined in Data.ByteArray.Bytes Methods length :: Bytes -> Int Source # withByteArray :: Bytes -> (Ptr p -> IO a) -> IO a Source # copyByteArrayToPtr :: Bytes -> Ptr p -> IO () Source #
ByteArrayAccess MemView Source # |
Instance details Defined in Data.ByteArray.MemView Methods length :: MemView -> Int Source # withByteArray :: MemView -> (Ptr p -> IO a) -> IO a Source # copyByteArrayToPtr :: MemView -> Ptr p -> IO () Source #
ByteArrayAccess ScrubbedBytes Source # |
Instance details Defined in Data.ByteArray.ScrubbedBytes Methods length :: ScrubbedBytes -> Int Source # withByteArray :: ScrubbedBytes -> (Ptr p -> IO a) -> IO a Source # copyByteArrayToPtr :: ScrubbedBytes -> Ptr p -> IO () Source #
ByteArrayAccess bytes => ByteArrayAccess (View bytes) Source # |
Instance details Defined in Data.ByteArray.View Methods length :: View bytes -> Int Source # withByteArray :: View bytes -> (Ptr p -> IO a) -> IO a Source # copyByteArrayToPtr :: View bytes -> Ptr p -> IO () Source #
(ByteArrayAccess ba, KnownNat n) => ByteArrayAccess (SizedByteArray n ba) Source # |
Instance details Defined in Data.ByteArray.Sized Methods length :: SizedByteArray n ba -> Int Source # withByteArray :: SizedByteArray n ba -> (Ptr p -> IO a) -> IO a Source # copyByteArrayToPtr :: SizedByteArray n ba -> Ptr p -> IO () Source #

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

Class to allocate new ByteArray of specific size

Methods

allocRet Source #

Arguments

:: Int | number of bytes to allocate. i.e. might not match the size of the given type `ba`.
-> (Ptr p -> IO a) |
-> IO (a, ba) |

allocate `n` bytes and perform the given operation

#### Instances

Instances details

ByteArray Bytes Source # |
Instance details Defined in Data.ByteArray.Bytes Methods allocRet :: Int -> (Ptr p -> IO a) -> IO (a, Bytes) Source #
ByteArray ScrubbedBytes Source # |
Instance details Defined in Data.ByteArray.ScrubbedBytes Methods allocRet :: Int -> (Ptr p -> IO a) -> IO (a, ScrubbedBytes) Source #

# ByteArray built-in types

data Bytes Source #

Simplest Byte Array

#### Instances

Instances details

Monoid Bytes Source # |
Instance details Defined in Data.ByteArray.Bytes Methods mempty :: Bytes Source # mappend :: Bytes -> Bytes -> Bytes Source # mconcat :: [Bytes] -> Bytes Source #
Semigroup Bytes Source # |
Instance details Defined in Data.ByteArray.Bytes Methods (<>) :: Bytes -> Bytes -> Bytes Source # sconcat :: NonEmpty Bytes -> Bytes Source # stimes :: Integral b => b -> Bytes -> Bytes Source #
Show Bytes Source # |
Instance details Defined in Data.ByteArray.Bytes Methods showsPrec :: Int -> Bytes -> ShowS Source # show :: Bytes -> String Source # showList :: [Bytes] -> ShowS Source #
Eq Bytes Source # |
Instance details Defined in Data.ByteArray.Bytes Methods (==) :: Bytes -> Bytes -> Bool Source # (/=) :: Bytes -> Bytes -> Bool Source #
Ord Bytes Source # |
Instance details Defined in Data.ByteArray.Bytes Methods compare :: Bytes -> Bytes -> Ordering Source # (<) :: Bytes -> Bytes -> Bool Source # (<=) :: Bytes -> Bytes -> Bool Source # (>) :: Bytes -> Bytes -> Bool Source # (>=) :: Bytes -> Bytes -> Bool Source # max :: Bytes -> Bytes -> Bytes Source # min :: Bytes -> Bytes -> Bytes Source #
ByteArray Bytes Source # |
Instance details Defined in Data.ByteArray.Bytes Methods allocRet :: Int -> (Ptr p -> IO a) -> IO (a, Bytes) Source #
ByteArrayAccess Bytes Source # |
Instance details Defined in Data.ByteArray.Bytes Methods length :: Bytes -> Int Source # withByteArray :: Bytes -> (Ptr p -> IO a) -> IO a Source # copyByteArrayToPtr :: Bytes -> Ptr p -> IO () Source #

data ScrubbedBytes Source #

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

Instances details

Monoid ScrubbedBytes Source # |
Instance details Defined in Data.ByteArray.ScrubbedBytes Methods mempty :: ScrubbedBytes Source # mappend :: ScrubbedBytes -> ScrubbedBytes -> ScrubbedBytes Source # mconcat :: [ScrubbedBytes] -> ScrubbedBytes Source #
Semigroup ScrubbedBytes Source # |
Instance details Defined in Data.ByteArray.ScrubbedBytes Methods (<>) :: ScrubbedBytes -> ScrubbedBytes -> ScrubbedBytes Source # sconcat :: NonEmpty ScrubbedBytes -> ScrubbedBytes Source # stimes :: Integral b => b -> ScrubbedBytes -> ScrubbedBytes Source #
IsString ScrubbedBytes Source # |
Instance details Defined in Data.ByteArray.ScrubbedBytes Methods fromString :: String -> ScrubbedBytes Source #
Show ScrubbedBytes Source # |
Instance details Defined in Data.ByteArray.ScrubbedBytes Methods showsPrec :: Int -> ScrubbedBytes -> ShowS Source # show :: ScrubbedBytes -> String Source # showList :: [ScrubbedBytes] -> ShowS Source #
Eq ScrubbedBytes Source # |
Instance details Defined in Data.ByteArray.ScrubbedBytes Methods (==) :: ScrubbedBytes -> ScrubbedBytes -> Bool Source # (/=) :: ScrubbedBytes -> ScrubbedBytes -> Bool Source #
Ord ScrubbedBytes Source # |

Instance details

Defined in Data.ByteArray.ScrubbedBytes

Methods

compare :: ScrubbedBytes -> ScrubbedBytes -> Ordering Source #

(<) :: ScrubbedBytes -> ScrubbedBytes -> Bool Source #

(<=) :: ScrubbedBytes -> ScrubbedBytes -> Bool Source #

(>) :: ScrubbedBytes -> ScrubbedBytes -> Bool Source #

(>=) :: ScrubbedBytes -> ScrubbedBytes -> Bool Source #

max :: ScrubbedBytes -> ScrubbedBytes -> ScrubbedBytes Source #

min :: ScrubbedBytes -> ScrubbedBytes -> ScrubbedBytes Source #

ByteArray ScrubbedBytes Source # |
Instance details Defined in Data.ByteArray.ScrubbedBytes Methods allocRet :: Int -> (Ptr p -> IO a) -> IO (a, ScrubbedBytes) Source #
ByteArrayAccess ScrubbedBytes Source # |
Instance details Defined in Data.ByteArray.ScrubbedBytes Methods length :: ScrubbedBytes -> Int Source # withByteArray :: ScrubbedBytes -> (Ptr p -> IO a) -> IO a Source # copyByteArrayToPtr :: ScrubbedBytes -> Ptr p -> IO () Source #

data MemView Source #

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

Instances details

Show MemView Source # |
Instance details Defined in Data.ByteArray.MemView Methods showsPrec :: Int -> MemView -> ShowS Source # show :: MemView -> String Source # showList :: [MemView] -> ShowS Source #
Eq MemView Source # |
Instance details Defined in Data.ByteArray.MemView Methods (==) :: MemView -> MemView -> Bool Source # (/=) :: MemView -> MemView -> Bool Source #
ByteArrayAccess MemView Source # |
Instance details Defined in Data.ByteArray.MemView Methods length :: MemView -> Int Source # withByteArray :: MemView -> (Ptr p -> IO a) -> IO a Source # copyByteArrayToPtr :: MemView -> Ptr p -> IO () Source #

data View bytes Source #

a view on a given bytes

Equality test in constant time

#### Instances

Instances details

ByteArrayAccess bytes => Show (View bytes) Source # |
Instance details Defined in Data.ByteArray.View Methods showsPrec :: Int -> View bytes -> ShowS Source # show :: View bytes -> String Source # showList :: [View bytes] -> ShowS Source #
ByteArrayAccess bytes => Eq (View bytes) Source # |
Instance details Defined in Data.ByteArray.View Methods (==) :: View bytes -> View bytes -> Bool Source # (/=) :: View bytes -> View bytes -> Bool Source #
ByteArrayAccess bytes => Ord (View bytes) Source # |

Instance details

Defined in Data.ByteArray.View

Methods

compare :: View bytes -> View bytes -> Ordering Source #

(<) :: View bytes -> View bytes -> Bool Source #

(<=) :: View bytes -> View bytes -> Bool Source #

(>) :: View bytes -> View bytes -> Bool Source #

(>=) :: View bytes -> View bytes -> Bool Source #

max :: View bytes -> View bytes -> View bytes Source #

min :: View bytes -> View bytes -> View bytes Source #

ByteArrayAccess bytes => ByteArrayAccess (View bytes) Source # |
Instance details Defined in Data.ByteArray.View Methods length :: View bytes -> Int Source # withByteArray :: View bytes -> (Ptr p -> IO a) -> IO a Source # copyByteArrayToPtr :: View bytes -> Ptr p -> IO () Source #

view Source #

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 Source #

Arguments

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

create a view from the given bytearray

dropView Source #

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

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

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

unsafe, no bound checking are done

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

Concatenate bytearray into a larger bytearray

empty :: ByteArray a => a Source #

Create an empty byte array

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

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

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

Check if a byte array is empty

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

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

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

Take the first `n` byte of a bytearray

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

drop the first `n` byte of a bytearray

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

Split a bytearray at a specific length in two bytearray

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

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

reverse :: ByteArray bs => bs -> bs Source #

Reverse a bytearray

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

Check if any element of a byte array satisfies a predicate

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

Check if all elements of a byte array satisfy a predicate

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

Create a xor of bytes between a and b.

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

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

Create a byte array from a single byte

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

prepend a single byte to a byte array

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

append one bytearray to the other

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

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

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

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

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

Pack a list of bytes into a bytearray

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

Un-pack a bytearray into a list of bytes

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

append a single byte to a byte array

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

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

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

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.

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

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

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

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

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

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 Source #

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

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

Create a bytearray of a specific size initialized to 0

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

Convert a bytearray to another type of bytearray

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

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.