reference clarifications on string ports
Closes PR 12365
This commit is contained in:
parent
48d5d6fca3
commit
1175964a78
|
@ -81,26 +81,27 @@ If @racket[mode] is not provided, the current mode is returned, or
|
|||
|
||||
Returns or sets the current read/write position of @racket[port].
|
||||
|
||||
Calling @racket[file-position] without a position on a
|
||||
non-file/non-string input port returns the number of bytes that have
|
||||
Calling @racket[file-position] without a position on a port other
|
||||
than a @tech{file-stream port} or @tech{string port}
|
||||
returns the number of bytes that have
|
||||
been read from that port if the position is known (see
|
||||
@secref["linecol"]), otherwise the @exnraise[exn:fail:filesystem].
|
||||
|
||||
For @tech{file-stream ports} and string ports, the position-setting
|
||||
For @tech{file-stream ports} and @tech{string ports}, the position-setting
|
||||
variant sets the read/write position to @racket[pos] relative to the
|
||||
beginning of the file/string if @racket[pos] is a number, or to the
|
||||
current end of the file/string if @racket[pos] is @racket[eof]. In
|
||||
beginning of the file or (byte) string if @racket[pos] is a number, or to the
|
||||
current end of the file or (byte) string if @racket[pos] is @racket[eof]. In
|
||||
position-setting mode, @racket[file-position] raises the
|
||||
@racket[exn:fail:contract] exception for port kinds other than
|
||||
file-stream and string ports. Furthermore, not all @tech{file-stream
|
||||
@tech{file-stream ports} and @tech{string ports}. Furthermore, not all @tech{file-stream
|
||||
ports} support setting the position; if @racket[file-position] is
|
||||
called with a position argument on such a @tech{file-stream port}, the
|
||||
@exnraise[exn:fail:filesystem].
|
||||
|
||||
When @racket[file-position] sets the position @racket[pos] beyond the
|
||||
current size of an output file or string, the file/string is enlarged
|
||||
current size of an output file or (byte) string, the file/string is enlarged
|
||||
to size @racket[pos] and the new region is filled with @racket[0]
|
||||
bytes. If @racket[pos] is beyond the end of an input file or string,
|
||||
bytes. If @racket[pos] is beyond the end of an input file or (byte) string,
|
||||
then reading thereafter returns @racket[eof] without changing the
|
||||
port's position.
|
||||
|
||||
|
|
|
@ -3,26 +3,33 @@
|
|||
|
||||
@title[#:tag "stringport"]{String Ports}
|
||||
|
||||
String input and output ports do not need to be explicitly closed. The
|
||||
@racket[file-position] procedure works for string ports in
|
||||
position-setting mode.
|
||||
A @deftech{string port} reads or writes from a @tech{byte string}. An
|
||||
input @tech{string port} can be created from either a @tech{byte string} or a
|
||||
@tech{string}; in the latter case, the @tech{string} is effectively converted to
|
||||
a @tech{byte string} using @racket[string->bytes/utf-8]. An output @tech{string port}
|
||||
collects output into a @tech{byte string}, but @racket[get-output-string]
|
||||
conveniently converts the accumulated bytes to a @tech{string}.
|
||||
|
||||
Input and output @tech{string ports} do not need to be explicitly
|
||||
closed. The @racket[file-position] procedure works for @tech{string
|
||||
ports} in position-setting mode.
|
||||
|
||||
@defproc[(open-input-bytes [bstr bytes?] [name any/c 'string]) input-port?]{
|
||||
|
||||
Creates an input port that reads characters from @racket[bstr] (see
|
||||
Creates an input @tech{string port} that reads characters from @racket[bstr] (see
|
||||
@secref["bytestrings"]). Modifying @racket[bstr] afterward does not
|
||||
affect the byte stream produced by the port. The optional
|
||||
@racket[name] argument is used as the name for the returned port.}
|
||||
|
||||
@defproc[(open-input-string [str string?] [name any/c 'string]) input-port?]{
|
||||
|
||||
Creates an input port that reads bytes from the UTF-8 encoding (see
|
||||
Creates an input @tech{string port} that reads bytes from the UTF-8 encoding (see
|
||||
@secref["encodings"]) of @racket[str]. The optional @racket[name]
|
||||
argument is used as the name for the returned port.}
|
||||
|
||||
@defproc[(open-output-bytes [name any/c 'string]) output-port?]{
|
||||
|
||||
Creates an output port that accumulates the output into a byte
|
||||
Creates an output @tech{string port} that accumulates the output into a byte
|
||||
string. The optional @racket[name] argument is used as the name for
|
||||
the returned port.}
|
||||
|
||||
|
@ -35,10 +42,10 @@ same as @racket[open-output-bytes].}
|
|||
[end-pos exact-nonnegative-integer? #f])
|
||||
bytes?]{
|
||||
|
||||
Returns the bytes accumulated in @racket[out] so far in a
|
||||
freshly allocated byte string (including any bytes written after the
|
||||
port's current position, if any). The @racket[out] port must be a
|
||||
string output port produced by @racket[open-output-bytes] (or
|
||||
Returns the bytes accumulated in the @tech{string port} @racket[out] so far in a
|
||||
freshly allocated @tech{byte string} (including any bytes written after the
|
||||
port's current position, if any). The @racket[out] port must be an
|
||||
output @tech{string port} produced by @racket[open-output-bytes] (or
|
||||
@racket[open-output-string]) or a structure whose
|
||||
@racket[prop:output-port] property refers to such an output port
|
||||
(transitively).
|
||||
|
|
Loading…
Reference in New Issue
Block a user