Cross-Platform C++

ot::io
class BufferedReader

#include "ot/io/BufferedReader.h"

ot::io::Reader ot::SynchronizedObject ot::ManagedObject A BufferedReader wraps another Reader object and provides buffering as well as support for the mark() and reset() methods and a readLine() method. When the BufferedReader is constructed, an internal buffer is created. The size of the internal buffer can be specified by using the overloaded constructor.

As characters are read, the internal buffer is refilled as necessary from the contained Reader. In this way i/o efficiency can be improved by translating multiple small read operations into one large one.

To improve efficiency and avoid the needless copying of data, if the application performs a read request that is larger than the internal buffer, the internal buffer is empty and there is not a mark() operation outstanding, the internal buffer is bypassed and characters are read directly into the application's buffer.

mark() and reset() are supported by buffering all data after a mark() operation until the readLimit has been exceeded. If mark() is called with a readLimit that is larger than the internal buffer, the buffer is re-allocated to the size requested.

Multi-threaded considerations:
The contained Reader is used as the lock object for synchronized methods.



Constructor/Destructor Summary
BufferedReader(Reader* pReader)
         Constructs a BufferedReader using a default buffer size and pReader as the contained Reader.
BufferedReader(Reader* pReader, size_t size)
         Constructs a BufferedReader with the specified buffer size and pReader as the contained Reader.
~BufferedReader()
         Destroys the internal buffer.

Method Summary
 virtual void close()
         Closes the Reader.
 virtual void mark(size_t readLimit)
         Marks the current position in the character stream.
 virtual bool markSupported() const
         Tests whether the Reader supports the mark() operation, which it does.
 virtual long read(CharType* pBuffer, size_t bufLen)
         Reads up to bufLen characters into the supplied buffer.
 virtual Character readAtomic()
         Reads a single Unicode Character.
 virtual long readAtomic(CharType* pBuffer, size_t bufLen)
         Reads an integral number of Unicode characters into the supplied CharType buffer.
 virtual long readLine(String& ret)
         Reads a line of text into the return parameter ret.
 virtual void reset()
         Resets the position in the character stream to a previously marked position.

Methods inherited from class ot::ManagedObject
addRef, getRefCount, onFinalRelease, operator=, release

Methods inherited from class ot::io::Reader
getLock, read, skip, skipAtomic

Methods inherited from class ot::SynchronizedObject
lock, unlock

Constructor/Destructor Detail

BufferedReader

 BufferedReader(Reader* pReader)
Constructs a BufferedReader using a default buffer size and pReader as the contained Reader.

Parameters:
pReader - the contained Reader
Exceptions:
NullPointerException - if pReader is null

BufferedReader

 BufferedReader(Reader* pReader,
                size_t size)
Constructs a BufferedReader with the specified buffer size and pReader as the contained Reader.

Parameters:
pReader - the contained Reader
size - the size of the internal character buffer
Exceptions:
NullPointerException - if pReader is null

~BufferedReader

virtual ~BufferedReader()
Destroys the internal buffer. Any buffered data that has not been read is lost.


Method Detail

close

virtual void close()
Closes the Reader. Once a Reader is closed, all system resources associated with the Reader are released, preventing any further read(), mark(), reset() or skip() operations. However, further calls to close() have no effect.

Exceptions:
IOException - if an I/O error occurs.
Multi-threaded considerations:
Synchronized for safe access from multiple concurrent threads.

mark

virtual void mark(size_t readLimit)
Marks the current position in the character stream. Subsequent reset() operations will attempt to re-establish the stream's position to the marked position. This is guaranteed to succeed so long as the application does not read more than readLimit character positions.

When the readLimit is exceeded, the marked position is automatically invalidated, with the result that subsequent reset() operations will fail with an IOException.

Only one mark position is maintained by the InputStream. Further calls to mark() will establish a new mark position; reset() can only reset the position to the most recently established mark position.

If the current buffer has less than readLimit character positions available then the buffer is re-organized or reallocated so that is can hold at least readLimit character positions forward from the current position.

Note: remember that a single Unicode character may occupy several character positions.

Parameters:
readLimit - specifies the minimum number of character positions that the BufferedReader must return before making the marked position invalid.
Exceptions:
IOException - if the Reader has been closed
See also:
markSupported() , reset()
Multi-threaded considerations:
Synchronized for safe access from multiple concurrent threads.

