Contents

• Public Types
• Public Functions
• Detailed Description

Detailed Description

TheQ3TextStream class provides basic functions for reading and writing text using aQIODevice.

The text stream class has a functional interface that is very similar to that of the standard C++ iostream class.

Qt provides several global functions similar to the ones in iostream:

Warning: By defaultQ3TextStream will automatically detect whether integers in the stream are in decimal, octal, hexadecimal or binary format when reading from the stream. In particular, a leading '0' signifies octal, i.e. the sequence "0100" will be interpreted as 64.

TheQ3TextStream class reads and writes text; it is not appropriate for dealing with binary data (butQDataStream is).

By default, output of Unicode text (i.e.QString) is done using the local 8-bit encoding. This can be changed using thesetEncoding() method. For input, theQ3TextStream will auto-detect standard Unicode "byte order marked" text files; otherwise the local 8-bit encoding is used.

TheQIODevice is set in the constructor, or later usingsetDevice(). If the end of the input is reachedatEnd() returns TRUE. Data can be read into variables of the appropriate type using the operator>>() overloads, or read in its entirety into a single string usingread(), or read a line at a time usingreadLine(). Whitespace can be skipped over usingskipWhiteSpace(). You can set flags for the stream usingflags() orsetf(). The stream also supportswidth(),precision() andfill(); usereset() to reset the defaults.

Member Type Documentation

enum Q3TextStream::Encoding

SeesetEncoding() for an explanation of the encodings.

Member Function Documentation

Q3TextStream::Q3TextStream()

Constructs a data stream that has no IO device.

Q3TextStream::Q3TextStream(QIODevice * iod)

Constructs a text stream that uses the IO deviceiod.

Q3TextStream::Q3TextStream(QString * str,int filemode)

Constructs a text stream that operates on the UnicodeQString,str, through an internal device. Thefilemode argument is passed to the device's open() function; seeQIODevice::mode().

If you set an encoding or codec withsetEncoding() orsetCodec(), this setting is ignored for text streams that operate onQString.

Example:

QString str;Q3TextStream ts(&str, IO_WriteOnly );ts<<"pi = "<<3.14;// str == "pi = 3.14"

Writing data to the text stream will modify the contents of the string. The string will be expanded when data is written beyond the end of the string. Note that the string will not be truncated:

QString str="pi = 3.14";Q3TextStream ts(&str, IO_WriteOnly );ts<<"2+2 = "<<2+2;// str == "2+2 = 414"

Note that becauseQString is Unicode, you should not usereadRawBytes() orwriteRawBytes() on such a stream.

Q3TextStream::Q3TextStream(QByteArray & a,int mode)

Constructs a text stream that operates on the byte array,a, through an internalQBuffer device. Themode argument is passed to the device's open() function; seeQIODevice::mode().

Example:

QByteArray array;Q3TextStream ts( array, IO_WriteOnly );ts<<"pi = "<<3.14<<'\0';// array == "pi = 3.14"

Writing data to the text stream will modify the contents of the array. The array will be expanded when data is written beyond the end of the string.

Same example, using aQBuffer:

QByteArray array;QBuffer buf( array );buf.open( IO_WriteOnly );Q3TextStream ts(&buf );ts<<"pi = "<<3.14<<'\0';// array == "pi = 3.14"buf.close();

Q3TextStream::Q3TextStream(FILE * fh,int mode)

Constructs a text stream that operates on an existing file handlefh through an internalQFile device. Themode argument is passed to the device's open() function; seeQIODevice::mode().

Note that if you create aQ3TextStreamcout or another name that is also used for another variable of a different type, some linkers may confuse the two variables, which will often cause crashes.

[virtual]Q3TextStream::~Q3TextStream()

Destroys the text stream.

The destructor does not affect the current IO device.

bool Q3TextStream::atEnd() const

Returns TRUE if the IO device has reached the end position (end of the stream or file) or if there is no IO device set; otherwise returns FALSE.

This function was introduced in Qt 4.2.

See alsoQIODevice::atEnd().

QTextCodec * Q3TextStream::codec()

Returns the codec actually used for this stream.

If Unicode is automatically detected in input, a codec withname() "ISO-10646-UCS-2" is returned.

This function was introduced in Qt 4.2.

See alsosetCodec().

QIODevice * Q3TextStream::device() const

Returns the IO device currently set.

This function was introduced in Qt 4.2.

See alsosetDevice() andunsetDevice().

int Q3TextStream::fill() const

Returns the fill character. The default value is ' ' (space).

This function was introduced in Qt 4.2.

int Q3TextStream::fill(int f)

This is an overloaded function.

Sets the fill character tof. Returns the previous fill character.

int Q3TextStream::flags() const

Returns the current stream flags. The default value is 0.

Note that unlessbin,oct,dec, orhex is set, the input base is octal if the value starts with 0, hexadecimal if it starts with 0x, binary if it starts with 0b, and decimal otherwise.

