READ-DELIMITED
(READ-DELIMITED) (proposed by Jochen Schmidt) is a member of the Common Lisp Utilities family of programs, designed by community consensus.

Function READ-DELIMITED

Syntax:

read-delimited sequence stream &key start end delimiter test key => position, delimited-p

Arguments and Values:

sequence---a sequence. stream---an input stream. start, end---bounding index designators of sequence. The defaults for start and end are 0 and nil, respectively. delimiter---a character. It defaults to #\newline. test---a designator for a function of two arguments that returns a generalized boolean. key---a designator for a function of one argument, or nil. position---an integer greater than or equal to zero, and less than or equal to the length of the sequence. delimited-p---the result of the last invokation of test

Description:

Destructively modifies sequence by replacing elements of sequence bounded by start and end with elements read from stream.

Test is called with the actual read character, converted by applying key to it, as the first and delimiter as the second argument.

If a character is read for which (funcall test (funcall key char) delimiter) is non-nil, read-delimited terminates the copying even before reaching end of file or the end of the bounding designator.

read-delimited returns the index of the first element of sequence that was not updated as the first and the result of the last invokation of test as the second value.

Sequence is destructively modified by copying successive elements into it from stream. If the end of file for stream is reached before copying all elements of the subsequence, then the extra elements near the end of sequence are not updated.

Exceptional situations:

If start and/or end are out of bounds, or if start > end, then a read-delimited-bounds-error error is signalled. This error is passed the values of start, end, and sequence, which can be read with read-delimited-bounds-error-start, read-delimited-bounds-error-end, and read-delimited-bounds-error-sequence, respectively.