put package:bytestring

Construct a Put action. In contrast to BuildSteps, Puts are referentially transparent in the sense that sequencing the same Put multiple times yields every time the same value with the same side-effect.

A Put action denotes a computation of a value that writes a stream of bytes as a side-effect. Puts are strict in their side-effect; i.e., the stream of bytes will always be written before the computed value is returned. Puts are a generalization of Builders. The typical use case is the implementation of an encoding that might fail (e.g., an interface to the zlib compression library or the conversion from Base64 encoded data to 8-bit data). For a Builder, the only way to handle and report such a failure is ignore it or call error. In contrast, Put actions are expressive enough to allow reporting and handling such a failure in a pure fashion. Put () actions are isomorphic to Builders. The functions putBuilder and fromPut convert between these two types. Where possible, you should use Builders, as sequencing them is slightly cheaper than sequencing Puts because they do not carry around a computed value.

Write a ByteString to stdout.

Run a Builder as a side-effect of a Put () action.

Execute a Put and return the computed result and the bytes written during the computation as a LazyByteString. This function is strict in the computed result and lazy in the writing of the bytes. For example, given

infinitePut = sequence_ (repeat (putBuilder (word8 1))) >> return 0

evaluating the expression

fst $ putToLazyByteString infinitePut

does not terminate, while evaluating the expression

L.head $ snd $ putToLazyByteString infinitePut

does terminate and yields the value 1 :: Word8. An illustrative example for these strictness properties is the implementation of Base64 decoding (http://en.wikipedia.org/wiki/Base64).

type DecodingState = ...

decodeBase64 :: StrictByteString -> DecodingState -> Put (Maybe DecodingState)
decodeBase64 = ...

The above function takes a StrictByteString supposed to represent Base64 encoded data and the current decoding state. It writes the decoded bytes as the side-effect of the Put and returns the new decoding state, if the decoding of all data in the StrictByteString was successful. The checking if the StrictByteString represents Base64 encoded data and the actual decoding are fused. This makes the common case, where all data represents Base64 encoded data, more efficient. It also implies that all data must be decoded before the final decoding state can be returned. Puts are intended for implementing such fused checking and decoding/encoding, which is reflected in their strictness properties.

Execute a Put with a buffer-allocation strategy and a continuation. For example, putToLazyByteString is implemented as follows.

putToLazyByteString = putToLazyByteStringWith
(safeStrategy smallChunkSize defaultChunkSize) (x -> (x, L.empty))

Write a ByteString to stdout, appending a newline byte. Unlike putStr, this is not atomic: other threads might write to stdout between writing of the bytestring and the newline.

Write a ByteString to stdout. The chunks will be written one at a time. Other threads might write to the stdout in between, and hence putStr alone is not suitable for concurrent writes.

Write a ByteString to stdout, appending a newline byte. The chunks will be written one at a time, followed by a newline. Other threads might write to the stdout in between, and hence putStrLn alone is not suitable for concurrent writes.

Outputs a ByteString to the specified Handle.

Similar to hPut except that it will never block. Instead it returns any tail that did not get written. This tail may be empty in the case that the whole string was written, or the whole original string if nothing was written. Partial writes are also possible. Note: on Windows and with Haskell implementation other than GHC, this function does not work correctly; it behaves identically to hPut.

A synonym for hPut, for compatibility

Output a Builder to a Handle. The Builder is executed directly on the buffer of the Handle. If the buffer is too small (or not present), then it is replaced with a large enough buffer. It is recommended that the Handle is set to binary and BlockBuffering mode. See hSetBinaryMode and hSetBuffering. This function is more efficient than hPut . toLazyByteString because in many cases no buffer allocation has to be done. Moreover, the results of several executions of short Builders are concatenated in the Handles buffer, therefore avoiding unnecessary buffer flushes.

Convert a Put () action to a Builder.

Run a Put action redirecting the produced output to a Handle. The output is buffered using the Handles associated buffer. If this buffer is too small to execute one step of the Put action, then it is replaced with a large enough buffer.

Run a Put.

Write a ByteString to a handle, appending a newline byte. Unlike hPutStr, this is not atomic: other threads might write to the handle between writing of the bytestring and the newline.

Outputs a ByteString to the specified Handle. The chunks will be written one at a time. Other threads might write to the Handle in between, and hence hPut alone is not suitable for concurrent writes.

Write a ByteString to a handle, appending a newline byte. The chunks will be written one at a time, followed by a newline. Other threads might write to the Handle in between, and hence hPutStrLn alone is not suitable for concurrent writes.