This function was introduced in Qt 4.2.

See alsosetf() andunsetf().

int Q3TextStream::flags(int f)

This is an overloaded function.

Sets the stream flags tof. Returns the previous stream flags.

See alsosetf(),unsetf(), andflags().

int Q3TextStream::precision() const

Returns the precision. The default value is 6.

This function was introduced in Qt 4.2.

int Q3TextStream::precision(int p)

This is an overloaded function.

Sets the precision top. Returns the previous precision setting.

QString Q3TextStream::read()

Reads the entire stream from the current position, and returns a string containing the text.

This function was introduced in Qt 4.2.

See alsoreadLine().

QString Q3TextStream::readLine()

Reads a line from the stream and returns a string containing the text.

The returned string does not contain any trailing newline or carriage return. Note that this is different fromQIODevice::readLine(), which does not strip the newline at the end of the line.

On EOF you will get aQString that is null. On reading an empty line the returnedQString is empty but not null.

This function was introduced in Qt 4.2.

See alsoQIODevice::readLine().

Q3TextStream & Q3TextStream::readRawBytes(char * s,uint len)

Readslen bytes from the stream intos and returns a reference to the stream.

The buffers must be preallocated.

Note that no encoding is done by this function.

Warning: The behavior of this function is undefined unless the stream's encoding is set to Unicode or Latin1.

This function was introduced in Qt 4.2.

See alsoQIODevice::readBlock().

void Q3TextStream::reset()

Resets the text stream.

• All flags are set to 0.
• The field width is set to 0.
• The fill character is set to ' ' (Space).
• The precision is set to 6.

This function was introduced in Qt 4.2.

See alsosetf(),width(),fill(), andprecision().

void Q3TextStream::setCodec(QTextCodec * codec)

Sets the codec for this stream tocodec. Will not try to autodetect Unicode.

Note that this function should be called before any data is read to/written from the stream.

This function was introduced in Qt 4.2.

See alsosetEncoding() andcodec().

void Q3TextStream::setDevice(QIODevice * iod)

Sets the IO device toiod.

This function was introduced in Qt 4.2.

See alsodevice() andunsetDevice().

void Q3TextStream::setEncoding(Encoding e)

Sets the encoding of this stream toe, wheree is one of the following values:

Locale and all Unicode encodings, exceptRawUnicode, will look at the first two bytes in an input stream to determine the byte order. The initial byte order marker will be stripped off before data is read.

Note that this function should be called before any data is read to or written from the stream.

This function was introduced in Qt 4.2.

See alsosetCodec().

int Q3TextStream::setf(int bits)

Sets the stream flag bitsbits. Returns the previous stream flags.

Equivalent toflags( flags() | bits ).

This function was introduced in Qt 4.2.

See alsounsetf().

int Q3TextStream::setf(int bits,int mask)

This is an overloaded function.

Sets the stream flag bitsbits with a bit maskmask. Returns the previous stream flags.

Equivalent toflags( (flags() & ~mask) | (bits & mask) ).

See alsosetf() andunsetf().

void Q3TextStream::skipWhiteSpace()

Positions the read pointer at the first non-whitespace character.

This function was introduced in Qt 4.2.

void Q3TextStream::unsetDevice()

Unsets the IO device. Equivalent tosetDevice( 0 ).

This function was introduced in Qt 4.2.

See alsodevice() andsetDevice().

int Q3TextStream::unsetf(int bits)

Clears the stream flag bitsbits. Returns the previous stream flags.

Equivalent toflags( flags() & ~mask ).

This function was introduced in Qt 4.2.

See alsosetf().

int Q3TextStream::width() const

Returns the field width. The default value is 0.

This function was introduced in Qt 4.2.

int Q3TextStream::width(int w)

This is an overloaded function.

Sets the field width tow. Returns the previous field width.

Q3TextStream & Q3TextStream::writeRawBytes(constchar * s,uint len)

Writes thelen bytes froms to the stream and returns a reference to the stream.

Note that no encoding is done by this function.

This function was introduced in Qt 4.2.

See alsoQIODevice::writeBlock().

Q3TextStream & Q3TextStream::operator<<(QChar c)

Writes characterchar to the stream and returns a reference to the stream.

The characterc is assumed to be Latin1 encoded independent of the Encoding set for theQ3TextStream.

This function was introduced in Qt 4.2.

Q3TextStream & Q3TextStream::operator<<(char c)

This is an overloaded function.

Writes characterc to the stream and returns a reference to the stream.

This function was introduced in Qt 4.2.

Q3TextStream & Q3TextStream::operator<<(signedshort i)

This is an overloaded function.

Writes ashort integeri to the stream and returns a reference to the stream.

This function was introduced in Qt 4.2.

Q3TextStream & Q3TextStream::operator<<(unsignedshort i)

This is an overloaded function.

