QTextStream Class

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

List of all members, including inherited members

Public Types

Public Functions

Detailed Description

QTextStream can operate on a QIODevice, a QByteArray, a QString or a stdio FILE pointer. Use the stream operators to write values as text and read them back as words and numbers:

QFile file("numbers.txt");
if (file.open(QIODevice::WriteOnly)) {
    QTextStream out(&file);
    out << "pi = " << 3.14159 << Qt::endl;
}

Output is buffered and written to the device when the buffer fills, on flush(), and when the stream is destroyed. The formatting of numbers and fields is controlled by setIntegerBase(), setNumberFlags(), setRealNumberNotation(), setRealNumberPrecision(), setFieldWidth(), setFieldAlignment() and setPadChar(), or by the manipulators in the Qt namespace such as Qt::hex and Qt::endl.

Text on devices and byte arrays is UTF-8 unless setEncoding() selects another encoding. A byte order mark at the start of the data selects the encoding it stands for, unless setAutoDetectUnicode() turned detection off.

See also QIODevice, QFile, QDataStream and QBuffer.

Differences from Qt

Member Type Documentation

enum QTextStream::FieldAlignment

Selects where padding is inserted when a value is shorter than the field width.

enum QTextStream::NumberFlag

Controls how numbers are written. The NumberFlags type is a typedef for QFlags<NumberFlag>.

typedef QTextStream::NumberFlags

The NumberFlags type is a typedef for QFlags<NumberFlag>. It stores an OR combination of NumberFlag values.

enum QTextStream::RealNumberNotation

Selects how floating-point numbers are written.

enum QTextStream::Status

Describes the state of the stream.

Member Function Documentation

QTextStream::QTextStream()

Constructs a text stream with no device or string. Set one with setDevice() or setString() before using the stream.

[explicit] QTextStream::QTextStream(QIODevice *device)

Constructs a text stream that operates on device. The stream does not take ownership of the device.

See also setDevice().

[explicit] QTextStream::QTextStream(FILE *fileHandle, QIODeviceBase::OpenMode mode = QIODeviceBase::ReadWrite)

Constructs a text stream that operates on the stdio file fileHandle, opened with the given mode. The stream does not close the file. A seekable file can be repositioned with seek(); a terminal or pipe is read one line at a time.

[explicit] QTextStream::QTextStream(QString *string, QIODeviceBase::OpenMode mode = QIODeviceBase::ReadWrite)

Constructs a text stream that operates on string, using the open mode. Reading starts at the beginning of the string. Writing appends to the string and requires WriteOnly in mode. The string must outlive the stream.

See also setString().

[explicit] QTextStream::QTextStream(QByteArray *array, QIODeviceBase::OpenMode mode = QIODeviceBase::ReadWrite)

Constructs a text stream that operates on the byte array array, using the open mode. The array must outlive the stream. Text is encoded as UTF-8.

[explicit] QTextStream::QTextStream(const QByteArray &array, QIODeviceBase::OpenMode mode = QIODeviceBase::ReadOnly)

Constructs a text stream that reads from a copy of array, using the open mode. Text is decoded as UTF-8.

QTextStream::~QTextStream()

Flushes any buffered output and destroys the stream. A device given to the constructor or setDevice() is not closed.

See also flush().

bool QTextStream::atEnd() const

Returns true if there is no more data to read from the stream; otherwise returns false. For a QString, the stream is at its end when it is not open for reading or the read position is at the end.

See also read() and readLine().

bool QTextStream::autoDetectUnicode() const

Returns true if the stream detects the encoding from a byte order mark; otherwise returns false.

See also setAutoDetectUnicode().

QIODevice * QTextStream::device() const

Returns the current I/O device, or nullptr if none is set or the stream operates on a QString.

See also setDevice() and string().

QStringConverter::Encoding QTextStream::encoding() const

Returns the encoding of the stream: the one set with setEncoding(), or the one found by Unicode detection. The default is QStringConverter::Utf8.

