Falcon::Stream Class Reference

Base class for file and filelike services. More...

#include <stream.h>

Inheritance diagram for Falcon::Stream:

List of all members.

Public Types

Public Member Functions

bool bad () const

virtual FalconData * clone () const

Clones the stream.

virtual bool close ()

Close target stream.

void discardReadAhead (uint32 count=0)

Discards ungetted and read ahead characters.

bool eof () const

bool error () const

virtual bool errorDescription (::Falcon::String &description) const

virtual bool flush ()

Flushes stream buffers.

virtual void gcMark (uint32 mark)

virtual bool get (uint32 &chr)=0

Gets next character from the stream.

bool good () const

bool interrupted () const

bool invalid () const

virtual bool isStreamBuffer () const

virtual bool isTranscoder () const

virtual int64 lastError () const

uint32 lastMoved () const

bool open () const

virtual bool put (uint32 chr)

Writes a character on the stream.

virtual int32 read (void *buffer, int32 size)

Reads from target stream.

bool readAhead (String &target, uint32 size)

Read a string but don't remove from get().

bool readAhead (uint32 &chr)

Read a character but don't remove from get().

virtual int32 readAvailable (int32 msecs_timeout, const Sys::SystemData *sysData=0)

Determines if the stream can be read, possibly with a given timeout.

virtual bool readString (String &target, uint32 size)

Gets a whole string from the stream.

void reset ()

virtual int64 seek (int64 pos, e_whence w)

int64 seekBegin (int64 pos)

int64 seekCurrent (int64 pos)

int64 seekEnd (int64 pos)

void status (t_status s)

virtual t_status status () const

Stream (const Stream &other)

virtual int64 tell ()

virtual bool truncate (int64 pos=-1)

t_streamType type () const

void unget (const String &target)

Ungets a whole string.

void unget (uint32 chr)

Write a character in the readahead buffer.

bool unsupported () const

virtual int32 write (const void *buffer, int32 size)

Write to the target stream.

virtual int32 writeAvailable (int32 msecs_timeout, const Sys::SystemData *sysData=0)

Determines if the stream can be written, possibly with a given timeout.

virtual bool writeString (const String &source, uint32 begin=0, uint32 end=csh::npos)

Writes a string on the stream.

virtual ~Stream ()

Protected Types

enum e_whence { ew_begin, ew_cur, ew_end }

Protected Member Functions

bool bufferEmpty () const

Returns true if the buffer is empty.

bool popBuffer (uint32 &chr)

Pops next character from the buffer.

void pushBuffer (uint32 chr)

Push a character in the read ahead buffer.

Stream (t_streamType streamType)

Initializes the base file class.

Protected Attributes

int32 m_lastMoved

uint32 * m_rhBuffer

uint32 m_rhBufferPos

uint32 m_rhBufferSize

t_status m_status

t_streamType m_streamType

Friends

class Transcoder

Detailed Description

Base class for file and filelike services.

This class is used by all the I/O in Falcon libraries and modules.

Subclassess to store or read data from standard streams, files and memory buffers are already provided; the implementors may extend this class or the derived classes to support more systems and/or special I/O devices.

This is a purely abstract class that serves as a base class for system-specific or system independent implementations.

Member Enumeration Documentation

enum Falcon::Stream::e_whence [protected]

Enumerator:

ew_begin
ew_cur
ew_end

enum Falcon::Stream::t_status

Enumerator:

t_none
t_open
t_eof
t_error
t_unsupported
t_invalid
t_interrupted

enum Falcon::Stream::t_streamType

Protected constructor.

Transcoder constructor of this class and of all subclassess is guaranteed not to use the stream in any way but to store it in a protected member; so it is actually possible to switch streams after creation, or to pass 0 as stream initially. Just, be sure YOU KNOW WHAT YOU ARE DOING, as switching streams on stateful encoders may be a bad idea, as it may be a bad idea to create a transcoder passing a 0 stream to it.

Also, there's nowhere any control about the stream not being null before calling parsing functions, so be carefull.

Enumerator:

t_undefined
t_file
t_stream
t_membuf
t_network
t_proxy

Constructor & Destructor Documentation

Falcon::Stream::Stream ( t_streamType streamType ) [inline, protected]

Initializes the base file class.

Falcon::Stream::Stream ( const Stream & other )

virtual Falcon::Stream::~Stream ( ) [virtual]

Member Function Documentation

bool Falcon::Stream::bad ( ) const [inline]

References status(), t_error, t_invalid, and t_unsupported.

bool Falcon::Stream::bufferEmpty ( ) const [inline, protected]

Returns true if the buffer is empty.