Writes anunsignedshort integeri to the stream and returns a reference to the stream.

This function was introduced in Qt 4.2.

Q3TextStream & Q3TextStream::operator<<(signedint i)

This is an overloaded function.

Writes aninti to the stream and returns a reference to the stream.

This function was introduced in Qt 4.2.

Q3TextStream & Q3TextStream::operator<<(unsignedint i)

This is an overloaded function.

Writes anunsignedinti to the stream and returns a reference to the stream.

This function was introduced in Qt 4.2.

Q3TextStream & Q3TextStream::operator<<(signedlong i)

This is an overloaded function.

Writes alonginti to the stream and returns a reference to the stream.

This function was introduced in Qt 4.2.

Q3TextStream & Q3TextStream::operator<<(unsignedlong i)

This is an overloaded function.

Writes anunsignedlonginti to the stream and returns a reference to the stream.

This function was introduced in Qt 4.2.

Q3TextStream & Q3TextStream::operator<<(float f)

This is an overloaded function.

Writes afloatf to the stream and returns a reference to the stream.

This function was introduced in Qt 4.2.

Q3TextStream & Q3TextStream::operator<<(double f)

This is an overloaded function.

Writes adoublef to the stream and returns a reference to the stream.

This function was introduced in Qt 4.2.

Q3TextStream & Q3TextStream::operator<<(constchar * s)

This is an overloaded function.

Writes a string to the stream and returns a reference to the stream.

The strings is assumed to be Latin1 encoded independent of the Encoding set for theQ3TextStream.

This function was introduced in Qt 4.2.

Q3TextStream & Q3TextStream::operator<<(constQ3CString & s)

This is an overloaded function.

Writess to the stream and returns a reference to the stream.

The strings is assumed to be Latin1 encoded independent of the Encoding set for theQ3TextStream.

This function was introduced in Qt 4.2.

Q3TextStream & Q3TextStream::operator<<(constQString & s)

This is an overloaded function.

Writess to the stream and returns a reference to the stream.

This function was introduced in Qt 4.2.

Q3TextStream & Q3TextStream::operator<<(void * ptr)

This is an overloaded function.

Writes a pointer to the stream and returns a reference to the stream.

Theptr is output as an unsigned long hexadecimal integer.

This function was introduced in Qt 4.2.

Q3TextStream & Q3TextStream::operator>>(QChar & c)

Reads a charc from the stream and returns a reference to the stream. Note that whitespace isnot skipped.

Q3TextStream & Q3TextStream::operator>>(char & c)

This is an overloaded function.

Reads a charc from the stream and returns a reference to the stream. Note that whitespace is skipped.

Q3TextStream & Q3TextStream::operator>>(signedshort & i)

This is an overloaded function.

Reads a signedshort integeri from the stream and returns a reference to the stream. Seeflags() for an explanation of the expected input format.

Q3TextStream & Q3TextStream::operator>>(unsignedshort & i)

This is an overloaded function.

Reads an unsignedshort integeri from the stream and returns a reference to the stream. Seeflags() for an explanation of the expected input format.

Q3TextStream & Q3TextStream::operator>>(signedint & i)

This is an overloaded function.

Reads a signedinti from the stream and returns a reference to the stream. Seeflags() for an explanation of the expected input format.

Q3TextStream & Q3TextStream::operator>>(unsignedint & i)

This is an overloaded function.

Reads an unsignedinti from the stream and returns a reference to the stream. Seeflags() for an explanation of the expected input format.

Q3TextStream & Q3TextStream::operator>>(signedlong & i)

This is an overloaded function.

Reads a signedlong inti from the stream and returns a reference to the stream. Seeflags() for an explanation of the expected input format.

Q3TextStream & Q3TextStream::operator>>(unsignedlong & i)

This is an overloaded function.

Reads an unsignedlong inti from the stream and returns a reference to the stream. Seeflags() for an explanation of the expected input format.

Q3TextStream & Q3TextStream::operator>>(float & f)

This is an overloaded function.

Reads afloatf from the stream and returns a reference to the stream. Seeflags() for an explanation of the expected input format.

Q3TextStream & Q3TextStream::operator>>(double & f)

This is an overloaded function.

Reads adoublef from the stream and returns a reference to the stream. Seeflags() for an explanation of the expected input format.

Q3TextStream & Q3TextStream::operator>>(char * s)

This is an overloaded function.

Reads a "word" from the stream intos and returns a reference to the stream.

A word consists of characters for which isspace() returns FALSE.

Q3TextStream & Q3TextStream::operator>>(QString & str)

This is an overloaded function.

Reads a "word" from the stream intostr and returns a reference to the stream.

A word consists of characters for which isspace() returns FALSE.

Q3TextStream & Q3TextStream::operator>>(Q3CString & str)

This is an overloaded function.

Reads a "word" from the stream intostr and returns a reference to the stream.

A word consists of characters for which isspace() returns FALSE.