This function was introduced in 6.0.

See also setEncoding() and autoDetectUnicode().

FieldAlignment QTextStream::fieldAlignment() const

Returns the current field alignment, which is AlignRight by default.

See also setFieldAlignment().

int QTextStream::fieldWidth() const

Returns the current field width.

See also setFieldWidth().

void QTextStream::flush()

Writes any buffered output to the device and, for files, asks the operating system to flush it. Does nothing for a QString.

See also Qt::flush() and Qt::endl().

bool QTextStream::generateByteOrderMark() const

Returns true if the stream writes a byte order mark; otherwise returns false.

See also setGenerateByteOrderMark().

int QTextStream::integerBase() const

Returns the current base of integers.

See also setIntegerBase().

QLocale QTextStream::locale() const

Returns the locale used for numbers. The default is QLocale::c().

See also setLocale().

NumberFlags QTextStream::numberFlags() const

Returns the current number flags.

See also setNumberFlags() and NumberFlag.

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

Writes the character c to the stream, padded to the field width, and returns a reference to the stream.

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

This is an overloaded function.

Writes the Latin-1 character c to the stream.

QTextStream & QTextStream::operator<<(short i)

This is an overloaded function.

Writes the short integer i to the stream, using the current integer base, number flags and field settings.

QTextStream & QTextStream::operator<<(unsigned short i)

This is an overloaded function.

Writes the unsigned short integer i to the stream; see operator<<(short).

QTextStream & QTextStream::operator<<(int i)

This is an overloaded function.

Writes the integer i to the stream; see operator<<(short).

QTextStream & QTextStream::operator<<(unsigned int i)

This is an overloaded function.

Writes the unsigned integer i to the stream; see operator<<(short).

QTextStream & QTextStream::operator<<(long i)

This is an overloaded function.

Writes the long integer i to the stream; see operator<<(short).

QTextStream & QTextStream::operator<<(unsigned long i)

This is an overloaded function.

Writes the unsigned long integer i to the stream; see operator<<(short).

QTextStream & QTextStream::operator<<(long long i)

This is an overloaded function.

Writes the long long integer i to the stream; see operator<<(short).

QTextStream & QTextStream::operator<<(unsigned long long i)

This is an overloaded function.

Writes the unsigned long long integer i to the stream; see operator<<(short).

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

This is an overloaded function.

Writes the real number f to the stream, as a double.

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

This is an overloaded function.

Writes the real number f to the stream, using the current real number notation, precision, number flags and field settings.

QTextStream & QTextStream::operator<<(const QString &s)

This is an overloaded function.

Writes the string s to the stream, padded to the field width.

QTextStream & QTextStream::operator<<(QStringView s)

This is an overloaded function.

Writes the string view s to the stream.

QTextStream & QTextStream::operator<<(QLatin1StringView s)

This is an overloaded function.

Writes the Latin-1 string s to the stream.

QTextStream & QTextStream::operator<<(const QByteArray &array)

This is an overloaded function.

Writes the UTF-8 byte array array to the stream.

QTextStream & QTextStream::operator<<(const char *s)

This is an overloaded function.

Writes the zero-terminated UTF-8 string s to the stream.

QTextStream & QTextStream::operator<<(const void *ptr)

This is an overloaded function.

Writes the address ptr to the stream as a hexadecimal number with a 0x prefix.

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

Reads a character from the stream into c, skipping leading whitespace, and returns a reference to the stream. If no character is available, c is set to a null character and the status is set to ReadPastEnd.

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

This is an overloaded function.

Reads a character from the stream into c, skipping leading whitespace. The character is converted to Latin-1.

QTextStream & QTextStream::operator>>(short &i)

This is an overloaded function.

Reads a short integer from the stream into i, skipping leading whitespace and using the current integer base. If the number cannot be read or does not fit the type, i is set to 0 and the status is set to ReadPastEnd at the end of the data or ReadCorruptData otherwise. Only the longest valid numeric prefix is consumed.

