QTextStream Class

成员函数文档

QTextStream::QTextStream()

构造一个 QTextStream。在使用它进行读取或写入之前，必须指定一个设备或字符串。

另请参阅 setDevice() 和setString()。

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

构造一个可在device 上运行的 QTextStream。

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

构造一个在fileHandle 上运行的 QTextStream，使用openMode 定义打开模式。在内部，会创建一个QFile 来处理 FILE 指针。

该构造函数可直接用于处理常见的基于 FILE 的输入和输出流：stdin、stdout 和 stderr。示例

QString str;
QTextStream in(stdin);
in >> str;

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

构造对array 进行操作的 QTextStream，使用openMode 定义打开模式。在内部，数组由QBuffer 封装。

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

构造一个可在string 上运行的 QTextStream，使用openMode 定义打开模式。

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

构造对array 进行操作的 QTextStream，使用openMode 定义打开模式。数组以只读方式访问，与openMode 中的值无关。

该构造函数可方便地处理常量字符串。示例

int main(int argc, char *argv[])
{
    // read numeric arguments (123, 0x20, 4.5...)
    for (int i = 1; i < argc; ++i) {
          int number;
          QTextStream in(argv[i]);
          in >> number;
          ...
    }
}

[virtual noexcept] QTextStream::~QTextStream()

销毁QTextStream 。

如果流在设备上运行，flush() 将被隐式调用。否则，设备不受影响。

bool QTextStream::atEnd() const

如果QTextStream 没有数据可读，则返回true ；否则返回false 。这与调用QIODevice::atEnd() 类似，但并不相同，因为QTextStream 也会考虑其内部的 Unicode 缓冲区。

bool QTextStream::autoDetectUnicode() const

如果启用了 Unicode 自动检测，则返回true ，否则返回false 。自动 Unicode 检测默认已启用。

另请参阅 setAutoDetectUnicode() 和setEncoding()。

QIODevice *QTextStream::device() const

返回与QTextStream 关联的当前设备，如果未指定设备，则返回nullptr 。

另请参阅 setDevice() 和string()。

QStringConverter::Encoding QTextStream::encoding() const

返回当前分配给数据流的编码。

另请参阅 setEncoding()、setAutoDetectUnicode() 和locale()。

QTextStream::FieldAlignment QTextStream::fieldAlignment() const

返回当前的字段对齐方式。

另请参阅 setFieldAlignment() 和fieldWidth()。

int QTextStream::fieldWidth() const

返回当前字段宽度。

另请参阅 setFieldWidth()。

void QTextStream::flush()

刷新任何等待写入设备的缓冲数据。

如果QTextStream 对字符串进行操作，则该函数不执行任何操作。

bool QTextStream::generateByteOrderMark() const

如果QTextStream 设置为在使用 UTF 编码时生成 UTF BOM（字节序标记），则返回true ；否则返回false 。UTF BOM 生成默认设置为 false。

另请参阅 setGenerateByteOrderMark().

int QTextStream::integerBase() const

返回整数的当前进制。0 表示读数时检测基数，或生成数字时检测 10（十进制）。

另请参阅 setIntegerBase()、QString::number() 和numberFlags()。

QLocale QTextStream::locale() const

返回此数据流的 locale。默认语言为 C。

另请参阅 setLocale()。

QTextStream::NumberFlags QTextStream::numberFlags() const

返回当前数字标志。

另请参阅 setNumberFlags()、integerBase() 和realNumberNotation()。

QChar QTextStream::padChar() const

返回当前填充字符。

另请参阅 setPadChar() 和setFieldWidth()。

qint64 QTextStream::pos() const

返回与数据流当前位置相对应的设备位置，如果出现错误（如没有设备或字符串，或设备出错），则返回-1。

由于QTextStream 是缓冲区，因此该函数可能需要寻找设备以重建有效的设备位置。这一操作的代价可能很高，因此应避免在紧循环中调用此函数。

另请参见 seek()。

QString QTextStream::read(qint64 maxlen)

从数据流中最多读取maxlen 个字符，并以QString 的形式返回读取的数据。

另请参阅 readAll()、readLine() 和QIODevice::read()。

QString QTextStream::readAll()

读取数据流的全部内容，并以QString 的形式返回。处理大文件时应避免使用该函数，因为它会占用大量内存。

如果不知道有多少数据可用，最好调用readLine() 。

另请参阅 readLine()。

