2 * ----------------------------------------------------------------------
7 (* A netstream is an input channel that is read block by block. The
8 * fragment of the channel currently loaded into memory is called the
9 * current window of the netstream.
13 * 0 window_position current_length EOS
14 * +------------------+-------------------+--------------------------+
15 * ====================
18 * window_length = current_length - window_position
20 * There is an automatism that the window has a certain length. If possible,
21 * the window is at least twice the block size long, where a "block" is
22 * the amount of data that is read from the input channel in one step.
24 * (The idea is that you choose as block size the number of bytes you want
25 * to analyze at once, and which must be loaded into memory. You can start
26 * your analysis at window_position and proceed until window_position +
27 * blocksize without having to check whether your window is large enough.
28 * Only when the first blocksize bytes of the window are already processed,
29 * the window must be enlarged by loading the next block.)
31 * If you want that the window becomes larger, you can call 'want' (to
32 * enlarge the window to a certain size) or 'want_another_block' (to load
33 * just another block from the input channel). Note that this affects only
34 * the current window and not future windows.
36 * If you do not need the first n bytes of the window anymore, you can
37 * call 'move' to move the beginning of the window by n bytes. If the
38 * window becomes too small after this operation, it is enlarged until
39 * it has twice the block size or until it reaches EOS.
44 val create_from_channel : in_channel -> int option -> int -> t
45 (* create_from_channel ch maxlength blocksize:
46 * The new netstream reads from the channel 'ch'. If maxlength = None,
47 * the channel is read until EOF. If maxlength = Some n, at most n bytes
48 * are read; i.e. the netstream reads until n bytes have been read or
49 * until EOF has been reached, whatever comes first. The blocksize
50 * specifies the number of bytes to read at once.
53 val create_from_string : string -> t
54 (* Creates a new netstream from a string. The initial window of this
55 * netstream is a copy of the passed string.
58 val block_size : t -> int
59 (* Returns the (immutable) block size. *)
61 val current_length : t -> int
62 (* Returns the number of bytes read so far. *)
64 val at_eos : t -> bool
65 (* True iff EOS (end of stream) is reached, i.e. the last byte of the
66 * window is the last byte of the stream.
69 val window_position : t -> int
70 (* Returns the absolute position of the current window. *)
72 val window_length : t -> int
73 (* Returns the length of the current window. *)
75 val window : t -> Netbuffer.t
76 (* Returns the current window. *)
78 val move : t -> int -> unit
80 * Moves the window: The first n bytes of the current window are
81 * discarded. If the window would become smaller than twice the
82 * blocksize and if the end of the stream is not yet reached, another
83 * block is read from the input channel and appended to the window.
86 * - n <= window_length
89 val want : t -> int -> unit
91 * If the window is smaller than n bytes, it is tried to enlarge
92 * the window such that it is at least n bytes long. The enlargement
93 * is not possible if the stream is not long enough; in this case
94 * the window becomes as large as possible.
97 val want_another_block : t -> unit
98 (* Enlarges the window by another block (if possible i.e. if the stream
102 val print_stream : t -> unit
104 (* ======================================================================
108 * Revision 1.1 2000/11/17 09:57:27 lpadovan
111 * Revision 1.2 2000/06/24 20:20:33 gerd
112 * Added the toploop printer.
114 * Revision 1.1 2000/04/15 13:07:48 gerd