IMPERATIVE_IO
signatureThe IMPERATIVE_IO signature defines the interface of the Imperative IO layer in the IO stack. This layer provides buffered IO using mutable streams.
signature IMPERATIVE_IO
structure StreamIO : STREAM_IO
type vector = StreamIO.vector
type elem = StreamIO.elem
type instream
type outstream
val input : instream -> vector
val input1 : instream -> elem option
val inputN : (instream * int) -> vector
val inputAll : instream -> vector
val canInput : (instream * int) -> int option
val lookahead : instream -> elem option
val closeIn : instream -> unit
val endOfStream : instream -> bool
val output : (outstream * vector) -> unit
val output1 : (outstream * elem) -> unit
val flushOut : outstream -> unit
val closeOut : outstream -> unit
val getPosIn : instream -> StreamIO.in_pos
val setPosIn : (instream * StreamIO.in_pos) -> unit
val mkInstream : StreamIO.instream -> instream
val getInstream : instream -> StreamIO.instream
val setInstream : (instream * StreamIO.instream) -> unit
val getPosOut : outstream -> StreamIO.out_pos
val setPosOut : (outstream * StreamIO.out_pos) -> unit
val mkOutstream : StreamIO.outstream -> outstream
val getOutstream : outstream -> StreamIO.outstream
val setOutstream : (outstream * StreamIO.outstream) -> unit
structure StreamIO
type vector
type elem
type instream
type outstream
input strm
vector
of at least one element. When strm is at end-of-stream or is closed, returns an empty vector. Otherwise, input
blocks until one of these conditions is met, and returns accordingly. May raise the exception Io.
input1 strm
SOME e
if one element was available; returns NONE if at end-of-stream. May block, and may raise the exception Io.
inputN (strm, n)
maxLen
.
inputAll strm
canInput (strm, n)
SOME k
, where 0 <= k <= n, if a call to input would return immediately with k characters. Note that k = 0 corresponds to the stream being at end-of-stream.
Some streams may not support this operation, in which case the Io exception will be raised. This function also raises the Io exception if there is an error in the underlying system calls. It raises the Size exception if n < 0.
Implementation note:
Implementations of canInput should attempt to return as large a k as possible. For example, if the buffer contains 10 characters and the user calls
canInput (f, 15)
, canInput should callreadVecNB 5
to see if an additional 5 characters are available.
lookahead strm
SOME e
in this case; returns NONE
if at end-of-stream. In the former case, e
is not removed from strm but stays available for further input operations. May block, and may raise the exception Io.
Note that arbitrary lookahead can be easily implemented using the underlying stream.
closeIn strm
closeIn
applied to an already closed stream will be ignored. Other operations on a closed stream will behave as if the stream is at end-of-stream. The function is implemented in terms of S.closeIn
. It may also raise Io when another error occurs.
endOfStream strm
true
if strm is at end-of-stream, and false
if elements are still available. May block until one of these conditions is determined, and may raise the exception Io. Note: When endOfStream
returns true
on an unterminated stream, this denotes the current situation. When further data are appended to the underlying file or stream, the next call to endOfStream
will return false, and input operations will deliver new elements.
output (strm, vec)
output1 (strm, el)
flushOut strm
S.flushOut
. May block, and may raise the exception Io when an error occurs.
closeOut strm
S.closeOut
. A write attempt on a closed outstream will cause the exception Io{cause=ClosedStream,...}
to be raised. May also raise Io when another error occurs (e.g., buffers can't be flushed out).
getPosIn strm
setPosIn (strm, pos)
mkInstream strm
getInstream
.
getInstream strm
setInstream (strm, strm')
getPosOut strm
setPosOut (strm, pos)
mkOutstream strm
getOutstream strm
setOutstream (strm, strm')
TextIO, BinIO, STREAM_IO, ImperativeIO
Last Modified January 29, 1997
Comments to John Reppy.
Copyright © 1997 Bell Labs, Lucent Technologies