virtual FalconData* Falcon::Stream::clone ( ) const [virtual]

Clones the stream.

This version returns 0 and sets error to unsupported; subclasses must properly clone the stream.

Implements Falcon::FalconData.

Reimplemented in Falcon::BaseFileStream, Falcon::ROStringStream, Falcon::StreamBuffer, Falcon::StringStream, Falcon::TranscoderEOL, Falcon::TranscoderByte, Falcon::TranscoderUTF8, and Falcon::TranscoderUTF16.

virtual bool Falcon::Stream::close ( ) [virtual]

Close target stream.

Reimplemented in Falcon::BaseFileStream, Falcon::ROStringStream, Falcon::StreamBuffer, Falcon::StringStream, and Falcon::Transcoder.

void Falcon::Stream::discardReadAhead ( uint32 count = 0 )

Discards ungetted and read ahead characters.

If the lexer finds that it would be useless to retreive again the read ahead characters, it can use this function to discard the content of the buffer instead of re-reading and ignoring them.

However, this can be done only if the final application has a state memory of what is happening, as there may be some ungetted or read ahaead strings that the code portion calling this function may not be aware of.

In that case, the caller should know the amount of character it has read ahead and pass as parameter for this function.

Parameters:

count

number of character to discard from read ahead buffer (0 for all).

bool Falcon::Stream::eof ( ) const [inline]

References status(), and t_eof.

bool Falcon::Stream::error ( ) const [inline]

References status(), and t_error.

virtual bool Falcon::Stream::errorDescription ( ::Falcon::String & description ) const [virtual]

Reimplemented in Falcon::BaseFileStream, Falcon::StreamBuffer, Falcon::StringStream, and Falcon::Transcoder.

virtual bool Falcon::Stream::flush ( ) [virtual]

Flushes stream buffers.

Hook for buffered streams.

Reimplemented in Falcon::StreamBuffer, and Falcon::Transcoder.

virtual void Falcon::Stream::gcMark ( uint32 mark ) [inline, virtual]

Implements Falcon::FalconData.

Reimplemented in Falcon::StringStream.

virtual bool Falcon::Stream::get ( uint32 & chr ) [pure virtual]

Gets next character from the stream.

Subclasses must manage both stateful transcoding and properly popping readahead characters from the buffer.

Returns:: true if the character is available, false on stream end or error.

Implemented in Falcon::BaseFileStream, Falcon::StreamBuffer, Falcon::StringStream, Falcon::TranscoderEOL, Falcon::TranscoderByte, Falcon::TranscoderUTF8, and Falcon::TranscoderUTF16.

bool Falcon::Stream::good ( ) const [inline]

References status(), t_error, t_invalid, and t_unsupported.

bool Falcon::Stream::interrupted ( ) const [inline]

References status(), and t_interrupted.

bool Falcon::Stream::invalid ( ) const [inline]

References status(), and t_invalid.

virtual bool Falcon::Stream::isStreamBuffer ( ) const [inline, virtual]

Reimplemented in Falcon::StreamBuffer.

virtual bool Falcon::Stream::isTranscoder ( ) const [inline, virtual]

Reimplemented in Falcon::Transcoder.

virtual int64 Falcon::Stream::lastError ( ) const [virtual]

Reimplemented in Falcon::BaseFileStream, Falcon::StreamBuffer, Falcon::StringStream, and Falcon::Transcoder.

uint32 Falcon::Stream::lastMoved ( ) const [inline]

bool Falcon::Stream::open ( ) const [inline]

References status(), and t_open.

bool Falcon::Stream::popBuffer ( uint32 & chr ) [protected]

Pops next character from the buffer.

If the buffer is not still constructed, or if its empty, the functionr returns false.

Parameters:

chr

the character that will be retreived.

Returns:: false if buffer empty.

void Falcon::Stream::pushBuffer ( uint32 chr ) [protected]

Push a character in the read ahead buffer.

If the buffer is not still constructed, it is constructed here.

Parameters:

chr

the char to be pushed.

virtual bool Falcon::Stream::put ( uint32 chr ) [virtual]

Writes a character on the stream.

Parameters:

chr

the character to write.

Returns:: true success, false on stream error.

Reimplemented in Falcon::BaseFileStream, Falcon::StreamBuffer, Falcon::StringStream, Falcon::TranscoderEOL, Falcon::TranscoderByte, Falcon::TranscoderUTF8, and Falcon::TranscoderUTF16.

virtual int32 Falcon::Stream::read	(	void *	buffer,
		int32	size
	)			`[virtual]`

Reads from target stream.