markSupported

virtual bool markSupported() const
Tests whether the Reader supports the mark() operation, which it does.

Returns:
always returns true for BufferedReader
See also:
mark() , reset()
Multi-threaded considerations:
Synchronized for safe access from multiple concurrent threads.

read

virtual long read(CharType* pBuffer,
                  size_t bufLen)
Reads up to bufLen characters into the supplied buffer. The CharType characters read into the supplied buffer may not make up an integral number of Unicode characters. For example, in the case where the internal character encoding is UTF-16, if the passed buffer has room for just one CharType, and the next Unicode character is higher than U+FFFF, then only the first half of the UTF-16 surrogate pair will be returned. The second half of the pair will be returned on the next read operation.

Parameters:
pBuffer - A pointer to the buffer into which the characters will be copied. This must be capable of holding at least bufLen CharType positions.
bufLen - The maximum number of CharType characters to read into the passed buffer. If this exceeds the maximum value that can be represented by a long integer, it is reduced to a value that can be so represented.
Returns:
The number of CharType characters read or Reader::EndOfFile if the end of the stream has been reached.
Exceptions:
IllegalArgumentException - if bufLen is zero
NullPointerException - if pBuffer is null
IOException - if an error occurs while reading from the character stream
See also:
readAtomic(CharType*, size_t)
Multi-threaded considerations:
Synchronized for safe access from multiple concurrent threads.

readAtomic

virtual Character readAtomic()
Reads a single Unicode Character. The Character class is capable of representing all Unicode characters up to U+10FFFF.

Returns:
The Character read or Character::EndOfFileCharacter if the end of the stream has been reached.
Exceptions:
AtomicReadException - if the next CharType is not on a character sequence boundary (i.e. a non-atomic read operation has been performed previously which resulted in an incomplete multi-character sequence being read)
IOException - if an error occurs while reading from the character stream
See also:
read()
Multi-threaded considerations:
Synchronized for safe access from multiple concurrent threads.

readAtomic

virtual long readAtomic(CharType* pBuffer,
                        size_t bufLen)
Reads an integral number of Unicode characters into the supplied CharType buffer. Reads as many characters that are available and that will fit into the supplied CharType buffer. Unicode characters that are encoded internally into multi-character sequences are either read in their entirety or not at all.

A return value of zero indicates that the supplied buffer was not large enough to hold the multi-character sequence for one Unicode character.

Parameters:
pBuffer - A pointer to the buffer into which the characters will be copied. This must be capable of holding at least bufLen CharType positions.
bufLen - The maximum number of CharType characters to read into the passed buffer. If this exceeds the maximum value that can be represented by a long integer, it is reduced to a value that can be so represented.
Returns:
The number of CharType characters read or Reader::EndOfFile if the end of the stream has been reached.
Exceptions:
IllegalArgumentException - if bufLen is zero
NullPointerException - if pBuffer is null
AtomicReadException - if the next CharType is not on a character sequence boundary (i.e. a non-atomic read operation has been performed previously which resulted in an incomplete multi-character sequence being read)
IOException - if an error occurs while reading from the character stream
See also:
readAtomic()
Multi-threaded considerations:
Synchronized for safe access from multiple concurrent threads.

readLine

virtual long readLine(String& ret)
Reads a line of text into the return parameter ret. A line is considered to be terminated by any one of a line feed ('\n'), a carriage return ('\r'), a carriage return followed immediately by a linefeed or when the end of the character stream is reached.

Returns:
the number of CharType characters read or Reader::EndOfFile if the end of the character stream is reached before any characters have been read.
Exceptions:
IOException - if an I/O error occurs.
Multi-threaded considerations:
Synchronized for safe access from multiple concurrent threads.

reset

virtual void reset()
Resets the position in the character stream to a previously marked position. It is permitted to call reset() multiple times. Each time it is called, the position will be reset to the position established by the most recent mark() operation.

Exceptions:
IOException - if mark() is not supported
IOException - if the Reader is closed
IOException - if mark() was not successfully called or the internal character buffer has been exhausted (i.e. the readLimit specified in the mark() call has been exceeded)
See also:
mark()
Multi-threaded considerations:
Synchronized for safe access from multiple concurrent threads.


Cross-Platform C++

Found a bug or missing feature? Please email us at support@elcel.com

Copyright © 2000-2003 ElCel Technology   Trademark Acknowledgements