# Using the NHC.BinArray library

This document describes the York BinArray library, a library for imperative binary arrays which, although it is implemented using the Binary library, has an independent interface and can be used pretty-much without any knowledge of the Binary library at all. We present this BinArray module as an example of the use of the Binary library to build higher-level facilities, and would encourage programmers to write and publish other useful libraries in a similar manner.

### NHC.BinArray library

        module NHC.BinArray
          ( type  BinArray
          , newBinArray
          , intoBinArray
          , fromBinArray
          , putBinArray
          , getBinArray
          ) where

        data BinArray a = ...

        newBinArray   :: Binary a => Int -> a -> IO (BinArray a)

        intoBinArray  :: Binary a => BinArray a -> a   -> IO Int
        fromBinArray  :: Binary a => BinArray a -> Int -> IO a

        putBinArray   :: Binary a => FilePath -> BinArray a -> IO ()
        getBinArray   :: Binary a => FilePath -> IO (BinArray a)

A `BinArray a` is an imperative (mutable) array that holds values of type `a` in binary representation. It is implemented using the Binary library, but as you can see, this is largely hidden from the programmer. A BinArray can only be written to sequentially. If one attempts to read a value from an index position which has not yet been written to (or which is beyond the bounds of the array), a default value is returned.

A BinArray can be stored in a file between program runs. Reading and writing BinArrays to disk is fast. Once a BinArray has been read back from disk, it can be written to again in the usual way.

`newBinArray n d` | gives you a fresh binary array of size `n`, filled with default value `d`. The binary values are stored in memory.
`intoBinArray ba x` | stuffs the value `x` into the array `ba` using a binary representation
`fromBinArray ba i` | gives you back the value at the `i`'th position in the array `ba`
`putBinArray fn ba` | copies the whole array `ba` into a binary file whose name is `fn`
`getBinArray fn` | gives you back a binary array read from the file named `fn`

The latest updates to these pages are available on the WWW from `http://www.cs.york.ac.uk/fp/nhc98/`

1998.03.26
York Functional Programming Group