MissingH-1.2.0.0: Large utility library

Portability | portable to platforms supporting binary I\/O
Stability | provisional
Maintainer | John Goerzen <jgoerzen@complete.org>
Safe Haskell | None

System.IO.Binary

Contents

- Support for different types of blocks
- Entire File/Handle Utilities
  - Opened Handle Data Copying
  - Disk File Data Copying
- Binary Single-Block I/O
- Binary Multi-Block I/O
- Lazy Interaction
  - Binary Block-based

Description

This module provides various helpful utilities for dealing with binary input and output.

You can use this module to deal with binary blocks of data as either Strings or lists of Word8. The BinaryConvertible class provides this abstraction.

Wherever you see HVIO, you can transparently substite a regular Handle. This module can work with any HVIO object, however. See System.IO.HVIO for more details.

Versions of MissingH prior 0.11.6 lacked the `BinaryConvertible` class and worked only with Strings and Handles.

Important note: /binary functions are not supported in all Haskell implementations/. Do not import or use this module unless you know you are using an implementation that supports them. At this time, here is the support status:

- GHC 6.2 and above: yes
- GHC 6.x, earlier versions: unknown
- GHC 5.x: no
- nhc98: no
- Hugs: partial (maybe complete; needs more testing)

Non-binary functions may be found in System.IO.

See also: System.IO.BlockIO

Written by John Goerzen, jgoerzen@complete.org

Synopsis

- class (Eq a, Show a) => BinaryConvertible a where
  - toBuf :: [a] -> (Ptr CChar -> IO c) -> IO c
  - fromBuf :: Int -> (Ptr CChar -> IO Int) -> IO [a]
- hBlockCopy :: (HVIO a, HVIO b) => Int -> a -> b -> IO ()
- blockCopy :: Int -> IO ()
- copyFileBlocksToFile :: Int -> FilePath -> FilePath -> IO ()
- hPutBufStr :: (HVIO a, BinaryConvertible b) => a -> [b] -> IO ()
- putBufStr :: BinaryConvertible b => [b] -> IO ()
- hGetBufStr :: (HVIO a, BinaryConvertible b) => a -> Int -> IO [b]
- getBufStr :: BinaryConvertible b => Int -> IO [b]
- hFullGetBufStr :: (HVIO a, BinaryConvertible b) => a -> Int -> IO [b]
- fullGetBufStr :: BinaryConvertible b => Int -> IO [b]
- hGetBlocks :: (HVIO a, BinaryConvertible b) => a -> Int -> IO [[b]]
- getBlocks :: BinaryConvertible b => Int -> IO [[b]]
- hFullGetBlocks :: (HVIO a, BinaryConvertible b) => a -> Int -> IO [[b]]
- fullGetBlocks :: BinaryConvertible b => Int -> IO [[b]]
- readBinaryFile :: FilePath -> IO String
- writeBinaryFile :: FilePath -> String -> IO ()
- hBlockInteract :: (HVIO a, HVIO d, BinaryConvertible b, BinaryConvertible c) => Int -> a -> d -> ([[b]] -> [[c]]) -> IO ()
- blockInteract :: (BinaryConvertible b, BinaryConvertible c) => Int -> ([[b]] -> [[c]]) -> IO ()
- hFullBlockInteract :: (HVIO a, HVIO d, BinaryConvertible b, BinaryConvertible c) => Int -> a -> d -> ([[b]] -> [[c]]) -> IO ()
- fullBlockInteract :: (BinaryConvertible b, BinaryConvertible c) => Int -> ([[b]] -> [[c]]) -> IO ()

# Support for different types of blocks

class (Eq a, Show a) => BinaryConvertible a where Source

Provides support for handling binary blocks with convenient types.

This module provides implementations for Strings and for [Word8] (lists of Word8s).

Methods

toBuf :: [a] -> (Ptr CChar -> IO c) -> IO cSource

fromBuf :: Int -> (Ptr CChar -> IO Int) -> IO [a]Source

Instances

BinaryConvertible Char |
BinaryConvertible Word8 |

# Entire File/Handle Utilities

## Opened Handle Data Copying

hBlockCopy :: (HVIO a, HVIO b) => Int -> a -> b -> IO ()Source

Copies everything from the input handle to the output handle using binary blocks of the given size. This was once the following beautiful implementation:

     hBlockCopy bs hin hout = hBlockInteract bs hin hout id

(`id` is the built-in Haskell function that just returns whatever is given to it)

In more recent versions of MissingH, it uses a more optimized routine that avoids ever having to convert the binary buffer at all.