QString QTextStream::readLine(qint64 maxlen = 0)

从数据流中读取一行文本，并以QString 的形式返回。允许的最大行长设置为maxlen 。如果数据流中的行数超过此值，则将在maxlen 字符之后分行并分次返回。

如果maxlen 为 0，则行的长度不限。

返回的行没有行尾字符（"\n "或"\r\n"），因此可以不必调用QString::trimmed() 。

如果数据流已经读到文件末尾，readLine() 将返回一个空值QString 。对于字符串或支持该功能的设备，可以使用atEnd() 明确测试流是否已结束。

另请参阅 readAll() 和QIODevice::readLine()。

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

从数据流中读取一行文本到line 。如果line 是nullptr ，则不存储读取的行。

允许的最大行长设置为maxlen 。如果数据流中的行长超过此值，则会在maxlen 字符后分行并分次返回。

如果maxlen 为 0，则行的长度不限。

生成的行没有行尾字符（"\n "或"\r\n"），因此可以不必调用QString::trimmed() 。

如果line 有足够的容量容纳即将读取的数据，则该函数可能不需要分配新的内存。因此，它可能比readLine() 更快。

如果数据流已读取到文件末尾或发生错误，则返回false ；否则返回true 。在任何情况下，调用前line 中的内容都将被丢弃。

另请参阅 readAll()、QIODevice::readLine() 和QIODevice::readLineInto()。

QTextStream::RealNumberNotation QTextStream::realNumberNotation() const

返回当前的实数符号。

另请参见 setRealNumberNotation()、realNumberPrecision()、numberFlags() 和integerBase()。

int QTextStream::realNumberPrecision() const

返回当前实数精度，或QTextStream 在生成实数时将写入的分数位数 (FixedNotation,ScientificNotation) ，或最大有效位数 (SmartNotation) 。

另请参阅 setRealNumberPrecision(),setRealNumberNotation(),realNumberNotation(),numberFlags() 和integerBase().

void QTextStream::reset()

重置QTextStream 的格式化选项，使其恢复到初始构造状态。设备、字符串和任何缓冲数据均保持不变。

void QTextStream::resetStatus()

重置文本流的状态。

另请参阅 QTextStream::Status,status() 和setStatus()。

bool QTextStream::seek(qint64 pos)

查找设备中的位置pos 。成功时返回true ；否则返回false 。

void QTextStream::setAutoDetectUnicode(bool enabled)

如果enabled 为 true，QTextStream 将尝试检测 Unicode 编码，方法是窥视流数据，看是否能找到 UTF-8、UTF-16 或 UTF-32 字节顺序标记 (BOM)。如果发现该标记，QTextStream 将用 UTF 编码替换当前编码。

该函数可与setEncoding() 一起使用。通常将编码设置为 UTF-8，然后启用 UTF-16 检测。

另请参阅 autoDetectUnicode() 和setEncoding()。

void QTextStream::setDevice(QIODevice *device)

将当前设备设置为device 。如果已经分配了一个设备，QTextStream 将在替换旧设备之前调用flush() 。

另请参阅 device() 和setString()。

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

将该数据流的编码设置为encoding 。该编码用于解码从指定设备读取的任何数据，以及编码写入的任何数据。默认情况下，使用QStringConverter::Utf8 ，并启用自动 unicode 检测。

如果QTextStream 对字符串进行操作，则此函数不会执行任何操作。

另请参阅 encoding()、setAutoDetectUnicode() 和setLocale()。

void QTextStream::setFieldAlignment(QTextStream::FieldAlignment mode)

将字段对齐方式设置为mode 。与setFieldWidth() 一起使用时，该函数允许您生成文本左对齐、右对齐或居中对齐的格式化输出。

另请参阅 fieldAlignment() 和setFieldWidth()。

void QTextStream::setFieldWidth(int width)

将当前字段宽度设置为width 。如果width 为 0（默认值），则字段宽度等于生成文本的长度。

另请参见 fieldWidth() 和setPadChar()。

void QTextStream::setGenerateByteOrderMark(bool generate)

如果generate 为真且使用 UTF 编码，QTextStream 将在任何数据写入设备之前插入 BOM（字节序号标记）。如果generate 为假，则不会插入 BOM。必须在写入任何数据之前调用此函数。否则，它不会执行任何操作。

另请参阅 generateByteOrderMark() 和bom()。

