#include <Pt/TextStream.h>

Converts character sequences using a codec. More...

Inherits BasicIStream< CharT, TraitsT >.

Public Types
typedef ByteT	extern_type
	External character type.
typedef CharT	intern_type
	Internal character type.
typedef CharT	char_type
	Internal character type.
typedef std::char_traits< CharT >	traits_type
	Internal character traits.
typedef traits_type::int_type	int_type
	Integer type.
typedef traits_type::pos_type	pos_type
	Stream position type.
typedef traits_type::off_type	off_type
	Stream offset type.
typedef std::basic_istream< extern_type >	StreamType
	External stream type.
typedef TextCodec< char_type, extern_type >	CodecType
	Codec type.

Public Member Functions
	BasicTextIStream (StreamType &is, CodecType *codec)
	Construct with input stream and codec.
	BasicTextIStream (CodecType *codec)
	Construct with codec.
	~BasicTextIStream ()
	Destructor.
CodecType *	codec ()
	Returns the used code or a nullptr.
void	setCodec (CodecType *codec)
	Sets the text codec.
void	attach (StreamType &is)
	Attach to external target.
void	detach ()
	Detach from external target.
void	discard ()
	Discards the buffer.
void	reset ()
	Resets the buffer and target.
void	reset (StreamType &is)
	Resets the buffer and target.
BasicTextBuffer< intern_type, extern_type > &	textBuffer ()
	Returns the stream buffer.
std::streamsize	peeksome (CharT *buffer, std::streamsize n)
	Peeks bytes in the stream buffer.
BasicStreamBuffer< CharT > *	buffer ()
	Returns the buffer.
void	setBuffer (BasicStreamBuffer< CharT > *sb)
	Sets the buffer.

Detailed Description

template<typename CharT, typename ByteT>
class Pt::BasicTextIStream< CharT, ByteT >

This stream decodes an external character sequence using a codec. Reading from the stream will convert from the the encoding of external characters.

Text streams do not only convert between text encodings, but also between character types of different size. The first template parameter CharT is the character type of the decoded text and the second one ByteT is the character type of the encoded text. They are also called the internal and external character types and may be of the same type. The internal character type is used as the character type of the standard C++ stream base class.

A text stream always works with another stream as input or output. This stream works with another std::basic_istream to read the encoded input, using the external character type. A text stream can be constructed with an underlying stream and a codec, but both can also be set or reset later. If no codec is set, the stream will directly assign characters, instead of converting them. If no target stream is set, the text stream will always be EOF.

The following example demonstrates how a string stream is used as the input for a text stream, which uses a Pt::Utf8Codec to decode UTF-8 encoded text:

std::istringstream iss("UTF-8 encoded text");
 
Pt::String s;
Pt::TextIStream tis(iss, new Pt::Utf8Codec());
std::getline(tis, s);

The std::getline() function reads all input into a Pt::String. The extraction operator can also be used, for example to directly read numbers from the stream.