1
<?xml version="1.0" encoding="ISO-8859-1"?>
6
====================================================================
8
====================================================================
11
<module name="bufstream">
12
<short>Buffered stream</short>
15
<file>BufStream</file> implements two one-way buffered streams: the streams
16
store all data from (or for) the source stream in a memory buffer, and only
17
flush the buffer when it's full (or refill it when it's empty).
18
The buffer size can be specified at creation time. 2 streams are
19
implemented: <link id="TReadBufStream"/> which is for reading only, and
20
<link id="TWriteBufStream"/> which is for writing only.
23
Buffered streams can help in speeding up read or write operations,
24
especially when a lot of small read/write operations are done: it
25
avoids doing a lot of operating system calls.
29
<!-- unresolved type reference Visibility: default -->
30
<element name="Classes">
31
<short>Stream definitions</short>
34
<!-- unresolved type reference Visibility: default -->
35
<element name="SysUtils">
36
<short>Exception support</short>
39
<!-- constant Visibility: default -->
40
<element name="DefaultBufferCapacity">
41
<short>Default buffer size</short>
43
If no buffer size is specified when the stream is created, then this size is
47
<link id="TBufStream.Create"/>
52
********************************************************************
53
#fcl.bufstream.TBufStream
54
********************************************************************
57
<!-- object Visibility: default -->
58
<element name="TBufStream">
59
<short>Common ancestor for buffered streams</short>
61
<var>TBufStream</var> is the common ancestor for the <link
62
id="TReadBufStream"/> and <link id="TWriteBufStream"/> streams.
63
It completely handles the buffer memory management and position
64
management. An instance of <var>TBufStream</var> should never
65
be created directly. It also keeps the instance of the source stream.
68
<link id="TReadBufStream"/>
69
<link id="TWriteBufStream"/>
73
<!-- constructor Visibility: public -->
74
<element name="TBufStream.Create">
75
<short>Create a new <var>TBufStream</var> instance.</short>
78
<var>Create</var> creates a new <var>TBufStream</var> instance.
79
A buffer of size <var>ACapacity</var> is allocated, and the
80
<var>ASource</var> source (or destination) stream is stored.
81
If no capacity is specified, then <link id="DefaultBufferCapacity"/> is used
85
An instance of <var>TBufStream</var> should never be instantiated
86
directly. Instead, an instance of <link id="TReadBufStream"/> or
87
<link id="TWriteBufStream"/> should be created.
91
If not enough memory is available for the buffer, then an exception may be
95
<link id="TBufStream.Destroy"/>
96
<link id="TReadBufStream"/>
97
<link id="TWriteBufStream"/>
101
<!-- destructor Visibility: public -->
102
<element name="TBufStream.Destroy">
103
<short>Destroys the <var>TBufStream</var> instance</short>
105
<var>Destroy</var> destroys the instance of <var>TBufStream</var>. It
106
flushes the buffer, deallocates it, and then destroys the
107
<var>TBufStream</var> instance.
110
<link id="TBufStream.Create"/>
111
<link id="TReadBufStream"/>
112
<link id="TWriteBufStream"/>
116
<!-- property Visibility: public -->
117
<element name="TBufStream.Buffer">
118
<short>The current buffer</short>
120
<var>Buffer</var> is a pointer to the actual buffer in use.
123
<link id="TBufStream.Create"/>
124
<link id="TBufStream.Capacity"/>
125
<link id="TBufStream.BufferSize"/>
129
<!-- property Visibility: public -->
130
<element name="TBufStream.Capacity">
131
<short>Current buffer capacity</short>
133
<var>Capacity</var> is the amount of memory the buffer occupies.
134
To change the buffer size, the capacity can be set. Note that the
135
capacity cannot be set to a value that is less than the current
136
buffer size, i.e. the current amount of data in the buffer.
139
<link id="TBufStream.Create"/>
140
<link id="TBufStream.Buffer"/>
141
<link id="TBufStream.BufferSize"/>
142
<link id="TBufStream.BufferPos"/>
146
<!-- property Visibility: public -->
147
<element name="TBufStream.BufferPos">
148
<short>Current buffer position.</short>
150
<var>BufPos</var> is the current stream position in the buffer. Depending on
151
whether the stream is used for reading or writing, data will be read from
152
this position, or will be written at this position in the buffer.
155
<link id="TBufStream.Create"/>
156
<link id="TBufStream.Buffer"/>
157
<link id="TBufStream.BufferSize"/>
158
<link id="TBufStream.Capacity"/>
162
<!-- property Visibility: public -->
163
<element name="TBufStream.BufferSize">
164
<short>Amount of data in the buffer</short>
166
<var>BufferSize</var> is the actual amount of data in the buffer. This is
167
always less than or equal to the <link id="TBufStream.Capacity">Capacity</link>.
170
<link id="TBufStream.Create"/>
171
<link id="TBufStream.Buffer"/>
172
<link id="TBufStream.BufferPos"/>
173
<link id="TBufStream.Capacity"/>
178
********************************************************************
179
#fcl.bufstream.TReadBufStream
180
********************************************************************
183
<!-- object Visibility: default -->
184
<element name="TReadBufStream">
185
<short>Read-only buffered stream.</short>
188
<var>TReadBufStream</var> is a read-only buffered stream. It implements the
189
needed methods to read data from the buffer and fill the buffer with
190
additional data when needed.
193
The stream provides limited forward-seek possibilities.
197
<link id="TBufStream"/>
198
<link id="TWriteBufStream"/>
202
<!-- function Visibility: public -->
203
<element name="TReadBufStream.Seek">
204
<short>Set location in the buffer</short>
207
<var>Seek</var> sets the location in the buffer. Currently, only a forward
208
seek is allowed. It is emulated by reading and discarding data. For an
209
explanation of the parameters, see <link id="#rtl.classes.tstream.seek">TStream.Seek"</link>
212
The seek method needs enhancement to enable it to do a full-featured seek.
213
This may be implemented in a future release of Free Pascal.
217
In case an illegal seek operation is attempted, an exception is raised.
220
<link id="TWriteBufStream.Seek"/>
221
<link id="TReadBufStream.Read"/>
222
<link id="TReadBufStream.Write"/>
226
<!-- function Visibility: public -->
227
<element name="TReadBufStream.Read">
228
<short>Reads data from the stream</short>
231
<var>Read</var> reads at most <var>ACount</var> bytes from the stream and
232
places them in <var>Buffer</var>. The number of actually read bytes is
236
<var>TReadBufStream</var> first reads whatever data is still available in
237
the buffer, and then refills the buffer, after which it continues to read
238
data from the buffer. This is repeated untill <var>ACount</var> bytes are
239
read, or no more data is available.
243
<link id="TReadBufStream.Seek"/>
244
<link id="TReadBufStream.Read"/>
248
<!-- function Visibility: public -->
249
<element name="TReadBufStream.Write">
250
<short>Writes data to the stream</short>
252
<var>Write</var> always raises an <var>EStreamError</var> exception, because
253
the stream is read-only. A <link id="TWriteBufStream"/> write stream must be
254
used to write data in a buffered way.
257
<link id="TReadBufStream.Seek"/>
258
<link id="TReadBufStream.Read"/>
263
********************************************************************
264
#fcl.bufstream.TWriteBufStream
265
********************************************************************
268
<!-- object Visibility: default -->
269
<element name="TWriteBufStream">
270
<short>Write-only buffered stream.</short>
273
<var>TWriteBufStream</var> is a write-only buffered stream. It implements the
274
needed methods to write data to the buffer and flush the buffer (i.e., write
275
its contents to the source stream) when needed.
279
<link id="TBufStream"/>
280
<link id="TReadBufStream"/>
284
<!-- destructor Visibility: public -->
285
<element name="TWriteBufStream.Destroy">
286
<short>Remove the <var>TWriteBufStream</var> instance from memory</short>
288
<var>Destroy</var> flushes the buffer and then calls the inherited
289
<link id="TBufstream.Destroy">Destroy</link>.
292
If an error occurs during flushing of the buffer, an exception may be
296
<link id="TBufStream.Create">Create</link>
297
<link id="TBufStream.Destroy"/>
301
<!-- function Visibility: public -->
302
<element name="TWriteBufStream.Seek">
303
<short>Set stream position.</short>
306
<var>Seek</var> always raises an <var>EStreamError</var> exception,
307
except when the seek operation would not alter the current position.
310
A later implementation may perform a proper seek operation by flushing the
311
buffer and doing a seek on the source stream.
317
<link id="TWriteBufStream.Write"/>
318
<link id="TWriteBufStream.Read"/>
319
<link id="TReadBufStream.Seek"/>
323
<!-- function Visibility: public -->
324
<element name="TWriteBufStream.Read">
325
<short>Read data from the stream</short>
327
<var>Read</var> always raises an <var>EStreamError</var>
328
exception since <var>TWriteBufStream</var> is write-only.
329
To read data in a buffered way, <link id="TReadBufStream"/> should be used.
332
<link id="TWriteBufStream.Seek"/>
333
<link id="TWriteBufStream.Write"/>
334
<link id="TReadBufStream.Read"/>
338
<!-- function Visibility: public -->
339
<element name="TWriteBufStream.Write">
340
<short>Write data to the stream</short>
342
<var>Write</var> writes at most <var>ACount</var> bytes from
343
<var>ABuffer</var> to the stream. The data is written to the
344
internal buffer first. As soon as the internal buffer is full, it is flushed
345
to the destination stream, and the internal buffer is filled again. This
346
process continues till all data is written (or an error occurs).
349
An exception may occur if the destination stream has problems writing.
352
<link id="TWriteBufStream.Seek"/>
353
<link id="TWriteBufStream.Read"/>
354
<link id="TReadBufStream.Write"/>
358
</module> <!-- bufstream -->
361
</fpdoc-descriptions>
added
removed
fpcdocs/bufstream.xml
