USING: help.markup help.syntax quotations hashtables kernel
classes strings continuations destructors math byte-arrays
-alien ;
+alien specialized-arrays sequences ;
IN: io
ARTICLE: "stream-types" "Binary and text streams"
$io-error ;
HELP: stream-read
-{ $values { "n" "a non-negative integer" } { "stream" "an input stream" } { "seq" { $or byte-array string f } } }
+{ $values { "n" "a non-negative integer" } { "stream" "an input stream" } { "seq/f" { $or byte-array string f } } }
{ $contract "Reads " { $snippet "n" } " elements from the stream. Outputs a truncated string or " { $link f } " on stream exhaustion." }
{ $notes "Most code only works on one stream at a time and should instead use " { $link read } "; see " { $link "stdio" } "." }
$io-error ;
+HELP: stream-read-unsafe
+{ $values { "n" "a non-negative integer" } { "buf" { $or c-ptr string } } { "stream" "an input stream" } { "count" integer } }
+{ $contract "Reads up to " { $snippet "n" } " elements from the stream. The data is stored directly into the buffer provided by " { $snippet "buf" } ", which must be a string (in the case of a character stream) or a byte array, specialized array, or other pointer to memory (in the case of a byte stream). There must be space in the buffer for at least " { $snippet "n" } " elements. Returns the number of elements read from the stream, which will be equal to " { $snippet "n" } " unless the end of the stream is reached. If the stream is exhausted, returns zero." }
+{ $warning "This word does not perform bounds checking on " { $snippet "buf" } ". Most code should use " { $link stream-read } " or " { $link stream-read-into } " instead." }
+$io-error ;
+
+HELP: read-into
+{ $values { "buf" { $or byte-array specialized-array string } } { "buf-slice/f" { $or slice f } } }
+{ $contract "Reads from the current " { $link input-stream } " into the sequence " { $snippet "buf" } ", until either the length of " { $snippet "buf" } " is reached or the stream is exhausted. Returns a " { $link slice } " over the part of " { $snippet "buf" } " that was written to, or " { $link f } " if the stream was exhausted." }
+$io-error ;
+
+HELP: stream-read-into
+{ $values { "buf" { $or byte-array specialized-array string } } { "stream" "an input stream" } { "buf-slice/f" { $or slice f } } }
+{ $contract "Reads from the stream into the sequence " { $snippet "buf" } ", until either the length of " { $snippet "buf" } " is reached or the stream is exhausted. Returns a " { $link slice } " over the part of " { $snippet "buf" } " that was written to, or " { $link f } " if the stream was exhausted." }
+{ $notes "Most code only works on one stream at a time and should instead use " { $link read-into } "; see " { $link "stdio" } "." }
+$io-error ;
+
HELP: stream-read-until
{ $values { "seps" string } { "stream" "an input stream" } { "seq" { $or byte-array string f } } { "sep/f" "a character or " { $link f } } }
{ $contract "Reads elements from the stream, until the first occurrence of a separator character, or stream exhaustion. In the former case, the separator is pushed on the stack, and is not part of the output string. In the latter case, the entire stream contents are output, along with " { $link f } "." }
HELP: stream-read-partial
{ $values
{ "n" "a non-negative integer" } { "stream" "an input stream" }
- { "seq" { $or byte-array string f } } }
+ { "seq/f" { $or byte-array string f } } }
{ $description "Reads at most " { $snippet "n" } " elements from a stream and returns up to that many characters without blocking. If no characters are available, blocks until some are and returns them." } ;
+HELP: stream-read-partial-unsafe
+{ $values { "n" "a non-negative integer" } { "buf" { $or c-ptr string } } { "stream" "an input stream" } { "count" integer } }
+{ $contract "Reads up to " { $snippet "n" } " elements from the stream without blocking. If no data is available immediately on the stream, blocks until data is available. The data is stored directly into the buffer provided by " { $snippet "buf" } ", which must be a string (in the case of a character stream), or a byte array, specialized array, or other pointer to memory (in the case of a byte stream). There must be space in the buffer for at least " { $snippet "n" } " elements. Returns the number of elements read from the stream, or zero if the end of the stream was reached." }
+{ $warning "This word does not perform bounds checking on " { $snippet "buf" } ". Most code should use " { $link stream-read-partial } " or " { $link stream-read-partial-into } " instead." }
+$io-error ;
+
+HELP: read-partial-into
+{ $values { "buf" { $or byte-array specialized-array string } } { "buf-slice/f" { $or slice f } } }
+{ $contract "Reads available data from the current " { $link input-stream } " into the sequence " { $snippet "buf" } " without blocking until all immediately available data is read or the length of " { $snippet "buf" } " is reached. If no data is immediately available, blocks until data is available. Returns a " { $link slice } " over the part of " { $snippet "buf" } " that was written to, or " { $link f } " if the stream was exhausted." }
+$io-error ;
+
+HELP: stream-read-partial-into
+{ $values { "buf" { $or byte-array specialized-array string } } { "stream" "an input stream" } { "buf-slice/f" { $or slice f } } }
+{ $contract "Reads available data from the stream into the sequence " { $snippet "buf" } " without blocking until all immediately available data is read or the length of " { $snippet "buf" } " is reached. If no data is immediately available, blocks until data is available. Returns a " { $link slice } " over the part of " { $snippet "buf" } " that was written to, or " { $link f } " if the stream was exhausted." }
+{ $notes "Most code only works on one stream at a time and should instead use " { $link read-partial-into } "; see " { $link "stdio" } "." }
+$io-error ;
+
HELP: stream-write1
{ $values { "elt" "an element" } { "stream" "an output stream" } }
{ $contract "Writes an element to the stream. If the stream does buffering, output may not be performed immediately; use " { $link stream-flush } " to force output." }
{ $notes "Most code only works on one stream at a time and should instead use " { $link print } "; see " { $link "stdio" } "." }
$io-error ;
+HELP: stream-copy*
+{ $values { "in" "an input stream" } { "out" "an output stream" } }
+{ $description "Copies the contents of one stream into another. The streams are left open when the copy is completed." { $link stream-copy } " will copy the streams and close them on completion." }
+$io-error ;
+
HELP: stream-copy
{ $values { "in" "an input stream" } { "out" "an output stream" } }
-{ $description "Copies the contents of one stream into another, closing both streams when done." }
+{ $description "Copies the contents of one stream into another, closing both streams when done. To copy without closing the streams, use " { $link stream-copy* } "." }
$io-error ;
HELP: stream-tell
{ $description "Returns the index of the stream pointer if the stream is seekable." }
{ $notes "Stream seeking is not supported on streams that do not have a known length, e.g. TCP/IP streams." } ;
-
HELP: stream-seek
{ $values
{ "n" integer } { "seek-type" "a seek singleton" } { "stream" "a stream" }
}
{ $notes "Stream seeking is not supported on streams that do not have a known length, e.g. TCP/IP streams." } ;
+HELP: stream-seekable?
+{ $values
+ { "stream" "a stream" } { "?" boolean }
+}
+{ $description "Returns true if " { $snippet "stream" } " is a seekable stream." }
+{ $notes "Stream seeking is not supported on streams that do not have a known length, e.g. TCP/IP streams." } ;
+
+HELP: stream-length
+{ $values
+ { "stream" "a stream" } { "n/f" "an integer or " { $link f } }
+}
+{ $description "Returns the length of the data supplied by " { $snippet "stream" } ", or " { $link f } " if the stream is not seekable or has unknown length." }
+{ $notes "Stream seeking is not supported on streams that do not have a known length, e.g. TCP/IP streams." } ;
+
HELP: seek-absolute
{ $values
}
{ $description "Seeks to an offset from the current position of the stream pointer." } ;
+{ stream-seek stream-tell stream-seekable? stream-length } related-words
{ seek-absolute seek-relative seek-end } related-words
HELP: seek-input
"These words are required for binary and string input streams:"
{ $subsections
stream-read1
- stream-read
+ stream-read-unsafe
stream-read-until
+ stream-read-partial-unsafe
+}
+"The " { $link stream-read-unsafe } " and " { $link stream-read-partial-unsafe } " words should be implemented by streams but not used by client code. The following safe words are provided for reading from input streams:"
+{ $subsections
+ stream-read
+ stream-read-into
stream-read-partial
+ stream-read-partial-into
}
"This word is only required for string input streams:"
{ $subsections stream-readln }
{ $subsections stream-nl }
"These words are for seekable streams:"
{ $subsections
+ stream-seekable?
stream-tell
stream-seek
tell-input
tell-output
+ stream-length
}
{ $see-also "io.timeouts" } ;
{ $subsections
read1
read
+ read-into
read-until
read-partial
+ read-partial-into
+ readln
}
"If the default input stream is a character stream (" { $link stream-element-type } " outputs " { $link +character+ } "), lines of text can be read:"
{ $subsections readln }
each-block
}
"Copying the contents of one stream to another:"
+{ $subsections stream-copy* }
{ $subsections stream-copy } ;
ARTICLE: "stream-examples" "Stream example"
projects / factor.git / commitdiff