void QTextStream::setIntegerBase(int base)

设置base 的整数进制，用于读取和生成数字。base 可以是 2（二进制）、8（八进制）、10（十进制）或 16（十六进制）。如果base 为 0，QTextStream 将尝试通过检查数据流中的数据来检测进制。在生成数字时，除非明确设置了进制，否则QTextStream 会假定进制为 10。

另请参见 integerBase()、QString::number() 和setNumberFlags()。

void QTextStream::setLocale(const QLocale &locale)

将此数据流的 locale 设置为locale 。指定的 locale 用于数字和字符串之间的转换。

默认 locale 为 C，这是一种特殊情况--出于向后兼容的原因，不使用千位分隔符。

另请参阅 locale() 。

void QTextStream::setNumberFlags(QTextStream::NumberFlags flags)

将当前数字标志设置为flags 。flags 是NumberFlag 枚举中的一组标志，描述了格式化生成代码的选项（例如，是否始终写入数字的底数或符号）。

另请参见 numberFlags()、setIntegerBase() 和setRealNumberNotation()。

void QTextStream::setPadChar(QChar ch)

将填充字符设置为ch 。默认值是 ASCII 空格字符（' ' ），或QChar(0x20)。该字符用于在生成文本时填充字段中的空格。

例如

QString s;
QTextStream out(&s);
out.setFieldWidth(10);
out.setFieldAlignment(QTextStream::AlignCenter);
out.setPadChar('-');
out << "Qt" << "rocks!";

字符串s 包含：

----Qt------rocks!--

另请参阅 padChar() 和setFieldWidth()。

void QTextStream::setRealNumberNotation(QTextStream::RealNumberNotation notation)

将实数符号设置为notation (SmartNotation,FixedNotation,ScientificNotation)。在读取和生成数字时，QTextStream 会使用该值来检测实数的格式。

另请参阅 realNumberNotation(),setRealNumberPrecision(),setNumberFlags() 和setIntegerBase().

void QTextStream::setRealNumberPrecision(int precision)

设置precision 的实数精度。该值描述了QTextStream 在生成实数时应写入的分数位数 (FixedNotation,ScientificNotation) 或最大有效位数 (SmartNotation)。

精度不能为负值。默认值为 6。

另请参阅 realNumberPrecision() 和setRealNumberNotation()。

void QTextStream::setStatus(QTextStream::Status status)

将文本流的状态设置为status 。

在调用resetStatus() 之前，对 setStatus() 的后续调用将被忽略。

另请参阅 Status 、status() 和resetStatus()。

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

使用给定的openMode 将当前字符串设置为string 。如果已经分配了一个设备，QTextStream 将在替换它之前调用flush() 。

另请参阅 string() 和setDevice()。

void QTextStream::skipWhiteSpace()

读取并丢弃数据流中的空白字符，直到检测到非空格字符或atEnd() 返回 true。该函数在逐个字符读取数据流时非常有用。

空白字符是QChar::isSpace() 返回true 的所有字符。

另请参见 operator>>()。

QTextStream::Status QTextStream::status() const

返回文本流的状态。

另请参阅 QTextStream::Status,setStatus() 和resetStatus()。

QString *QTextStream::string() const

返回分配给QTextStream 的当前字符串，如果没有分配字符串，则返回nullptr 。

另请参阅 setString() 和device()。

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

将字符c 写入数据流，然后返回对QTextStream 的引用。

另请参阅 setFieldWidth() 。

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

将字符串string 写入数据流，并返回指向QTextStream 的引用。在将字符串写入数据流之前，首先使用指定的编码（默认为 UTF-8）对其进行编码。

另请参阅 setFieldWidth() 和setEncoding()。

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

将实数f 写入数据流，然后返回QTextStream 的引用。默认情况下，QTextStream 使用SmartNotation 进行存储，精度可达 6 位数。您可以通过调用setRealNumberNotation(),setRealNumberPrecision() 和setNumberFlags() 来更改QTextStream 对实数使用的文本表示法。

另请参见 setFieldWidth()、setRealNumberNotation()、setRealNumberPrecision() 和setNumberFlags()。

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

将整数i 写入数据流，然后返回对QTextStream 的引用。默认情况下，数字以十进制形式存储，但也可以通过调用setIntegerBase() 设置基数。

另请参阅 setFieldWidth() 和setNumberFlags()。

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

这是一个重载函数。

