Data.Bytes.Builder.Unsafe

bytebuild-0.3.16.3: Build byte arrays

Safe Haskell | None
Language | Haskell2010

Data.Bytes.Builder.Unsafe

Contents

- Types
- Execution
- Construction
- Builder State
- Finalization
- Commit Distance
- Safe Functions
- Pasting with Preconditions

Synopsis

- newtype Builder = Builder (forall s. MutableByteArray# s -> Int# -> Int# -> Commits s -> State# s -> (# State# s, MutableByteArray# s, Int#, Int#, Commits s #))
- data BuilderState s = BuilderState (MutableByteArray# s) Int# Int# !(Commits s)
- data Commits s
  - = Mutable (MutableByteArray# s) Int# !(Commits s)
  - | Immutable ByteArray# Int# Int# !(Commits s)
  - | Initial
- pasteST :: Builder -> BuilderState s -> ST s (BuilderState s)
- pasteIO :: Builder -> BuilderState RealWorld -> IO (BuilderState RealWorld)
- fromEffect :: Int -> (forall s. MutableByteArray s -> Int -> ST s Int) -> Builder
- newBuilderState :: Int -> ST s (BuilderState s)
- closeBuilderState :: BuilderState s -> Commits s
- reverseCommitsOntoChunks :: Chunks -> Commits s -> ST s Chunks
- commitsOntoChunks :: Chunks -> Commits s -> ST s Chunks
- copyReverseCommits :: MutableByteArray s -> Int -> Commits s -> ST s Int
- addCommitsLength :: Int -> Commits s -> Int
- commitDistance :: MutableByteArray# s -> Int# -> Commits s -> Int#
- commitDistance1 :: MutableByteArray# s -> Int# -> MutableByteArray# s -> Int# -> Commits s -> Int#
- stringUtf8 :: String -> Builder
- cstring :: CString -> Builder
- pasteUtf8TextJson# :: ByteArray# -> Int# -> Int# -> MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)

# Types

newtype Builder #

An unmaterialized sequence of bytes that may be pasted into a mutable byte array.

Constructors

Builder (forall s. MutableByteArray# s -> Int# -> Int# -> Commits s -> State# s -> (# State# s, MutableByteArray# s, Int#, Int#, Commits s #)) |

#### Instances

Instances details

ToBuilder Builder # | Identity
Instance details Defined in Data.Bytes.Builder.Class Methods toBuilder :: Builder -> Builder #
Monoid Builder # |
Instance details Defined in Data.Bytes.Builder.Unsafe Methods mempty :: Builder # mappend :: Builder -> Builder -> Builder # mconcat :: [Builder] -> Builder #
Semigroup Builder # |
Instance details Defined in Data.Bytes.Builder.Unsafe Methods (<>) :: Builder -> Builder -> Builder # sconcat :: NonEmpty Builder -> Builder # stimes :: Integral b => b -> Builder -> Builder #
IsString Builder # |
Instance details Defined in Data.Bytes.Builder.Unsafe Methods fromString :: String -> Builder #

data BuilderState s #

A list of committed chunks along with the chunk currently being written to. This is kind of like a non-empty variant of `Commmits` but with the additional invariant that the head chunk is a mutable byte array.

Constructors

BuilderState (MutableByteArray# s) Int# Int# !(Commits s) |

data Commits s #

Constructors

Mutable |
Fields (MutableByteArray# s) Mutable buffer, start index implicitly zero Int# Length (may be smaller than actual length) !(Commits s)
Immutable |
Fields ByteArray# Immutable chunk Int# Offset into chunk, not necessarily zero Int# Length (may be smaller than actual length) !(Commits s)
Initial |

# Execution

pasteST :: Builder -> BuilderState s -> ST s (BuilderState s) #

Run a builder, performing an in-place update on the state. The `BuilderState` argument must not be reused after being passed to this function. That is, its use must be affine.

pasteIO :: Builder -> BuilderState RealWorld -> IO (BuilderState RealWorld) #

Variant of `pasteST` that runs in `IO`.

# Construction

fromEffect #

Arguments

:: Int | Maximum number of bytes the paste function needs
-> (forall s. MutableByteArray s -> Int -> ST s Int) | Paste function. Takes a byte array and an offset and returns the new offset and having pasted into the buffer.
-> Builder |

# Builder State

newBuilderState :: Int -> ST s (BuilderState s) #

Create an empty `BuilderState` with a buffer of the given size.

closeBuilderState :: BuilderState s -> Commits s #

Push the active chunk onto the top of the commits. The `BuilderState` argument must not be reused after being passed to this function. That is, its use must be affine.

# Finalization

reverseCommitsOntoChunks :: Chunks -> Commits s -> ST s Chunks #

Cons the chunks from a list of `Commits` onto an initial `Chunks` list (this argument is often `ChunksNil`). This reverses the order of the chunks, which is desirable since builders assemble `Commits` with the chunks backwards. This performs an in-place shrink and freezes any mutable byte arrays it encounters. Consequently, these must not be reused.

commitsOntoChunks :: Chunks -> Commits s -> ST s Chunks #

Variant of `reverseCommitsOntoChunks` that does not reverse the order of the commits. Since commits are built backwards by consing, this means that the chunks appended to the front will be backwards. Within each chunk, however, the bytes will be in the correct order.

Unlike `reverseCommitsOntoChunks`, this function is not tail recursive.

copyReverseCommits #

Arguments

:: MutableByteArray s | Destination
-> Int | Destination range successor
-> Commits s | Source
-> ST s Int |

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

addCommitsLength :: Int -> Commits s -> Int #

Add the total number of bytes in the commits to first argument.

# Commit Distance

commitDistance :: MutableByteArray# s -> Int# -> Commits s -> Int# #

Compute the number of bytes between the last byte and the offset specified in a chunk. Precondition: the chunk must exist in the list of committed chunks. This relies on mutable byte arrays having identity (e.g. it uses `sameMutableByteArray#`).

commitDistance1 :: MutableByteArray# s -> Int# -> MutableByteArray# s -> Int# -> Commits s -> Int# #

Variant of commitDistance where you get to supply a head of the commit list that has not yet been committed.

# Safe Functions

These functions are actually completely safe, but they are defined here because they are used by typeclass instances. Import them from `Data.Bytes.Builder` instead.

stringUtf8 :: String -> Builder #

Create a builder from a cons-list of `Char`. These must be UTF-8 encoded.

cstring :: CString -> Builder #

Create a builder from a `NUL`-terminated `CString`. This ignores any textual encoding, copying bytes until `NUL` is reached.

# Pasting with Preconditions

pasteUtf8TextJson# #

Arguments

:: ByteArray# | source
-> Int# | source offset
-> Int# | source length
-> MutableByteArray# s | destination buffer
-> Int# | offset into destination buffer
-> State# s | state token
-> (# State# s, Int# #) |

Encode (UTF-8 encoded) text as a JSON string, wrapping it in double quotes. This escapes all characters with code points below `0x20`.

- Precondition: The slice of the byte argument is UTF-8 encoded text.
- Precondition: There is enough space in the buffer for the result to be written to. A simple way to ensure enough space is to allocate `6N + 2` bytes, where N is the length of the argument. However, the caller may use clever heuristics to find a lower upper bound.
- Result: The next offset in the destination buffer