Represents a text output stream. More...

#include <jem/io/Writer.h>

Inherits jem::Object, and jem::io::TextOutput.

Inherited by jem::io::BufferedWriter, jem::io::FilterWriter, jem::io::NullWriter, jem::io::OutputStreamWriter, jem::io::PrefixWriter, jem::io::PrintWriter, jem::io::StderrWriter, jem::io::StdoutWriter, jem::io::StringWriter, jem::io::TeeWriter, and jem::mt::ThreadSafeWriter.

Public Member Functions
virtual void	lock ()
	Locks this output stream. More...

virtual void	unlock ()
	Unlocks this output stream. More...

virtual int	poll ()
	Returns the number of characters that can be written without blocking. More...

virtual void	close ()
	Closes this output stream. More...

virtual void	flush ()
	Writes any buffered data to this output stream. More...

virtual void	write (int c, int n)
	Writes multiple copies of a character to this output stream. More...

virtual void	write (const char *buf, int n)
	Writes an array of characters to this output stream. More...

virtual void	writeNoThrow (const char *buf, int n)
	Writes a character array without throwing an exception. More...

virtual void	printByte (byte b)
	Prints a formatted byte to this output stream. More...

virtual void	printBool (bool b)
	Prints a formatted bool to this output stream. More...

virtual void	printInt (long i)
	Prints a formatted integer to this output stream. More...

virtual void	printFloat (double d)
	Prints a formatted double to this output stream. More...

Public Member Functions inherited from jem::Object
virtual Class *	getClass () const
	Returns the `Class` instance representing the runtime class of this object. More...

virtual String	toString () const
	Returns a short textual description of this object. More...

virtual long	hashValue () const
	Returns a hash value for this object. More...

virtual bool	equals (const Ref< Object > &obj) const
	Tests whether two objects are equal. More...

Ref< Object >	clone () const
	Returns a copy of this object. More...

Public Member Functions inherited from jem::io::TextOutput
virtual void	write (int c)=0
	Writes a single character to this output stream. More...

Additional Inherited Members
Static Public Member Functions inherited from jem::Object
static Class *	getType ()
	Returns the `Class` instance representing the `Object` class. More...

Protected Member Functions inherited from jem::Collectable
	Collectable ()
	Creates an empty `Collectable`. More...

	~Collectable ()
	Frees resources. More...

Protected Member Functions inherited from jem::Interface
virtual	~Interface ()
	Empty destructor. More...

Related Functions inherited from jem::io::TextOutput
TextOutput &	operator<< (TextOutput &out, bool b)
	Prints a boolean to a text output stream. More...

TextOutput &	operator<< (TextOutput &out, byte b)
	Prints a byte to a text output stream. More...

TextOutput &	operator<< (TextOutput &out, char c)
	Prints a character to a text output stream. More...

TextOutput &	operator<< (TextOutput &out, short i)
	Prints a short integer to a text output stream. More...

TextOutput &	operator<< (TextOutput &out, int i)
	Prints an integer to a text output stream. More...

TextOutput &	operator<< (TextOutput &out, long i)
	Prints a long integer to a text output stream. More...

TextOutput &	operator<< (TextOutput &out, float f)
	Prints a float to a text output stream. More...

TextOutput &	operator<< (TextOutput &out, double d)
	Prints a double to a text output stream. More...

TextOutput &	operator<< (TextOutput &out, const char *s)
	Prints a string to a text output stream. More...

TextOutput &	operator<< (TextOutput &out, TextOutput &(*manip)(TextOutput &))
	Applies a manipulator function to a text output stream. More...

TextOutput &	endl (TextOutput &out)
	Writes a newline to a text output stream. More...

Detailed Description

The Writer class implements the TextOutput interface and provides various additional member functions for operating on text output streams. Since the Writer class also extends the Object class, Writer instances are subjected to garbage collection.

See also: Reader.

Examples:: alloc.cpp, Array.cpp, BitSet.cpp, Database.cpp, DataParser.cpp, Properties.cpp, String.cpp, System.cpp, and Tuple.cpp.

Member Function Documentation

virtual void jem::io::Writer::lock ( )

virtual

This function locks this Writer object so that only the current thread can write to the output stream. All other threads calling this function will be blocked until the current thread calls the unlock() member function.

