ot::io
class Reader (abstract)
#include "ot/io/Reader.h"
Abstract class for reading a Unicode character stream.
Concrete sub-classes of Reader may be used to translate byte sequences from an InputStream into sequences of Unicode characters. In this case, an instance of CodeConverter may be used to translate between bytes and Unicode characters.
Depending on the configuration chosen, Unicode characters may be represented internally using 32-bit UCS-4 characters, 16-bit UTF-16 characters or 8-bit UTF-8 characters. See SystemCodeConverter for further information.
The Reader interface mirrors InputStream, but deals in characters where InputStream deals in bytes.
- Multi-threaded considerations:
-
As shown on the inheritance graph, Reader derives from SynchronizedObject, which gives it the ability to protect its internal state from concurrent access from multiple threads. All public methods are synchronized for safe concurrent access.
Method Summary
|
virtual void |
close()
Closes the Reader. |
RefPtr< SynchronizedObject > |
getLock() const
Returns a reference to the SynchronizedObject used for controlling access to synchronized methods. |
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)=0
Reads up to bufLen characters into the supplied buffer. |
virtual Character |
readAtomic()=0
Reads a single Unicode Character. |
virtual long |
readAtomic(CharType* pBuffer, size_t bufLen)=0
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;. |
Protected Instance Data Members |
m_rpLock
RefPtrMember< SynchronizedObject > m_rpLock
int_type
typedef IntType int_type
unit_type
typedef CharType unit_type
enum { |
EndOfFile = -1} |
/* End of character stream reached */ |
Constructor/Destructor Detail |
Reader
Reader()
-
Default constructor.
Reader
Reader(SynchronizedObject* pLockObject)
-
Constructor taking a SynchronizedObject which will be used as the lock for synchronized functions.
- Exceptions:
NullPointerException
-
if pLockObject is null
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.
getLock
RefPtr< SynchronizedObject > getLock() const
-
Returns a reference to the SynchronizedObject used for controlling access to synchronized methods.
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 base class contains an implementation that always returns false.
- Returns:
-
true if the Reader supports the mark() operation; false otherwise
- See also:
-
mark() , reset()
- Multi-threaded considerations:
-
Synchronized for safe access from multiple concurrent threads.
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)=0
-
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()=0
-
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)=0
-
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.
Found a bug or missing feature? Please email us at support@elcel.com