QTextStream & QTextStream::operator>>(unsigned short &i)

This is an overloaded function.

Reads an unsigned short integer from the stream into i; see operator>>(short &).

QTextStream & QTextStream::operator>>(int &i)

This is an overloaded function.

Reads an integer from the stream into i; see operator>>(short &).

QTextStream & QTextStream::operator>>(unsigned int &i)

This is an overloaded function.

Reads an unsigned integer from the stream into i; see operator>>(short &).

QTextStream & QTextStream::operator>>(long &i)

This is an overloaded function.

Reads a long integer from the stream into i; see operator>>(short &).

QTextStream & QTextStream::operator>>(unsigned long &i)

This is an overloaded function.

Reads an unsigned long integer from the stream into i; see operator>>(short &).

QTextStream & QTextStream::operator>>(long long &i)

This is an overloaded function.

Reads a long long integer from the stream into i; see operator>>(short &).

QTextStream & QTextStream::operator>>(unsigned long long &i)

This is an overloaded function.

Reads an unsigned long long integer from the stream into i; see operator>>(short &).

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

This is an overloaded function.

Reads a real number from the stream into f, skipping leading whitespace. Decimal, exponent, inf and nan forms are accepted. If no number can be read, f is set to 0 and the status is set to ReadPastEnd or ReadCorruptData.

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

This is an overloaded function.

Reads a real number from the stream into f; see operator>>(float &).

QTextStream & QTextStream::operator>>(QString &s)

This is an overloaded function.

Reads a whitespace-delimited word from the stream into s, skipping leading whitespace. If no word is available, s is null and the status is set to ReadPastEnd.

QTextStream & QTextStream::operator>>(QByteArray &array)

This is an overloaded function.

Reads a whitespace-delimited word from the stream into array as UTF-8, skipping leading whitespace. If no word is available, array is cleared and the status is set to ReadPastEnd.

QChar QTextStream::padChar() const

Returns the current pad character.

See also setPadChar().

qint64 QTextStream::pos() const

Returns the current position of the stream. For a device, this is the device position adjusted for the text that was read ahead and the output that is still buffered. For a QString, it is the read position as a number of UTF-16 code units. Returns 0 if there is no device or string.

See also seek().

QString QTextStream::read(qint64 maxlen)

Reads at most maxlen characters from the stream and returns them as a string. The result is shorter, or empty, if fewer characters remain or if maxlen is not positive.

See also readAll() and readLine().

QString QTextStream::readAll()

Reads the entire content of the stream from the current position and returns it as a string. The result is empty, but not null, if there is nothing left to read.

See also readLine() and read().

QString QTextStream::readLine(qint64 maxlen = 0)

Reads one line of text from the stream and returns it, without the line terminator. Lines end at a newline; one trailing carriage return is removed. If maxlen is greater than 0, at most maxlen characters are read. Returns a null string if the stream is at its end.

See also readLineInto(), readAll() and atEnd().

bool QTextStream::readLineInto(QString *line, qint64 maxlen = 0)

Reads one line of text from the stream into line, without the line terminator, and returns true. Lines end at a newline; one trailing carriage return is removed. If maxlen is greater than 0, at most maxlen characters are read. Returns false and clears line if the stream is at its end.

See also readLine() and readAll().

RealNumberNotation QTextStream::realNumberNotation() const

Returns the current real number notation, which is SmartNotation by default.

See also setRealNumberNotation().

int QTextStream::realNumberPrecision() const

Returns the current real number precision.

See also setRealNumberPrecision().

void QTextStream::reset()

Resets all formatting options to their defaults: right alignment, a space pad character, field width 0, no number flags, integer base 10, smart notation and precision 6. The status, device and read position are not changed.

See also Qt::reset().

void QTextStream::resetStatus()

Resets the status of the text stream to Ok.

See also status() and setStatus().

bool QTextStream::seek(qint64 pos)

