haskell / haskell/bytestring

Request for clarification in Builder.customStrategy docs

Open
#561 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
Haskell
Stars
301
Forks
144
Avg merge
7d 22h
Merged PRs (30d)
1

Description

[`customStrategy`](https://hackage.haskell.org/package/bytestring-0.11.3.1/docs/Data-ByteString-Builder-Internal.html#v:customStrategy) is documented:

``` hs
customStrategy
:: (Maybe (Buffer, Int) -> IO Buffer)
-- ^ Buffer allocation function. If 'Nothing' is given, then a new first
-- buffer should be allocated. If @'Just' (oldBuf, minSize)@ is given,
-- then a buffer with minimal size @minSize@ must be returned. The
-- strategy may reuse the @oldBuf@, if it can guarantee that this
-- referentially transparent and @oldBuf@ is large enough.
-> Int
-- ^ Default buffer size.
-> (Int -> Int -> Bool)
-- ^ A predicate @trim used allocated@ returning 'True', if the buffer
-- should be trimmed before it is returned.
-> AllocationStrategy
```

I'm struggling to understand where one might want to reuse the buffer passed to the first argument of `customStrategy` (call it `nextBuffer`) . My understanding is `nextBuffer` is meant to do something like:

```
nextBuffer (Just (buf, minSize)) = if free_space_in buf <= minSize then return buf else newBuffer minSize
```

But I’m confused about under what circumstances `free_space_in buf` is true. None of the `AllocationStrategy`s in the library make use of `buf` as far as I can tell

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.