Parameters:

	buffer	the buffer where read data will be stored.
	size	the amount of bytes to read

Reimplemented in Falcon::BaseFileStream, Falcon::OutputStream, Falcon::StreamBuffer, Falcon::StringStream, and Falcon::Transcoder.

bool Falcon::Stream::readAhead	(	String &	target,
		uint32	size
	)

Read a string but don't remove from get().

Every character in the returned string will still be read by other get() operations; this allows to "peek" forward a bit in the target stream to i.e. take lexer decisions that won 't affect a parser.

The target string may be shorter than required if the stream ends before all the characters are read, or in case of error.

Parameters:

	target	the read string
	size	the amount of character to be read.

Returns:: false on stream end or error.

bool Falcon::Stream::readAhead ( uint32 & chr )

Read a character but don't remove from get().

This function is equivalent to:

         Stream *s = ...
         Transcoder xss );
         uint32 chr;
         x.get( chr );
         x.unget( chr );

Parameters:

chr

the read character

Returns:: false on stream end or error.

virtual int32 Falcon::Stream::readAvailable	(	int32	msecs_timeout,
		const Sys::SystemData *	sysData = `0`
	)			`[virtual]`

Determines if the stream can be read, possibly with a given timeout.

If sysData is not zero, it will be used to honor concurrent interrupt requests.

Reimplemented in Falcon::BaseFileStream, Falcon::StreamBuffer, Falcon::StringStream, and Falcon::Transcoder.

virtual bool Falcon::Stream::readString	(	String &	target,
		uint32	size
	)			`[virtual]`

Gets a whole string from the stream.

This is implemented by iteratively calling get( uint32 ). The caller should provide a string with enough space already reserved, if possible, to make operations more efficient.

The target string may be shorter than required if the stream ends before all the characters are read, or in case of error.

Returns:: true if some characters are available, false on stream end or error.

Reimplemented in Falcon::BaseFileStream, Falcon::StringStream, and Falcon::Transcoder.

void Falcon::Stream::reset ( ) [inline]

References m_lastMoved, status(), t_error, t_invalid, and t_unsupported.

virtual int64 Falcon::Stream::seek	(	int64	pos,
		e_whence	w
	)			`[virtual]`

Reimplemented in Falcon::BaseFileStream, Falcon::StreamBuffer, Falcon::StringStream, and Falcon::Transcoder.

int64 Falcon::Stream::seekBegin ( int64 pos ) [inline]

int64 Falcon::Stream::seekCurrent ( int64 pos ) [inline]

int64 Falcon::Stream::seekEnd ( int64 pos ) [inline]

void Falcon::Stream::status ( t_status s ) [inline]

virtual t_status Falcon::Stream::status ( ) const [inline, virtual]

Reimplemented in Falcon::StreamBuffer, and Falcon::Transcoder.

Referenced by bad(), eof(), error(), good(), interrupted(), invalid(), open(), reset(), and unsupported().

virtual int64 Falcon::Stream::tell ( ) [virtual]

Reimplemented in Falcon::BaseFileStream, Falcon::StreamBuffer, Falcon::StringStream, and Falcon::Transcoder.

virtual bool Falcon::Stream::truncate ( int64 pos = -1 ) [virtual]

Reimplemented in Falcon::BaseFileStream, Falcon::StdStream, Falcon::ROStringStream, Falcon::StreamBuffer, Falcon::StringStream, and Falcon::Transcoder.

t_streamType Falcon::Stream::type ( ) const [inline]

void Falcon::Stream::unget ( const String & target )

Ungets a whole string.

The string is pushed on the read back buffer so that the next target.length() get() operations return the content of the string.

Note:: use wisely.

void Falcon::Stream::unget ( uint32 chr ) [inline]

Write a character in the readahead buffer.

Next get() operation will return characters pushed in the buffer in reverse order. So, if the next character on the stream is 100 and the caller class unget(1) and unget(2), three consecutive get will return in turn 2, 1 and 100.

Unget is interleaved with readAhead(), so that the sequence

         Stream *s = ...
         Transcoder x( s );
         x.unget( 10 );
         x.readAhead( chr ); // chr <- 20
         x.unget( 30 );

         String res;
         x.get( res, 3 );

Will fill res with 30, 20 and 10.

See also:: readAhead

Parameters:

chr

the character to be pushed.

bool Falcon::Stream::unsupported ( ) const [inline]

References status(), and t_unsupported.

virtual int32 Falcon::Stream::write	(	const void *	buffer,
		int32	size
	)			`[virtual]`

Write to the target stream.

