21.4. Bulk Input and Output
Prev | Chapter 21. Streams | Next

## 21.4. Bulk Input and Output

### 21.4.1. Bulk Input

In addition to `READ-SEQUENCE`, the following two functions are provided:

`EXT:READ-BYTE-SEQUENCE` performs multiple `READ-BYTE` operations:

  `(`EXT:READ-BYTE-SEQUENCE` `sequence` `stream` `&KEY` `:START` `:END` :NO-HANG :INTERACTIVE)` fills the subsequence of `sequence` specified by `:START` and `:END` with `INTEGER`s consecutively read from `stream`. It returns the index of the first element of `sequence` that was not updated (= `end` or < `end` if the `stream` reached its end). When `no-hang` is non-`NIL`, it does not block: it treats input unavailability as `end-of-stream`. When `no-hang` is `NIL` and `interactive` is non-`NIL`, it can block for reading the first byte but does not block for any further bytes.

  This function is especially efficient if `sequence` is a `(`VECTOR` (`UNSIGNED-BYTE` 8))` and `stream` is a file/pipe/socket `STREAM` with `STREAM-ELEMENT-TYPE` `(`UNSIGNED-BYTE` 8)`.

`EXT:READ-CHAR-SEQUENCE` performs multiple `READ-CHAR` operations:

  `(`EXT:READ-CHAR-SEQUENCE` `sequence` `stream` `&KEY` `:START` `:END`)` fills the subsequence of `sequence` specified by `:START` and `:END` with characters consecutively read from `stream`. It returns the index of the first element of `sequence` that was not updated (= `end` or < `end` if the `stream` reached its end).

  This function is especially efficient if `sequence` is a `STRING` and `stream` is a file/pipe/socket `STREAM` with `STREAM-ELEMENT-TYPE` `CHARACTER` or an input `STRING-STREAM`.

### 21.4.2. Bulk Output

In addition to `WRITE-SEQUENCE`, the following two functions are provided:

`EXT:WRITE-BYTE-SEQUENCE` performs multiple `WRITE-BYTE` operations:

  `(`EXT:WRITE-BYTE-SEQUENCE` `sequence` `stream` `&KEY` `:START` `:END` :NO-HANG :INTERACTIVE)` outputs the `INTEGER`s of the subsequence of `sequence` specified by `:START` and `:END` to `stream`. When `no-hang` is non-`NIL`, does not block. When `no-hang` is `NIL` and `interactive` is non-`NIL`, it can block for writing the first byte but does not block for any further bytes. Returns two values: `sequence` and the index of the first byte that was not output.

  This function is especially efficient if `sequence` is a `(`VECTOR` (`UNSIGNED-BYTE` 8))` and `stream` is a file/pipe/socket `STREAM` with `STREAM-ELEMENT-TYPE` `(`UNSIGNED-BYTE` 8)`.

`EXT:WRITE-CHAR-SEQUENCE` performs multiple `WRITE-CHAR` operations:

  `(`EXT:WRITE-CHAR-SEQUENCE` `sequence` `stream` `&KEY` `:START` `:END`)` outputs the characters of the subsequence of `sequence` specified by `:START` and `:END` to `stream`. Returns the `sequence` argument.

  This function is especially efficient if `sequence` is a `STRING` and `stream` is a file/pipe/socket `STREAM` with `STREAM-ELEMENT-TYPE` `CHARACTER`.

### 21.4.3. Rationale

The rationale for `EXT:READ-CHAR-SEQUENCE`, `EXT:READ-BYTE-SEQUENCE`, `EXT:WRITE-CHAR-SEQUENCE` and `EXT:WRITE-BYTE-SEQUENCE` is that some `STREAM`s support both character and binary i/o, and when you read into a `SEQUENCE` that can hold both (e.g., `LIST` or `SIMPLE-VECTOR`) you cannot determine which kind of input to use. In such situation `READ-SEQUENCE` and `WRITE-SEQUENCE` `SIGNAL` an `ERROR`, while `EXT:READ-CHAR-SEQUENCE`, `EXT:READ-BYTE-SEQUENCE`, `EXT:WRITE-CHAR-SEQUENCE` and `EXT:WRITE-BYTE-SEQUENCE` work just fine.

| These notes document CLISP version 2.45 | Last modified: 2008-05-14

Enter your search termsSubmit search form
Webclisp.cons.orgclisp.podval.orgwww.lisp.org

Prev | Up | Next
21.3. Binary Input and Output | Home | 21.5. Non-Blocking Input and Output