QTextStream Class Reference

\inmodule QtCore More...

Collaboration diagram for QTextStream:

Related Symbols
(Note that these are not member symbols.)
QTextStreamManipulator	qSetFieldWidth (int width)
	Equivalent to QTextStream::setFieldWidth(width).
QTextStreamManipulator	qSetPadChar (QChar ch)
	Equivalent to QTextStream::setPadChar(ch).
QTextStreamManipulator	qSetRealNumberPrecision (int precision)
	Equivalent to QTextStream::setRealNumberPrecision(precision).

Detailed Description

\inmodule QtCore

The QTextStream class provides a convenient interface for reading and writing text.

\reentrant

QTextStream can operate on a QIODevice, a QByteArray or a QString. Using QTextStream's streaming operators, you can conveniently read and write words, lines and numbers. For generating text, QTextStream supports formatting options for field padding and alignment, and formatting of numbers. Example:

QFile data("output.txt");
if (data.open(QFile::WriteOnly | QFile::Truncate)) {
    QTextStream out(&data);
    out << "Result: " << qSetFieldWidth(10) << left << 3.14 << 2.7;
    // writes "Result: 3.14      2.7       "
}

It's also common to use QTextStream to read console input and write console output. QTextStream is locale aware, and will automatically decode standard input using the correct encoding. Example:

QTextStream stream(stdin);
QString line;
while (stream.readLineInto(&line)) {
    ...
}

Besides using QTextStream's constructors, you can also set the device or string QTextStream operates on by calling setDevice() or setString(). You can seek to a position by calling seek(), and atEnd() will return true when there is no data left to be read. If you call flush(), QTextStream will empty all data from its write buffer into the device and call flush() on the device.

Internally, QTextStream uses a Unicode based buffer, and QStringConverter is used by QTextStream to automatically support different encodings. By default, UTF-8 is used for reading and writing, but you can also set the encoding by calling setEncoding(). Automatic Unicode detection is also supported. When this feature is enabled (the default behavior), QTextStream will detect the UTF-8, UTF-16 or the UTF-32 BOM (Byte Order Mark) and switch to the appropriate UTF encoding when reading. QTextStream does not write a BOM by default, but you can enable this by calling setGenerateByteOrderMark(true). When QTextStream operates on a QString directly, the encoding is disabled.

There are three general ways to use QTextStream when reading text files:

\list

• Chunk by chunk, by calling readLine() or readAll().

• Word by word. QTextStream supports streaming into \l {QString}s, \l {QByteArray}s and char* buffers. Words are delimited by space, and leading white space is automatically skipped.

• Character by character, by streaming into QChar or char types. This method is often used for convenient input handling when parsing files, independent of character encoding and end-of-line semantics. To skip white space, call skipWhiteSpace().

\endlist

Since the text stream uses a buffer, you should not read from the stream using the implementation of a superclass. For instance, if you have a QFile and read from it directly using QFile::readLine() instead of using the stream, the text stream's internal position will be out of sync with the file's position.

By default, when reading numbers from a stream of text, QTextStream will automatically detect the number's base representation. For example, if the number starts with "0x", it is assumed to be in hexadecimal form. If it starts with the digits 1-9, it is assumed to be in decimal form, and so on. You can set the integer base, thereby disabling the automatic detection, by calling setIntegerBase(). Example:

QTextStream in("0x50 0x20");
int firstNumber, secondNumber;
 
in >> firstNumber;             // firstNumber == 80
in >> dec >> secondNumber;     // secondNumber == 0
 
char ch;
in >> ch;                      // ch == 'x'

QTextStream supports many formatting options for generating text. You can set the field width and pad character by calling setFieldWidth() and setPadChar(). Use setFieldAlignment() to set the alignment within each field. For real numbers, call setRealNumberNotation() and setRealNumberPrecision() to set the notation (SmartNotation, ScientificNotation, FixedNotation) and precision in digits of the generated number. Some extra number formatting options are also available through setNumberFlags().

\target QTextStream manipulators

Like <iostream> in the standard C++ library, QTextStream also defines several global manipulator functions:

\table \header

• Manipulator
• Description \row
• Qt::bin
• Same as setIntegerBase(2). \row
• Qt::oct
• Same as setIntegerBase(8). \row
• Qt::dec
• Same as setIntegerBase(10). \row
• Qt::hex
• Same as setIntegerBase(16). \row
• Qt::showbase
• Same as setNumberFlags(numberFlags() | ShowBase). \row
• Qt::forcesign
• Same as setNumberFlags(numberFlags() | ForceSign). \row
• Qt::forcepoint
• Same as setNumberFlags(numberFlags() | ForcePoint). \row
• Qt::noshowbase
• Same as setNumberFlags(numberFlags() & ~ShowBase). \row
• Qt::noforcesign
• Same as setNumberFlags(numberFlags() & ~ForceSign). \row
• Qt::noforcepoint
• Same as setNumberFlags(numberFlags() & ~ForcePoint). \row
• Qt::uppercasebase
• Same as setNumberFlags(numberFlags() | UppercaseBase). \row
• Qt::uppercasedigits
• Same as setNumberFlags(numberFlags() | UppercaseDigits). \row
• Qt::lowercasebase
• Same as setNumberFlags(numberFlags() & ~UppercaseBase). \row
• Qt::lowercasedigits
• Same as setNumberFlags(numberFlags() & ~UppercaseDigits). \row
• Qt::fixed
• Same as setRealNumberNotation(FixedNotation). \row
• Qt::scientific
• Same as setRealNumberNotation(ScientificNotation). \row
• Qt::left
• Same as setFieldAlignment(AlignLeft). \row
• Qt::right
• Same as setFieldAlignment(AlignRight). \row
• Qt::center
• Same as setFieldAlignment(AlignCenter). \row
• Qt::endl
• Same as operator<<('\n') and flush(). \row
• Qt::flush
• Same as flush(). \row
• Qt::reset
• Same as reset(). \row
• Qt::ws
• Same as skipWhiteSpace(). \row
• Qt::bom
• Same as setGenerateByteOrderMark(true). \endtable

In addition, Qt provides three global manipulators that take a parameter: qSetFieldWidth(), qSetPadChar(), and qSetRealNumberPrecision().

See also

QDataStream, QIODevice, QFile, QBuffer, QTcpSocket

Friends And Related Symbol Documentation

qSetFieldWidth()

QTextStreamManipulator qSetFieldWidth ( int width )

related

Equivalent to QTextStream::setFieldWidth(width).

Definition at line 252 of file qtextstream.h.

qSetPadChar()

QTextStreamManipulator qSetPadChar ( QChar ch )

related

Equivalent to QTextStream::setPadChar(ch).

Definition at line 258 of file qtextstream.h.

qSetRealNumberPrecision()

QTextStreamManipulator qSetRealNumberPrecision ( int precision )

related

Equivalent to QTextStream::setRealNumberPrecision(precision).

Definition at line 264 of file qtextstream.h.

---

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

• qtbase/src/corelib/serialization/qtextstream.cpp (44ddb34da07f7fdb2214cb39b56cf114d4aa209e)