basis/io/streams/limited/limited-docs.factor

   1 ! Copyright (C) 2009 Doug Coleman.
   2 ! See https://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax io math ;
   4 IN: io.streams.limited
   5
   6 HELP: <limited-stream>
   7 { $values
   8     { "stream" "an input stream" } { "limit" integer }
   9     { "stream'" "an input stream" }
  10 }
  11 { $description "Constructs a new " { $link limited-stream } " from an existing stream. User code should use " { $link limit-stream } " or " { $link limited-input } "." } ;
  12
  13 HELP: limit-stream
  14 { $values
  15     { "stream" "an input stream" } { "limit" integer }
  16     { "stream'" "a stream" }
  17 }
  18 { $description "Changes a decoder's stream to be a limited stream, or wraps " { $snippet "stream" } " in a " { $link limited-stream } "." }
  19 { $examples
  20     "Limiting a longer stream to length three:"
  21     { $example
  22         "USING: accessors continuations io io.streams.limited"
  23         "io.streams.string kernel prettyprint ;"
  24         "\"123456\" <string-reader> 3 limit-stream"
  25         "100 swap stream-read ."
  26         "\"123\""
  27     }
  28 } ;
  29
  30 HELP: limited-stream
  31 { $values
  32     { "value" "a limited-stream class" }
  33 }
  34 { $description "Limited streams wrap other streams, changing their behavior to throw an exception or return " { $link f } " upon exhaustion." } ;
  35
  36 HELP: limited-input
  37 { $values { "limit" integer } }
  38 { $description "Wraps the current " { $link input-stream } " in a " { $link limited-stream } "." } ;
  39
  40 ARTICLE: "io.streams.limited" "Limited input streams"
  41 "The " { $vocab-link "io.streams.limited" } " vocabulary wraps a stream to behave as if it had only a limited number of bytes. Limiting a seekable stream creates a window of bytes that supports seeking and re-reading of bytes in that window. If it is desirable for a stream to throw an exception upon exhaustion, use the " { $vocab-link "io.streams.throwing" } " vocabulary in conjunction with this one." $nl
  42 "Wrap a stream in a limited stream:"
  43 { $subsections limited-stream }
  44 "Wrap the current " { $link input-stream } " in a limited stream:"
  45 { $subsections limited-input } ;
  46
  47 ABOUT: "io.streams.limited"