Falcon::Stream Class Reference

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

#include <stream.h>

Inheritance diagram for Falcon::Stream:

Inheritance graph
[legend]

List of all members.

Public Types


Public Member Functions

bool bad () const
virtual FalconDataclone () 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
uint32m_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 

Enumerator:
t_none 
t_open 
t_eof 
t_error 
t_unsupported 
t_invalid 
t_interrupted 

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]

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]

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]

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]

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]

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]

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

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]

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

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

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]

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

Referenced by reset().


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

Generated on Mon Oct 19 10:11:46 2009 for Falcon_Core by  doxygen 1.5.8