1 ! Copyright (C) 2009 Doug Coleman.
2 ! See http://factorcode.org/license.txt for BSD license.
3 USING: help.markup help.syntax kernel math io ;
8 { "stream" "an input stream" } { "limit" integer } { "mode" { $link stream-throws } " or " { $link stream-eofs } }
9 { "stream'" "an input stream" }
11 { $description "Constructs a new " { $link limited-stream } " from an existing stream. User code should use " { $link limit } " or " { $link limit-input } "." } ;
15 { "stream" "an input stream" } { "limit" integer } { "mode" { $link stream-throws } " or " { $link stream-eofs } }
16 { "stream'" "a stream" }
18 { $description "Changes a decoder's stream to be a limited stream, or wraps " { $snippet "stream" } " in a " { $link limited-stream } "." }
19 { $examples "Throwing an exception:"
21 "USING: continuations io io.streams.limited io.streams.string"
22 "kernel prettyprint ;"
24 " \"123456\" <string-reader> 3 stream-throws limit"
25 " 100 swap stream-read ."
29 "Returning " { $link f } " on exhaustion:"
31 "USING: accessors continuations io io.streams.limited"
32 "io.streams.string kernel prettyprint ;"
33 "\"123456\" <string-reader> 3 stream-eofs limit"
34 "100 swap stream-read ."
41 { "stream" "an input stream" }
42 { "stream'" "a stream" }
44 { $description "Returns the underlying stream of a limited stream." } ;
48 { "value" "a limited-stream class" }
50 { $description "Limited streams wrap other streams, changing their behavior to throw an exception or return " { $link f } " upon exhaustion." } ;
54 { "limit" integer } { "mode" { $link stream-throws } " or " { $link stream-eofs } }
56 { $description "Wraps the current " { $link input-stream } " in a " { $link limited-stream } "." } ;
59 { $description "Returns the underlying stream of the limited-stream stored in " { $link input-stream } "." } ;
63 { "value" { $link stream-throws } " or " { $link stream-eofs } }
65 { $description "If the " { $slot "mode" } " of a limited stream is set to this singleton, the stream will return " { $link f } " upon exhaustion." } ;
69 { "value" { $link stream-throws } " or " { $link stream-eofs } }
71 { $description "If the " { $slot "mode" } " of a limited stream is set to this singleton, the stream will throw " { $link limit-exceeded } " upon exhaustion." } ;
73 { stream-eofs stream-throws } related-words
75 ARTICLE: "io.streams.limited" "Limited input streams"
76 "The " { $vocab-link "io.streams.limited" } " vocabulary wraps a stream to behave as if it had only a limited number of bytes, either throwing an error or returning " { $link f } " upon reaching the end." $nl
77 "Wrap a stream in a limited stream:"
78 { $subsections limit }
79 "Wrap the current " { $link input-stream } " in a limited stream:"
80 { $subsections limit-input }
81 "Unlimits a limited stream:"
82 { $subsections unlimited }
83 "Unlimits the current " { $link input-stream } ":"
84 { $subsections unlimited-input }
85 "Make a limited stream throw an exception on exhaustion:"
86 { $subsections stream-throws }
87 "Make a limited stream return " { $link f } " on exhaustion:"
88 { $subsections stream-eofs } ;
90 ABOUT: "io.streams.limited"