13.2 Byte and String Input

Characters are read from in until a line separator or an end-of-file is read. The line separator is not included in the result string (but it is removed from the port’s stream). If no characters are read before an end-of-file is encountered, eof is returned.

The mode argument determines the line separator(s). It must be one of the following symbols:

• 'linefeed breaks lines on linefeed characters.

• 'return breaks lines on return characters.

• 'return-linefeed breaks lines on return-linefeed combinations. If a return character is not followed by a linefeed character, it is included in the result string; similarly, a linefeed that is not preceded by a return is included in the result string.

• 'any breaks lines on any of a return character, linefeed character, or return-linefeed combination. If a return character is followed by a linefeed character, the two are treated as a combination.

• 'any-one breaks lines on either a return or linefeed character, without recognizing return-linefeed combinations.

Return and linefeed characters are detected after the conversions that are automatically performed when reading a file in text mode. For example, reading a file in text mode on Windows automatically changes return-linefeed combinations to a linefeed. Thus, when a file is opened in text mode, 'linefeed is usually the appropriate read-line mode.

Returns a string containing the next amt characters from in.

If amt is 0, then the empty string is returned. Otherwise, if fewer than amt characters are available before an end-of-file is encountered, then the returned string will contain only those characters before the end-of-file; that is, the returned string’s length will be less than amt. (A temporary string of size amt is allocated while reading the input, even if the size of the result is less than amt characters.) If no characters are available before an end-of-file, then eof is returned.

If an error occurs during reading, some characters may be lost; that is, if read-string successfully reads some characters before encountering an error, the characters are dropped.

If the difference between start-pos and end-pos is 0, then 0 is returned and str is not modified. If no bytes are available before an end-of-file, then eof is returned. Otherwise, the return value is the number of characters read. If m characters are read and m<end-pos-start-pos, then str is not modified at indices start-pos+m through end-pos.

When in produces a special value, as described in Custom Ports, the result is a procedure of four arguments. The four arguments correspond to the location of the special value within the port, as described in Custom Ports. If the procedure is called more than once with valid arguments, the exn:fail:contract exception is raised. If read-bytes-avail! returns a special-producing procedure, then it does not place characters in bstr. Similarly, read-bytes-avail! places only as many bytes into bstr as are available before a special value in the port’s stream.

For most kinds of ports, inspecting skip-bytes-amt bytes and amt characters requires at least skip-bytes-amt+amt bytes of memory overhead associated with the port, at least until the bytes/characters are read. No such overhead is required when peeking into a string port (see String Ports), a pipe port (see Pipes), or a custom port with a specific peek procedure (depending on how the peek procedure is implemented; see Custom Ports).

If a port produces eof mid-stream, attempts to skip beyond the eof for a peek always produce eof until the eof is read.

To peek, peek-bytes-avail! blocks until finding an end-of-file, at least one byte (or special) past the skipped bytes, or until a non-#f progress becomes ready. Furthermore, if progress is ready before bytes are peeked, no bytes are peeked or skipped, and progress may cut short the skipping process if it becomes available during the peek attempt. Furthermore, progress is checked even before determining whether the port is still open.

The result of peek-bytes-avail! is 0 only

• when start-pos is equal to end-pos, or

• when progress becomes ready before bytes are peeked.

Changed in version 6.8.0.2 of package base: Added the special-wrap and source-name arguments.

Changed in version 6.8.0.2 of package base: Added the special-wrap and source-name arguments.

• If special-wrap is #f, then the special value is returned (as for read-char-or-special).

• If special-wrap is a procedure, then it is applied the special value to produce the result (as for read-char-or-special).

• If special-wrap is 'special, then 'special is returned in place of the special value—without calling the special-value procedure that is returned by the input-port implementation.

Changed in version 6.8.0.2 of package base: Added the special-wrap and source-name arguments.
Changed in version 6.90.0.16: Added 'special as an option for special-wrap.

Changed in version 6.8.0.2 of package base: Added the special-wrap and source-name arguments.
Changed in version 6.90.0.16: Added 'special as an option for special-wrap.

The read commits only if progress does not become ready first (i.e., if no other process reads from in first), and only if evt is chosen by a sync within port-commit-peeked (in which case the event result is ignored); the evt must be either a channel-put event, channel, semaphore, semaphore-peek event, always event, or never event. Suspending the thread that calls port-commit-peeked may or may not prevent the commit from proceeding.

The result from port-commit-peeked is #t if data has been committed, and #f otherwise.

If no data has been peeked from in and progress is not ready, then exn:fail:contract exception is raised. If fewer than amt items have been peeked at the current start of in’s stream, then only the peeked items are committed as read. If in’s stream currently starts at an eof or a non-byte special value, then only the eof or special value is committed as read.

If progress is not a result of port-progress-evt applied to in, then exn:fail:contract exception is raised.

The byte-ready? and char-ready? functions are appropriate for relatively few applications, because ports are meant to support streaming data among concurrent producers and consumers; the fact that a byte or character is not ready in some instant does not necessarily mean that the producer is finished supplying data. (Also, if a port has multiple consumers, data might get consumed between the time that a given process uses byte-ready? to poll the port and the time that it reads data from the port.) Using byte-ready? makes sense if you are implementing your own scheduler or if you know that the port’s implementation and use are particularly constrained.

See byte-ready? for a note on how byte-ready? and char-ready? are rarely the right choice.

With two arguments, returns #t if evt is a progress event for in, #f otherwise.