Reimplemented in Falcon::BaseFileStream, Falcon::InputStream, Falcon::ROStringStream, Falcon::StreamBuffer, Falcon::StringStream, and Falcon::Transcoder.

virtual int32 Falcon::Stream::writeAvailable	(	int32	msecs_timeout,
		const Sys::SystemData *	sysData = `0`
	)			`[virtual]`

Determines if the stream can be written, possibly with a given timeout.

If sysData is not zero, it will be used to honor concurrent interrupt requests.

Reimplemented in Falcon::BaseFileStream, Falcon::ROStringStream, Falcon::StreamBuffer, Falcon::StringStream, and Falcon::Transcoder.

virtual bool Falcon::Stream::writeString	(	const String &	source,
		uint32	begin = `0`,
		uint32	end = `csh::npos`
	)			`[virtual]`

Writes a string on the stream.

Encoding range is in [begin, end), that is, the last character encoded is end - 1.

Parameters:

	source	the string that must be encoded
	begin	first character from which to encode
	end	one past last character to encode (can be safely greater than string lenght() )

Returns:: true success, false on stream error.

Reimplemented in Falcon::BaseFileStream, Falcon::StringStream, and Falcon::Transcoder.

Friends And Related Function Documentation

friend class Transcoder [friend]

Member Data Documentation

int32 Falcon::Stream::m_lastMoved [protected]

Referenced by reset().

uint32* Falcon::Stream::m_rhBuffer [protected]

uint32 Falcon::Stream::m_rhBufferPos [protected]

uint32 Falcon::Stream::m_rhBufferSize [protected]

t_status Falcon::Stream::m_status [protected]

t_streamType Falcon::Stream::m_streamType [protected]

The documentation for this class was generated from the following file:

/home/gian/Progetti/falcon/core/include/falcon/stream.h


Public Types
Public Member Functions
bool	bad () const
virtual FalconData *	clone () const
	Clones the stream.
virtual bool	close ()
	Close target stream.
void	discardReadAhead (uint32 count=0)
	Discards ungetted and read ahead characters.
bool	eof () const
bool	error () const
virtual bool	errorDescription (::Falcon::String &description) const
virtual bool	flush ()
	Flushes stream buffers.
virtual void	gcMark (uint32 mark)
virtual bool	get (uint32 &chr)=0
	Gets next character from the stream.
bool	good () const
bool	interrupted () const
bool	invalid () const
virtual bool	isStreamBuffer () const
virtual bool	isTranscoder () const
virtual int64	lastError () const
uint32	lastMoved () const
bool	open () const
virtual bool	put (uint32 chr)
	Writes a character on the stream.
virtual int32	read (void *buffer, int32 size)
	Reads from target stream.
bool	readAhead (String &target, uint32 size)
	Read a string but don't remove from get().
bool	readAhead (uint32 &chr)
	Read a character but don't remove from get().
virtual int32	readAvailable (int32 msecs_timeout, const Sys::SystemData *sysData=0)
	Determines if the stream can be read, possibly with a given timeout.
virtual bool	readString (String &target, uint32 size)
	Gets a whole string from the stream.
void	reset ()
virtual int64	seek (int64 pos, e_whence w)
int64	seekBegin (int64 pos)
int64	seekCurrent (int64 pos)
int64	seekEnd (int64 pos)
void	status (t_status s)
virtual t_status	status () const
	Stream (const Stream &other)
virtual int64	tell ()
virtual bool	truncate (int64 pos=-1)
t_streamType	type () const
void	unget (const String &target)
	Ungets a whole string.
void	unget (uint32 chr)
	Write a character in the readahead buffer.
bool	unsupported () const
virtual int32	write (const void *buffer, int32 size)
	Write to the target stream.
virtual int32	writeAvailable (int32 msecs_timeout, const Sys::SystemData *sysData=0)
	Determines if the stream can be written, possibly with a given timeout.
virtual bool	writeString (const String &source, uint32 begin=0, uint32 end=csh::npos)
	Writes a string on the stream.
virtual	~Stream ()
Protected Types
enum	e_whence { ew_begin, ew_cur, ew_end }
Protected Member Functions
bool	bufferEmpty () const
	Returns true if the buffer is empty.
bool	popBuffer (uint32 &chr)
	Pops next character from the buffer.
void	pushBuffer (uint32 chr)
	Push a character in the read ahead buffer.
	Stream (t_streamType streamType)
	Initializes the base file class.
Protected Attributes
int32	m_lastMoved
uint32 *	m_rhBuffer
uint32	m_rhBufferPos
uint32	m_rhBufferSize
t_status	m_status
t_streamType	m_streamType
Friends
class	Transcoder