blockCopy :: Int -> IO ()Source

Copies from `stdin` to `stdout` using binary blocks of the given size. An alias for `hBlockCopy` over `stdin` and `stdout`

## Disk File Data Copying

copyFileBlocksToFile :: Int -> FilePath -> FilePath -> IO ()Source

Copies one filename to another in binary mode.

Please note that the Unix permission bits on the output file cannot be set due to a limitation of the Haskell `openBinaryFile` function. Therefore, you may need to adjust those bits after the copy yourself.

This function is implemented using `hBlockCopy` internally.

# Binary Single-Block I/O

hPutBufStr :: (HVIO a, BinaryConvertible b) => a -> [b] -> IO ()Source

As a wrapper around the standard function `hPutBuf`, this function takes a standard Haskell `String` instead of the far less convenient `Ptr a`. The entire contents of the string will be written as a binary buffer using `hPutBuf`. The length of the output will be the length of the passed String or list.

If it helps, you can thing of this function as being of type `Handle -> String -> IO ()`

putBufStr :: BinaryConvertible b => [b] -> IO ()Source

An alias for `hPutBufStr` `stdout`

hGetBufStr :: (HVIO a, BinaryConvertible b) => a -> Int -> IO [b]Source

Acts a wrapper around the standard function `hGetBuf`, this function returns a standard Haskell String (or [Word8]) instead of modifying a 'Ptr a' buffer. The length is the maximum length to read and the semantice are the same as with `hGetBuf`; namely, the empty string is returned with EOF is reached, and any given read may read fewer bytes than the given length.

(Actually, it's a wrapper around `vGetBuf`)

getBufStr :: BinaryConvertible b => Int -> IO [b]Source

An alias for `hGetBufStr` `stdin`

hFullGetBufStr :: (HVIO a, BinaryConvertible b) => a -> Int -> IO [b]Source

Like `hGetBufStr`, but guarantees that it will only return fewer than the requested number of bytes when EOF is encountered.

fullGetBufStr :: BinaryConvertible b => Int -> IO [b]Source

An alias for `hFullGetBufStr` `stdin`

# Binary Multi-Block I/O

hGetBlocks :: (HVIO a, BinaryConvertible b) => a -> Int -> IO [[b]]Source

An alias for `hPutBlocks` `stdout` putBlocks :: (BinaryConvertible b) => [[b]] -> IO () putBlocks = hPutBlocks stdout

Returns a lazily-evaluated list of all blocks in the input file, as read by `hGetBufStr`. There will be no 0-length block in this list. The list simply ends at EOF.

getBlocks :: BinaryConvertible b => Int -> IO [[b]]Source

An alias for `hGetBlocks` `stdin`

hFullGetBlocks :: (HVIO a, BinaryConvertible b) => a -> Int -> IO [[b]]Source

Same as `hGetBlocks`, but using `hFullGetBufStr` underneath.

fullGetBlocks :: BinaryConvertible b => Int -> IO [[b]]Source

An alias for `hFullGetBlocks` `stdin`

# Lazy Interaction

readBinaryFile :: FilePath -> IO String Source

Like the built-in `readFile`, but opens the file in binary instead of text mode.

writeBinaryFile :: FilePath -> String -> IO ()Source

Like the built-in `writeFile`, but opens the file in binary instead of text mode.

## Binary Block-based

hBlockInteract :: (HVIO a, HVIO d, BinaryConvertible b, BinaryConvertible c) => Int -> a -> d -> ([[b]] -> [[c]]) -> IO ()Source

Binary block-based interaction. This is useful for scenarios that take binary blocks, manipulate them in some way, and then write them out. Take a look at `hBlockCopy` for an example. The integer argument is the size of input binary blocks. This function uses `hGetBlocks` internally.

blockInteract :: (BinaryConvertible b, BinaryConvertible c) => Int -> ([[b]] -> [[c]]) -> IO ()Source

An alias for `hBlockInteract` over `stdin` and `stdout`

hFullBlockInteract :: (HVIO a, HVIO d, BinaryConvertible b, BinaryConvertible c) => Int -> a -> d -> ([[b]] -> [[c]]) -> IO ()Source

Same as `hBlockInteract`, but uses `hFullGetBlocks` instead of `hGetBlocks` internally.

fullBlockInteract :: (BinaryConvertible b, BinaryConvertible c) => Int -> ([[b]] -> [[c]]) -> IO ()Source

An alias for `hFullBlockInteract` over `stdin` and `stdout`