Cross-Platform C++

ot::io
class FilterReader

#include "ot/io/FilterReader.h"

ot::io::Reader ot::SynchronizedObject ot::ManagedObject A base class that derives from Reader but also contains another Reader which is used as the input source. FilterReader and its sister class FilterWriter provide an extensible framework for building chains of character processing.

The FilterReader class overrides all methods of Reader with versions that pass requests to the contained Reader. Derived classes of FilterReader are expected to further override some of these methods to perform some useful function before the characters are returned to the caller (which may be yet another FilterReader).

Note:
Derived classes that override the any of the read() or readAtomic() methods would be advised to override all the read() and readAtomic() methods in addition to the skip() and skipAtomic() methods. Failure to do so may produce unexpected results as these methods would otherwise be delegated to the contained Reader - perhaps bypassing the required logic.
Multi-threaded considerations:
The contained Reader is used as the lock object for synchronized methods.



Constructor/Destructor Summary
FilterReader(Reader* pReader)
         Constructs a FilterReader using pReader as the contained Reader.

Method Summary
 virtual void close()
         Closes the Reader.
protected  RefPtr< Reader > getReader() const
         Returns a reference to the contained 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.
 virtual IntType read()
         Reads and returns a single CharType character.
 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 void reset()
         Resets the position in the character stream to a previously marked position.
 virtual size_t skip(size_t n)
         Reads and discards n characters.
 virtual size_t skipAtomic(size_t n)
         Reads and discards n Unicode characters;.

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

Methods inherited from class ot::io::Reader
getLock

Methods inherited from class ot::SynchronizedObject
lock, unlock

Constructor/Destructor Detail

FilterReader

 FilterReader(Reader* pReader)
Constructs a FilterReader using pReader as the contained Reader.

Exceptions:
NullPointerException - if pReader is null.

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.

getReader

protected RefPtr< ReadergetReader() const
Returns a reference to the contained Reader.


mark

virtual void mark(size_t readLimit)
Marks the current position in the character stream. Subsequent reset() operations will attempt to re-establish the character stream's position to the marked position.

Supporting mark() implies that the Reader must maintain an internal character buffer containing all the characters read from the point at which mark() was called. The size of this buffer is implementation dependent, but is guaranteed to hold at least readLimit CharType characters before it becomes full. When the buffer limit is exceeded, the marked position is automatically invalidated, with the result that subsequent reset() operations will fail.

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

Parameters:
readLimit - specifies the minimum number of CharType characters that the Reader must return before making the marked position invalid.
Exceptions:
IOException - if the Reader does not support the mark() operation.
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. The FilterReader class contains an implementation that passes the request to the contained Reader.

Returns:
true if the contained Reader supports the mark() operation; false otherwise
See also:
mark() , reset()

read

virtual IntType read()
Reads and returns a single CharType character. Depending on whether CharType is a 32-bit value, reading a single CharType character may not be the same as reading a single Unicode character. See CharEncoding for a detailed explanation of Unicode character encoding within OpenTop.

Returns:
The CharType read or Reader::EndOfFile if the end of the character stream has been reached.
Exceptions:
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.

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.

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.

skip

virtual size_t skip(size_t n)
Reads and discards n characters. This is the equivalent to calling read() n times or until Reader::EndOfFile is returned, which ever comes first.

Note: this method skips up to n occurrences of CharType from the character stream. This is not necessarily the same as skipping n Unicode characters. The skipAtomic() method may be used to skip n Unicode characters.

Parameters:
n - The number of CharType positions to skip
Returns:
the number of CharType positions skipped.
Exceptions:
IOException - if an error occurs while reading from the character stream
See also:
skipAtomic()
Multi-threaded considerations:
Synchronized for safe access from multiple concurrent threads.

skipAtomic

virtual size_t skipAtomic(size_t n)
Reads and discards n Unicode characters;. This is the equivalent to calling readAtomic() n times or until Character::EndOfFileCharacter is returned.

Parameters:
n - The number of integral Unicode character positions to skip
Returns:
the number of Unicode characters skipped.
Exceptions:
IOException - if an error occurs while reading from the character stream
AtomicReadException - if the character stream is not positioned on a Unicode character boundary
See also:
skip()
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