Cross-Platform C++

ot::io
class OutputStreamWriter

#include "ot/io/OutputStreamWriter.h"

ot::io::Writer ot::SynchronizedObject ot::ManagedObject An OutputStreamWriter uses an instance of the CodeConverter class to translate Unicode characters into sequences of bytes and writes these bytes to an underlying OutputStream. The encoding of the underlying byte stream may be specified by name or by directly providing an instance of a CodeConverter. If no encoding is specified the system will use a default encoding.

A CodeConverter can be configured to behave in one of two specified ways when it encounters a Unicode character that cannot be mapped into the target encoding. By default, unmappable characters are silently dealt with by replacing the character with a default replacement character. A stricter scheme is also available that treats unmappable characters as non-recoverable errors and throws an UnmappableCharacterException. Overloaded versions of the OutputStreamWriter constructors can be used to explicitly set the required policy.

To improve efficiency, the OutputStreamWriter contains a byte buffer into which it encodes Unicode characters. It is only when the buffer fills or one of the flush() methods are called that the bytes are actually written to the underlying byte stream.

See the description of InputStreamReader for a sample piece of code that uses an OutputStreamWriter.

Multi-threaded considerations:
As shown on the inheritance graph, OutputStreamWriter 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.
See also:
InputStreamReader



Constructor/Destructor Summary
OutputStreamWriter(OutputStream* pOutputStream)
         Constructs an OutputStreamWriter with pOutputStream as the contained OutputStream.
OutputStreamWriter(OutputStream* pOut, const String& encoding)
         Constructs an OutputStreamWriter with pOutputStream as the contained OutputStream and encoding as the specified encoding name.
OutputStreamWriter(OutputStream* pOut, CodeConverter* pEncoder)
         Constructs an OutputStreamWriter with pOutputStream as the contained OutputStream and @pEncoder as the CodeConverter which will encode Unicode characters into bytes for the underlying output stream.
OutputStreamWriter(OutputStream* pOut, const String& encoding, bool bStrict)
         Constructs an OutputStreamWriter with pOutputStream as the contained OutputStream and encoding as the specified encoding name.
~OutputStreamWriter()
         The destructor flushes the byte buffer to the underlying OutputStream before freeing resources associated with this OutputStreamWriter.

Method Summary
 virtual void close()
         Closes the character stream, flushing it first.
 virtual void flush()
         Flushes any output buffers before forcing the output to its final destination.
 virtual void flushBuffers()
         If this Writer maintains an output buffer, the buffer is emptied and written to the output destination without requesting the final destination to flush the output.
 RefPtr< CodeConverter > getEncoder() const
         Returns a reference to the CodeConverter employed by this OutputStreamWriter.
 String getEncoding() const
         Returns the canonical name of the encoding employed by the underlying byte stream.
 virtual void write(const CharType* pBuf, size_t len)
         Writes an array of CharType characters.

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

Methods inherited from class ot::SynchronizedObject
lock, unlock

Methods inherited from class ot::io::Writer
getLock, write, write, write

Constructor/Destructor Detail

OutputStreamWriter

 OutputStreamWriter(OutputStream* pOutputStream)
Constructs an OutputStreamWriter with pOutputStream as the contained OutputStream. The OutputStream will be encoded using the default CodeConverter returned from the CodeConverterFactory. Unmappable characters will be silently converted into replacement characters.

Parameters:
pOutputStream - the contained OutputStream.
Exceptions:
NullPointerException - if pOutputStream is null.
See also:
cvt::CodeConverterFactory::getDefaultConverter()

OutputStreamWriter

 OutputStreamWriter(OutputStream* pOut,
                    const String& encoding)
Constructs an OutputStreamWriter with pOutputStream as the contained OutputStream and encoding as the specified encoding name. The OutputStream will be encoded using a CodeConverter obtained from the CodeConverterFactory. Unmappable characters will be silently converted into replacement characters.

Parameters:
pOutputStream - the contained OutputStream.
encoding - the name of the encoding (e.g. "UTF-8")
Exceptions:
NullPointerException - if pOutputStream is null.
UnsupportedEncodingException - if the CodeConverterFactory is unable to create a CodeConverter for the specified encoding

OutputStreamWriter

 OutputStreamWriter(OutputStream* pOut,
                    CodeConverter* pEncoder)
Constructs an OutputStreamWriter with pOutputStream as the contained OutputStream and @pEncoder as the CodeConverter which will encode Unicode characters into bytes for the underlying output stream. The policy for dealing with unmappable characters can be specified using the CodeConverter::setUnmappableCharAction() method.

Parameters:
pOutputStream - the contained OutputStream.
pEncoder - the CodeConverter to use for encoding Unicode characters into bytes
Exceptions:
NullPointerException - if either pOutputStream or pEncoder is null.

OutputStreamWriter

 OutputStreamWriter(OutputStream* pOut,
                    const String& encoding,
                    bool bStrict)
Constructs an OutputStreamWriter with pOutputStream as the contained OutputStream and encoding as the specified encoding name. The OutputStream will be encoded using a CodeConverter obtained from the CodeConverterFactory. The policy for the treatment of malformed byte sequences is specified using the bStrict parameter.

Parameters:
pOutputStream - the contained OutputStream.
encoding - the name of the encoding (e.g. "UTF-8")
bStrict - when true, the CodeConverter is instructed to throw an UnmappableCharacterException when it encounters a Unicode character that cannot be encoded into the specified byte encoding; otherwise unmappable characters are silently converted into a replacement character
Exceptions:
NullPointerException - if pOutputStream is null.
UnsupportedEncodingException - if the CodeConverterFactory is unable to create a CodeConverter for the specified encoding

~OutputStreamWriter

virtual ~OutputStreamWriter()
The destructor flushes the byte buffer to the underlying OutputStream before freeing resources associated with this OutputStreamWriter. The underlying OutputStream is not explicitly closed, but it will be automatically closed when no further references to it exist.


Method Detail

close

virtual void close()
Closes the character stream, flushing it first.

Multi-threaded considerations:
Synchronized for safe access from multiple concurrent threads.

flush

virtual void flush()
Flushes any output buffers before forcing the output to its final destination.

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

flushBuffers

virtual void flushBuffers()
If this Writer maintains an output buffer, the buffer is emptied and written to the output destination without requesting the final destination to flush the output. The base class implementation does nothing.

See also:
flush()
Multi-threaded considerations:
Synchronized for safe access from multiple concurrent threads.

getEncoder

RefPtr< CodeConvertergetEncoder() const
Returns a reference to the CodeConverter employed by this OutputStreamWriter.

Multi-threaded considerations:
Synchronized for safe access from multiple concurrent threads.

getEncoding

String getEncoding() const
Returns the canonical name of the encoding employed by the underlying byte stream.

Multi-threaded considerations:
Synchronized for safe access from multiple concurrent threads.

write

virtual void write(const CharType* pBuf,
                   size_t len)
Writes an array of CharType characters.

Parameters:
pStr - a pointer to the first CharType character in the array
len - the number of CharType characters to write
Exceptions:
IOException - if an I/O error occurs.
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