base-4.7.0.0: Basic libraries

Copyright | (c) The University of Glasgow 2008
License | see libraries/base/LICENSE
Maintainer | cvs-ghc@haskell.org
Stability | internal
Portability | non-portable (GHC Extensions)
Safe Haskell | Trustworthy
Language | Haskell2010

GHC.IO.Buffer

Contents

- Buffers of any element
  - Creation
  - Insertion/removal
  - Inspecting
  - Operating on the raw buffer as a Ptr
  - Assertions
- Raw buffers

Description

Buffers used in the IO system

Synopsis

- data Buffer e = Buffer {
  - bufRaw :: !(RawBuffer e)
  - bufState :: BufferState
  - bufSize :: !Int
  - bufL :: !Int
  - bufR :: !Int
  }
- data BufferState
  - = ReadBuffer
  - | WriteBuffer
- type CharBuffer = Buffer Char
- type CharBufElem = Char
- newByteBuffer :: Int -> BufferState -> IO (Buffer Word8)
- newCharBuffer :: Int -> BufferState -> IO CharBuffer
- newBuffer :: Int -> Int -> BufferState -> IO (Buffer e)
- emptyBuffer :: RawBuffer e -> Int -> BufferState -> Buffer e
- bufferRemove :: Int -> Buffer e -> Buffer e
- bufferAdd :: Int -> Buffer e -> Buffer e
- slideContents :: Buffer Word8 -> IO (Buffer Word8)
- bufferAdjustL :: Int -> Buffer e -> Buffer e
- isEmptyBuffer :: Buffer e -> Bool
- isFullBuffer :: Buffer e -> Bool
- isFullCharBuffer :: Buffer e -> Bool
- isWriteBuffer :: Buffer e -> Bool
- bufferElems :: Buffer e -> Int
- bufferAvailable :: Buffer e -> Int
- summaryBuffer :: Buffer a -> String
- withBuffer :: Buffer e -> (Ptr e -> IO a) -> IO a
- withRawBuffer :: RawBuffer e -> (Ptr e -> IO a) -> IO a
- checkBuffer :: Buffer a -> IO ()
- type RawBuffer e = ForeignPtr e
- readWord8Buf :: RawBuffer Word8 -> Int -> IO Word8
- writeWord8Buf :: RawBuffer Word8 -> Int -> Word8 -> IO ()
- type RawCharBuffer = RawBuffer CharBufElem
- peekCharBuf :: RawCharBuffer -> Int -> IO Char
- readCharBuf :: RawCharBuffer -> Int -> IO (Char, Int)
- writeCharBuf :: RawCharBuffer -> Int -> Char -> IO Int
- readCharBufPtr :: Ptr CharBufElem -> Int -> IO (Char, Int)
- writeCharBufPtr :: Ptr CharBufElem -> Int -> Char -> IO Int
- charSize :: Int

# Buffers of any element

data Buffer e

A mutable array of bytes that can be passed to foreign functions.

The buffer is represented by a record, where the record contains the raw buffer and the start/end points of the filled portion. The buffer contents itself is mutable, but the rest of the record is immutable. This is a slightly odd mix, but it turns out to be quite practical: by making all the buffer metadata immutable, we can have operations on buffer metadata outside of the IO monad.

The "live" elements of the buffer are those between the `bufL` and `bufR` offsets. In an empty buffer, `bufL` is equal to `bufR`, but they might not be zero: for exmaple, the buffer might correspond to a memory-mapped file and in which case `bufL` will point to the next location to be written, which is not necessarily the beginning of the file.

Constructors

Buffer |
Fields bufRaw :: !(RawBuffer e) bufState :: BufferState bufSize :: !Int bufL :: !Int bufR :: !Int

data BufferState

Constructors

ReadBuffer |
WriteBuffer |

Instances

Eq BufferState |

type CharBuffer = Buffer Char

type CharBufElem = Char

## Creation

newByteBuffer :: Int -> BufferState -> IO (Buffer Word8)

newCharBuffer :: Int -> BufferState -> IO CharBuffer

newBuffer :: Int -> Int -> BufferState -> IO (Buffer e)

emptyBuffer :: RawBuffer e -> Int -> BufferState -> Buffer e

## Insertion/removal

bufferRemove :: Int -> Buffer e -> Buffer e

bufferAdd :: Int -> Buffer e -> Buffer e

slideContents :: Buffer Word8 -> IO (Buffer Word8)

slides the contents of the buffer to the beginning

bufferAdjustL :: Int -> Buffer e -> Buffer e

## Inspecting

isEmptyBuffer :: Buffer e -> Bool

isFullBuffer :: Buffer e -> Bool

isFullCharBuffer :: Buffer e -> Bool

isWriteBuffer :: Buffer e -> Bool

bufferElems :: Buffer e -> Int

bufferAvailable :: Buffer e -> Int

summaryBuffer :: Buffer a -> String

## Operating on the raw buffer as a Ptr

withBuffer :: Buffer e -> (Ptr e -> IO a) -> IO a

withRawBuffer :: RawBuffer e -> (Ptr e -> IO a) -> IO a

## Assertions

checkBuffer :: Buffer a -> IO ()

# Raw buffers

type RawBuffer e = ForeignPtr e

readWord8Buf :: RawBuffer Word8 -> Int -> IO Word8

writeWord8Buf :: RawBuffer Word8 -> Int -> Word8 -> IO ()

type RawCharBuffer = RawBuffer CharBufElem

peekCharBuf :: RawCharBuffer -> Int -> IO Char

readCharBuf :: RawCharBuffer -> Int -> IO (Char, Int)

writeCharBuf :: RawCharBuffer -> Int -> Char -> IO Int

readCharBufPtr :: Ptr CharBufElem -> Int -> IO (Char, Int)

writeCharBufPtr :: Ptr CharBufElem -> Int -> Char -> IO Int

charSize :: Int