Data.Bytes.Chunks

byteslice-0.2.14.0: Slicing managed and unmanaged memory

Safe Haskell | None
Language | Haskell2010

Data.Bytes.Chunks

Contents

- Types
- Properties
- Manipulate
- Folds
- Splitting
- Hashing
- Create
- Copy to buffer
- I/O with Handles

Description

Chunks of bytes. This is useful as a target for a builder or as a way to read a large amount of whose size is unknown in advance. Structurally, this type is similar to `Data.ByteString.Lazy.ByteString`. However, the type in this module is strict in its spine. Additionally, none of the `Handle` functions perform lazy I/O.

Synopsis

- data Chunks
  - = ChunksCons !Bytes !Chunks
  - | ChunksNil
- length :: Chunks -> Int
- null :: Chunks -> Bool
- cons :: Bytes -> Chunks -> Chunks
- concat :: Chunks -> Bytes
- concatPinned :: Chunks -> Bytes
- concatU :: Chunks -> ByteArray
- concatPinnedU :: Chunks -> ByteArray
- concatByteString :: Chunks -> ByteString
- reverse :: Chunks -> Chunks
- reverseOnto :: Chunks -> Chunks -> Chunks
- replicate :: Bytes -> Int -> Chunks
- replicateByte :: Word8 -> Int -> Chunks
- foldl' :: (a -> Word8 -> a) -> a -> Chunks -> a
- split :: Word8 -> Chunks -> [Bytes]
- fnv1a32 :: Chunks -> Word32
- fnv1a64 :: Chunks -> Word64
- fromBytes :: Bytes -> Chunks
- fromByteArray :: ByteArray -> Chunks
- unsafeCopy :: MutableByteArray s -> Int -> Chunks -> ST s Int
- hGetContents :: Handle -> IO Chunks
- readFile :: FilePath -> IO Chunks
- hPut :: Handle -> Chunks -> IO ()
- writeFile :: FilePath -> Chunks -> IO ()

# Types

data Chunks #

A cons-list of byte sequences.

Constructors

ChunksCons !Bytes !Chunks |
ChunksNil |

#### Instances

Instances details

Monoid Chunks # |
Instance details Defined in Data.Bytes.Chunks Methods mempty :: Chunks # mappend :: Chunks -> Chunks -> Chunks # mconcat :: [Chunks] -> Chunks #
Semigroup Chunks # |
Instance details Defined in Data.Bytes.Chunks Methods (<>) :: Chunks -> Chunks -> Chunks # sconcat :: NonEmpty Chunks -> Chunks # stimes :: Integral b => b -> Chunks -> Chunks #
Show Chunks # |
Instance details Defined in Data.Bytes.Chunks Methods showsPrec :: Int -> Chunks -> ShowS # show :: Chunks -> String # showList :: [Chunks] -> ShowS #
Eq Chunks # | This uses `concat` to form an equivalence class.
Instance details Defined in Data.Bytes.Chunks Methods (==) :: Chunks -> Chunks -> Bool # (/=) :: Chunks -> Chunks -> Bool #

# Properties

length :: Chunks -> Int #

The total number of bytes in all the chunks.

null :: Chunks -> Bool #

Are there any bytes in the chunked byte sequences?

# Manipulate

cons :: Bytes -> Chunks -> Chunks #

Add a byte sequence to the beginning.

concat :: Chunks -> Bytes #

Concatenate chunks into a single contiguous byte sequence.

concatPinned :: Chunks -> Bytes #

Variant of `concat` that ensure that the resulting byte sequence is pinned memory.

concatU :: Chunks -> ByteArray #

Variant of `concat` that returns an unsliced byte sequence.

concatPinnedU :: Chunks -> ByteArray #

Variant of `concatPinned` that returns an unsliced pinned byte sequence.

concatByteString :: Chunks -> ByteString #

Concatenate chunks into a strict bytestring.

reverse :: Chunks -> Chunks #

Reverse chunks but not the bytes within each chunk.

reverseOnto :: Chunks -> Chunks -> Chunks #

Variant of `reverse` that allows the caller to provide an initial list of chunks that the reversed chunks will be pushed onto.

replicate #

Arguments

:: Bytes |
-> Int | Number of times to repeat the sequence.
-> Chunks |

Repeat the byte sequence over and over. Returns empty chunks when given a negative repetition count.

replicateByte #

Arguments

:: Word8 |
-> Int | Number of times to replicate the byte
-> Chunks |

Repeat the byte over and over. This builds a single byte array that is at most 64KiB and shares that across every `ChunksCons` cell.

An as example, creating a 2GiB chunks this way would use 64KiB for the byte array, and there would be the additional overhead of the 2^15 `ChunksCons` data constructors. On a 64-bit platform, `ChunksCons` takes 40 bytes, so the total memory consumption would be `2^16 + 40 * 2^15`, which is roughly 1.37MB. The same reasoning shows that it takes about 83.95MB to represent a 128GiB chunks.

The size of the shared payload is an implementation detail. Do not rely on this function producing 64KiB chunks. The implementation might one day change to something smarter that minimizes the memory footprint for very large chunks.

# Folds

foldl' :: (a -> Word8 -> a) -> a -> Chunks -> a #

Left fold over all bytes in the chunks, strict in the accumulator.

# Splitting

split :: Word8 -> Chunks -> [Bytes] #

Break chunks of bytes into contiguous pieces separated by the byte argument. This is a good producer for list fusion. For this function to perform well, each chunk should contain multiple separators. Any piece that spans multiple chunks must be copied.

# Hashing

fnv1a32 :: Chunks -> Word32 #

Hash byte sequence with 32-bit variant of FNV-1a.

fnv1a64 :: Chunks -> Word64 #

Hash byte sequence with 64-bit variant of FNV-1a.

# Create

fromBytes :: Bytes -> Chunks #

Create a list of chunks with a single chunk.

fromByteArray :: ByteArray -> Chunks #

Variant of `fromBytes` where the single chunk is unsliced.

# Copy to buffer

unsafeCopy #

Arguments

:: MutableByteArray s | Destination
-> Int | Destination offset
-> Chunks | Source
-> ST s Int | Returns the next index into the destination after the payload

Copy the contents of the chunks into a mutable array. Precondition: The destination must have enough space to house the contents. This is not checked.

# I/O with Handles

hGetContents :: Handle -> IO Chunks #

Read a handle's entire contents strictly into chunks.

readFile :: FilePath -> IO Chunks #

Read an entire file strictly into chunks. If reading from a regular file, this makes an effort read the file into a single chunk.

hPut :: Handle -> Chunks -> IO () #

Outputs `Chunks` to the specified `Handle`. This is implemented with `hPut`.

writeFile :: FilePath -> Chunks -> IO () #

Write `Chunks` to a file, replacing the previous contents of the file.