|  | Home · Overviews · Examples

# QTextStream Class Reference
[com.trolltech.qt.core module]

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

## Detailed Description

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

`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 << endl;
            // writes "Result: 3.14      2.7       \n"
        }

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 codec. Example:

        QTextStream stream(stdin);
        QString line;
        do {
            line = stream.readLine();
        } while (!line.isNull());

Note that you cannot use QTextStream::atEnd(), which returns true when you have reached the end of the data stream, with stdin.

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 `QTextCodec` is used by `QTextStream` to automatically support different character sets. By default, QTextCodec::codecForLocale() is used for reading and writing, but you can also set the codec by calling `setCodec`. Automatic Unicode detection is also supported. When this feature is enabled (the default behavior), `QTextStream` will detect the UTF-16 BOM (Byte Order Mark) and switch to the appropriate UTF-16 codec 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 codec is disabled.

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

- Chunk by chunk, by calling `readLine` or `readAll`.
- Word by word. `QTextStream` supports streaming into QStrings, QByteArrays 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`.

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`.

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

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

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

See also `QDataStream`, `QIODevice`, `QFile`, `QBuffer`, `QTcpSocket`, and Codecs Example.