Flushes buffered output, discards read-ahead text and seeks to pos. Returns true on success; otherwise returns false. For a QString, pos is a position in UTF-16 code units from 0 to the string size, and only the read position changes. For a device, the device must support seeking.

See also pos() and QIODevice::seek().

void QTextStream::setAutoDetectUnicode(bool enabled)

Sets whether the stream detects the encoding of the data from a byte order mark at its start to enabled. It is enabled by default.

See also autoDetectUnicode() and encoding().

void QTextStream::setDevice(QIODevice *device)

Flushes any buffered output, then sets the I/O device to device, which can be nullptr. Any read-ahead text is discarded. The stream does not take ownership of the device.

See also device() and setString().

void QTextStream::setEncoding(QStringConverter::Encoding encoding)

Sets the encoding of the stream to encoding. Buffered output is written first; text read from then on is decoded with the new encoding (unless Unicode detection finds a byte order mark at the start of the data), and text written is encoded with it.

This function was introduced in 6.0.

See also encoding() and setAutoDetectUnicode().

void QTextStream::setFieldAlignment(FieldAlignment a)

Sets the field alignment to a. The alignment applies when a field width is set.

See also fieldAlignment() and setFieldWidth().

void QTextStream::setFieldWidth(int w)

Sets the current field width to w. If w is 0, the default, no padding is added. The width applies to each value written.

See also fieldWidth(), setPadChar() and setFieldAlignment().

void QTextStream::setGenerateByteOrderMark(bool generate)

Sets whether the stream writes a byte order mark before the first text it writes, for the Unicode encodings, to generate. It is off by default.

See also generateByteOrderMark() and Qt::bom().

void QTextStream::setIntegerBase(int base)

Sets the base of integers to base, which can be 2 to 36 when writing. When reading, a base of 0 detects the base from a prefix (0x, 0b or a leading 0 for octal). Other values are treated as 10. The default is 10.

See also integerBase().

void QTextStream::setLocale(const QLocale &locale)

Sets the locale used to write and read numbers to locale. Decimal numbers are then written with its decimal point and group separator (unless its number options include QLocale::OmitGroupSeparator), and read with or without the group separator. Use QLocale::c() to go back to the default.

QString out;
QTextStream stream(&out);
stream.setLocale(QLocale(QLocale::German));
stream << 1234567.5; // "1.234.567,5"

See also locale().

void QTextStream::setNumberFlags(NumberFlags f)

Sets the current number flags to f.

See also numberFlags() and NumberFlag.

void QTextStream::setPadChar(QChar c)

Sets the pad character to c. The default is a space.

See also padChar() and setFieldWidth().

void QTextStream::setRealNumberNotation(RealNumberNotation n)

Sets the real number notation to n.

See also realNumberNotation() and setRealNumberPrecision().

void QTextStream::setRealNumberPrecision(int p)

Sets the precision of real numbers to p, the number of digits written after the decimal point for fixed and scientific notation, or significant digits for smart notation. A negative value is treated as 6, which is the default.

See also realNumberPrecision() and setRealNumberNotation().

void QTextStream::setStatus(Status status)

Sets the status of the text stream to status, unless an error was already recorded. The first error is kept until resetStatus() is called.

See also Status, status() and resetStatus().

void QTextStream::setString(QString *string, QIODeviceBase::OpenMode mode = QIODeviceBase::ReadWrite)

Flushes any buffered output, then makes the stream operate on string with the open mode. Reading starts at the beginning of the string, and writing appends to it.

See also string() and setDevice().

void QTextStream::skipWhiteSpace()

Reads and discards whitespace from the stream until either a non-whitespace character is detected, or until atEnd() returns true.

See also Qt::ws().

Status QTextStream::status() const

Returns the status of the text stream.

See also Status, setStatus() and resetStatus().

QString * QTextStream::string() const

Returns the current string assigned to the stream, or nullptr if the stream uses a device.

See also setString() and device().