将string 写入数据流，并返回QTextStream 的引用。

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

这是一个重载函数。

将string 写入数据流，并返回QTextStream 的引用。

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

这是一个重载函数。

将c 从 ASCII 转换为QChar ，然后写入数据流。

[since 6.3.1] QTextStream &QTextStream::operator<<(char16_t c)

这是一个重载函数。

将 Unicode 字符c 写入流，然后返回对QTextStream 的引用。

该函数在 Qt 6.3.1 中引入。

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

这是一个重载函数。

将array 写入数据流。array 的内容通过QString::fromUtf8() 转换。

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

这是一个重载函数。

将string 指向的常量字符串写入数据流。假定string 采用 UTF-8 编码。该操作符在处理常量字符串数据时非常方便。示例

QTextStream out(stdout);
out << "Qt rocks!" << Qt::endl;

警告：QTextStream 假定string 指向以"\0 "字符结束的文本字符串。如果没有以'\0'字符结束，应用程序可能会崩溃。

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

这是一个重载函数。

将ptr 写入带进制的十六进制数据流。

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

这是一个重载函数。

将双f 写入数据流。

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

这是一个重载函数。

将有符号 inti 写入数据流。

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

这是一个重载函数。

将带符号的长i 写入数据流。

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

这是一个重载函数。

将 qlonglongi 写入数据流。

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

这是一个重载函数。

将 qulonglongi 写入数据流。

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

这是一个重载函数。

将无符号 inti 写入数据流。

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

这是一个重载函数。

将无符号长i 写入数据流。

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

这是一个重载函数。

将无符号短i 写入数据流。

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

从数据流中读取字符并将其存储在c 中。返回QTextStream 的引用，因此可以嵌套多个操作符。例如

QTextStream in(file);
QChar ch1, ch2, ch3;
in >> ch1 >> ch2 >> ch3;

不跳过空白。

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

从数据流中读取一个单词并将其存储在str 中，然后返回对数据流的引用。单词之间用空白分隔（即QChar::isSpace() 返回true 的所有字符）。

跳过前导空白。

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

从数据流中读取一个实数并将其存储在f 中，然后返回QTextStream 的引用。该数字将被转换为正确的类型。如果数据流中没有检测到实数，f 将被设置为 0.0。

作为一个特殊例外，QTextStream 允许使用字符串 "nan "和 "inf "来表示 NAN 和 INF 浮点数或二进制数。

跳过前导空白。

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

从数据流中读取一个整数并将其存储在i 中，然后返回QTextStream 的引用。在存储之前，数字会被转换为正确的类型。如果在数据流中没有检测到数字，i 将被设置为 0。

默认情况下，QTextStream 将尝试使用以下规则检测数字的基数：

通过调用setIntegerBase() 可以明确指定整数基数。这将禁用自动检测功能，并略微加快QTextStream 的运行速度。

跳过前导空白。

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

这是一个重载函数。

将字转换为 UTF-8，然后存储在array 中。

另请参见 QString::toLatin1().

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

这是一个重载函数。

从数据流中读取字符并将其存储在c 中。从数据流中读取的字符在存储前会转换为 ISO-8859-1 格式。

另请参阅 QChar::toLatin1() 。

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

这是一个重载函数。

将单词转换为 UTF-8 格式并存储在c 中，以"\0 "字符结束。如果没有单词，则只存储"\0 "字符。

警告：QTextStream 假定c 指向一个有足够空间容纳字的缓冲区。如果缓冲区太小，应用程序可能会崩溃。对于由n QChars 组成的单词，缓冲区的长度至少要达到3*n+1 个字符。

如果可能，请使用QByteArray 操作符。

[since 6.4] QTextStream &QTextStream::operator>>(char16_t &c)

这是一个重载函数。

从数据流中读取一个字符并将其存储在c 中。

该函数在 Qt 6.4 中引入。

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

这是一个重载函数。

将实数存储在双f 中。

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

这是一个重载函数。

将整数存储在有符号 inti 中。

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

这是一个重载函数。

将整数存储在带符号 longi 中。

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

这是一个重载函数。

将整数存储在 qlonglongi 中。

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

这是一个重载函数。

将整数存储在 qulonglongi 中。

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

这是一个重载函数。

将整数存储在无符号 inti 中。

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

这是一个重载函数。

将整数存储在无符号 longi 中。

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

这是一个重载函数。

将整数存储在无符号短i 中。