The lock() and unlock() member functions are guaranteed to be recursive. This means that a thread may call lock() multiple times without creating a deadlock situation. Each call to lock() must be balanced by a call to unlock() to ensure that this Writer instance does not become permanently inaccessible to other threads.

The lock() function does not have to lock this object. In fact, the default implementation provided by the Writer class does nothing. It is up to you to instantiate a class derived from the Writer class that implements an appropriate locking scheme.

See also: Lock, IOMutex, ThreadSafeWriter.

Reimplemented in jem::mt::ThreadSafeWriter.

virtual void jem::io::Writer::unlock ( )

virtual

Unlocks this Writer object so that it can be accessed by other threads.

The default implementation provided by the Writer class does nothing.

Precondition: This object has been locked by a call to the lock() member function.

Reimplemented in jem::mt::ThreadSafeWriter.

virtual int jem::io::Writer::poll ( )

virtual

Returns the number of characters that can be written to this output stream without having to wait until the underlying device has become ready for writing. If you write more characters you may have to wait an unspecified amount of time before the write operation is completed.

Note that a call to one of the write() functions is not guaranteed to block if more characters are written than the number returned by this function.

Also note that if another thread writes to this stream after calling the poll() function, the current thread may no longer be able to write the returned number of characters without blocking. Use the lock() member function to avoid these types of situations.

The default implementation provided by the Writer class always returns zero.

Returns: The number of characters that can be written without blocking.

Exceptions

IOException - if an I/O error occurs.

virtual void jem::io::Writer::close ( )

virtual

Closes this output stream. After calling this function, one should not attempt to write any more characters to the stream.

The default implementation provided by the Writer class does nothing.

Exceptions

IOException - if an I/O error occurs.

Reimplemented in jem::mt::ThreadSafeWriter, jem::io::PrintWriter, jem::io::PrefixWriter, jem::io::BufferedWriter, jem::io::OutputStreamWriter, jem::io::TeeWriter, jem::io::FilterWriter, jem::io::StderrWriter, and jem::io::StdoutWriter.

virtual void jem::io::Writer::flush ( )

virtual

Writes any buffered characters to this output stream.

The default implementation provided by the Writer class does nothing.

Exceptions

IOException - if an I/O error occurs.

Reimplemented in jem::mt::ThreadSafeWriter, jem::io::PrintWriter, jem::io::PrefixWriter, jem::io::BufferedWriter, jem::io::OutputStreamWriter, jem::io::TeeWriter, jem::io::FilterWriter, jem::io::StderrWriter, and jem::io::StdoutWriter.

Examples:: System.cpp, and TextInput.cpp.

virtual void jem::io::Writer::write	(	int	c,
		int	n
	)

virtual

Writes n copies of the integer c, cast to an unsigned char, to this output stream.

The default implementation provided by the Writer class repeatedly calls the write(int) member function. Derived classes are encouraged to provide a more efficient implementation.

Parameters

c	- the character to be written.
n	- the number of copies of the character c to be written.

Precondition: n >= 0

Exceptions

IOException - if an I/O error occurs.

Implements jem::io::TextOutput.

virtual void jem::io::Writer::write	(	const char *	buf,
		int	n
	)

virtual

Writes the first n characters stored in the array buf to this output stream.

The default implementation provided by the Writer class repeatedly calls the write(int) member function. Derived classes are encouraged to provide a more efficient implementation.

Parameters

buf	- a character array of which the length is at least n.
n	- the number of characters to be written.

Precondition: n >= 0
and the array buf is at least n characters long.

Postcondition: The characters buf[0], ..., buf[n - 1] have been written to this output stream.

Exceptions

IOException - if an I/O error occurs.

Implements jem::io::TextOutput.

virtual void jem::io::Writer::writeNoThrow	(	const char *	buf,
		int	n
	)

virtual

Writes the first n characters stored in the array buf to this output stream and tries not to throw an exception. The idea is that this member function can be safely called from the destructor of a class (to empty its buffers, for instance).

Note that there is no guarantee that this function does not throw an exception, since that may not always be possible. However, a well behaved implementation should avoid throwing exceptions whenever that is possible.

The default implementation provided by the Writer class simply calls write ( buf, n ).

Parameters