Falcon::Transcoder Class Reference
Basic transcoder class. More...
#include <transcoding.h>
Public Member Functions | |
| virtual bool | close () |
| Close target stream. | |
| void | detach () |
| Disengages this transcoder from the underlying stream. | |
| bool | encoderStatus () const |
| Return encoder status. | |
| virtual const String | encoding () const =0 |
| Returns the character encoding which is managed by this transcoder. | |
| virtual bool | errorDescription (::Falcon::String &description) const |
| virtual bool | flush () |
| Flushes stream buffers. | |
| virtual bool | isTranscoder () const |
| virtual int64 | lastError () const |
| virtual int32 | read (void *buffer, int32 size) |
| Reads from target stream. | |
| 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 &source, uint32 size) |
| Gets a whole string from the stream. | |
| void | setUnderlying (Stream *s, bool owner=false) |
| Sets the underlying stream. | |
| virtual t_status | status () const |
| virtual int64 | tell () |
| virtual bool | truncate (int64 pos=-1) |
| Stream * | underlying () const |
| Returns the underlying stream used by this transcoder. | |
| virtual int32 | write (const void *buffer, int32 size) |
| Write to the target stream. | |
| virtual int32 | writeAvailable (int32 msecs_timeout, const Sys::SystemData *sysData) |
| 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 | ~Transcoder () |
Protected Member Functions | |
| virtual int64 | seek (int64 pos, e_whence w) |
| Transcoder (const Transcoder &other) | |
| Transcoder (Stream *s, bool bOwn) | |
Protected Attributes | |
| bool | m_parseStatus |
| Stream * | m_stream |
| bool | m_streamOwner |
Detailed Description
Basic transcoder class.Falcon strings are internally organized in a format that is meant to:
- store every possible UNICODE character
- allow scripts to access nth character randomly at cost o(1)
- allow easy transcoding in international formats.
Transcoder are the objects that allow importing of text from streams (including "StringStreams") and encoding of falcon strings to output devices.
By picking the right transcoder, the embedder is able to read a text file which is recorded in any encoding and to import it in a Falcon String, or to write a falcon string to a file that can be then opened in other applications.
The stream the transcoder receives is not owned by the transcoder: the caller must close and dispose of the given stream separatedly.
As all transcoding operations are character oriented, unless the stream is considerabily small, using a BufferedStream is highly recommended (unless, of course, using a memory based stream like object).
A convenience function TranscoderFactory is provided to build a transcoder for a given character encoding.
This class has also a read ahead and write-back buffer facilities. This allows to build very complex lexers and parsers by using this class as an interface to a stream that may not have seek capabilities. The buffer is constructed only if needed, so there is no extra cost for this facility.
- Note:
- default behavior when transcoding a character that cannot be represented in the target encoding is to write a "?" (unicode question mark) character.
- See also:
- TranscoderFactory
Constructor & Destructor Documentation
| Falcon::Transcoder::Transcoder | ( | Stream * | s, | |
| bool | bOwn | |||
| ) | [protected] |
| Falcon::Transcoder::Transcoder | ( | const Transcoder & | other | ) | [protected] |
| virtual Falcon::Transcoder::~Transcoder | ( | ) | [virtual] |
Member Function Documentation
| virtual bool Falcon::Transcoder::close | ( | ) | [virtual] |
| void Falcon::Transcoder::detach | ( | ) | [inline] |
Disengages this transcoder from the underlying stream.
| bool Falcon::Transcoder::encoderStatus | ( | ) | const [inline] |
Return encoder status.
A false status indicates that the last encoding or decoding operation wasn't successful. In example, it may indicate an incorrect UTF-8 sequence in utf-8 reading, or an unencodable character in ISO8859 writing.
Stream I/O error do not set to false this state, and operations may return true even if this state get false. In example, ISO8859 encoding writes a "?" in case of unencodable character and correctly completes the operation, but to inform the user about this fact it sets the status to false.
Iterative get operations (i.e. get string) will be interrupted if status is false, and will return false, as the quality of the stream cannot be granted.
Iterative write operations will return true and complete iterations, but will set state to false on exit.
- Returns:
- false if last get or write operation caused an encoding breaking.
| virtual const String Falcon::Transcoder::encoding | ( | ) | const [pure virtual] |
Returns the character encoding which is managed by this transcoder.
Subclasses must reimplement this to return the name of the supported encoding.
Implemented in Falcon::TranscoderEOL, Falcon::TranscoderByte, Falcon::TranscoderUTF8, and Falcon::TranscoderUTF16.
| virtual bool Falcon::Transcoder::errorDescription | ( | ::Falcon::String & | description | ) | const [inline, virtual] |
Reimplemented from Falcon::Stream.
| virtual bool Falcon::Transcoder::flush | ( | ) | [virtual] |
| virtual bool Falcon::Transcoder::isTranscoder | ( | ) | const [inline, virtual] |
Reimplemented from Falcon::Stream.
| virtual int64 Falcon::Transcoder::lastError | ( | ) | const [inline, virtual] |
Reimplemented from Falcon::Stream.
Reads from target stream.
- Parameters:
-
buffer the buffer where read data will be stored. size the amount of bytes to read
Reimplemented from Falcon::Stream.
| virtual int32 Falcon::Transcoder::readAvailable | ( | int32 | msecs_timeout, | |
| const Sys::SystemData * | sysData = 0 | |||
| ) | [inline, 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 from Falcon::Stream.
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 from Falcon::Stream.
Reimplemented from Falcon::Stream.
| void Falcon::Transcoder::setUnderlying | ( | Stream * | s, | |
| bool | owner = false | |||
| ) |
Sets the underlying stream.
To be able to set a stream after that the transcoder has been created. This function can set property on the stream. If the owner parameter is set to true, the stream pointer will be destroyed when the transcoder will be destroyed.
- Note:
- If the previously used stream was owned by this instance, it is destroyed here.
- Parameters:
-
s stream to be used as underlying stream owner true if the stream must be destroyed at transcoder termination.
| virtual t_status Falcon::Transcoder::status | ( | ) | const [inline, virtual] |
Reimplemented from Falcon::Stream.
| virtual int64 Falcon::Transcoder::tell | ( | ) | [virtual] |
Reimplemented from Falcon::Stream.
| virtual bool Falcon::Transcoder::truncate | ( | int64 | pos = -1 |
) | [virtual] |
Reimplemented from Falcon::Stream.
| Stream* Falcon::Transcoder::underlying | ( | ) | const [inline] |
Returns the underlying stream used by this transcoder.
- Returns:
- the underlying stream.
| virtual int32 Falcon::Transcoder::writeAvailable | ( | int32 | msecs_timeout, | |
| const Sys::SystemData * | sysData | |||
| ) | [inline, 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 from Falcon::Stream.
| virtual bool Falcon::Transcoder::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 from Falcon::Stream.
Member Data Documentation
bool Falcon::Transcoder::m_parseStatus [protected] |
Stream* Falcon::Transcoder::m_stream [protected] |
bool Falcon::Transcoder::m_streamOwner [protected] |
The documentation for this class was generated from the following file:
- /home/gian/Progetti/falcon/core/include/falcon/transcoding.h
