From 895b81c8b112bce81ab8295c614ee738ced2058d Mon Sep 17 00:00:00 2001 From: Carl Gay Date: Thu, 8 Apr 2021 17:02:12 +0000 Subject: [PATCH] WIP -- read-into! --- .../library-reference/source/io/streams.rst | 103 +++++++++++++----- sources/io/streams/buffered-stream.dylan | 3 +- 2 files changed, 77 insertions(+), 29 deletions(-) diff --git a/documentation/library-reference/source/io/streams.rst b/documentation/library-reference/source/io/streams.rst index 532cc696a..b14c3780f 100644 --- a/documentation/library-reference/source/io/streams.rst +++ b/documentation/library-reference/source/io/streams.rst @@ -1285,35 +1285,73 @@ are exported from the *streams* module. .. class:: - Error type signaled on encountering the end of a stream before - reading the required number of elements. + Signaled on encountering the end of a stream before reading the requested + number of elements. :superclasses: :class:`` :keyword sequence: An instance of :drm:``. - :keyword count: An instance of :drm:``. + :keyword count: An instance of :drm:``. :description: - This error is signaled when input functions are reading a required - number of elements, but the end of the stream is read before - completing the required read. + This error is signaled when an input function reaches the end of the + stream before reading the requested number of elements. - The ``sequence:`` init-keyword contains the input that was read - before reaching the end of the stream. Its accessor is - ``incomplete-read-error-sequence``. + The *sequence:* init-keyword specifies a sequence of elements read from + the stream; it's value depends on which read function signaled the + error. Its accessor is :gf:`stream-error-sequence`. - The ``count:`` init-keyword contains the number of elements that were - requested to be read. Its accessor is - ``incomplete-read-error-count``. + The *count:* init-keyword specifies the number of elements that were + actually read. Its accessor is :gf:`stream-error-count`. :seealso: + - :gf:`stream-error-count` + - :gf:`stream-error-sequence` + +.. generic-function:: stream-error-count + + Returns the number of elements read before the end of the stream was + encountered. + + :signature: stream-error-count *stream-error* => *count* + + :parameter stream-error: An instance of :class:``. + :value count: An instance of :drm:``. + + :description: + + Returns the number of elements read before the end of the stream was + encountered. + + :seealso: + + - :gf:`stream-error-sequence` + - :class:`` + - :class:`` + +.. generic-function:: stream-error-sequence + + Returns a sequence of elements read before the end of the stream was + encountered. + + :signature: stream-error-sequence *stream-error* => *sequence* + + :parameter stream-error: An instance of :class:``. + :value sequence: An instance of :drm:``. + + :description: + + Returns the number of elements read before the end of the stream was + encountered. The exact semantics differ depending on which read function + signaled the error. + + :seealso: + + - :gf:`stream-error-count` + - :class:`` - :class:`` - - :class:`` - - :class:`` - - :class:`` - - :class:`` .. class:: :sealed: @@ -1848,25 +1886,34 @@ are exported from the *streams* module. :parameter input-stream: An instance of :class:``. :parameter n: An instance of :drm:``. :parameter sequence: An instance of :drm:``. - :parameter #key start: An instance of :drm:``. + :parameter #key start: An instance of :drm:``. Defaults to ``0``. :parameter #key on-end-of-stream: An instance of :drm:``. :value count-or-eof: An instance of :drm:``, or an instance of - :drm:`` if the end of stream is reached.. + :drm:`` if the end of stream is reached. :description: - Reads the next *n* elements from *input-stream*, and inserts them - into a mutable sequence starting at the position *start*. Returns - the number of elements actually inserted into *sequence* unless the - end of the stream is reached, in which case the *on-end-of-stream* - behavior is as for :gf:`read`. + Reads the next *n* elements from *input-stream*, and inserts them into + *sequence* starting at the position *start*. Returns the number of + elements actually inserted into *sequence* unless the end of the stream is + reached, in which case the *on-end-of-stream* behavior is as follows. + + - If a value for the *on-end-of-stream* argument was supplied, it + is returned as the value of *read-into!*. + - If a value for the *on-end-of-stream* argument was not supplied, and at + least one element was read from the stream, then an + :class:`` condition is signaled. When signaling + this condition, *read-into!* supplies two values: a sequence of the + elements that were read successfully, and *n*. + - If the *on-end-of-stream* argument was not supplied, and no + elements were read from the stream, an + :class:`` condition is signalled. - If the sum of *start* and *n* is greater than the size of - *sequence*, ``read-into!`` reads only enough elements to fill - sequence up to the end. If *sequence* is a stretchy vector, no - attempt is made to grow it. + If the sum of *start* and *n* is greater than the size of *sequence*, + :gf:`read-into!` reads only enough elements to fill sequence up to the + end. If *sequence* is a stretchy vector, no attempt is made to grow it. - If the stream is not at its end, ``read-into!`` waits until input + If the stream is not at its end, :gf:`read-into!` waits until input becomes available. :seealso: diff --git a/sources/io/streams/buffered-stream.dylan b/sources/io/streams/buffered-stream.dylan index 8967f1a81..15fb17630 100644 --- a/sources/io/streams/buffered-stream.dylan +++ b/sources/io/streams/buffered-stream.dylan @@ -468,7 +468,8 @@ define method read-into! n-read := i - start; signal(make(, stream: stream, - count: n-read, sequence: seq)) + count: n-read, + sequence: seq)) end end end