Cross-Platform C++

ot::io
class Reader  (abstract)

#include "ot/io/Reader.h"

ot::SynchronizedObject ot::ManagedObject ot::io::BufferedReader ot::io::FilterReader ot::io::InputStreamReader ot::io::StringReader 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.



Constructor/Destructor Summary
Reader()
         Default constructor.
Reader(SynchronizedObject* pLockObject)
         Constructor taking a SynchronizedObject which will be used as the lock for synchronized functions.

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;.

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

Methods inherited from class ot::SynchronizedObject
lock, unlock

Protected Instance Data Members

m_rpLock

RefPtrMember< SynchronizedObject > m_rpLock


Typedefs

int_type

typedef IntType int_type


unit_type

typedef CharType unit_type

Enumerations

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

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.

getLock

RefPtr< SynchronizedObjectgetLock() 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.


Cross-Platform C++

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

Copyright © 2000-2003 ElCel Technology   Trademark Acknowledgements