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

返回此流的区域设置。默认区域设置为 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() 将返回一个 nullQString 。对于字符串，或者对于支持该功能的设备，您可以使用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 ` 为真，则 `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()。

[since 6.0] void QTextStream::setEncoding(QStringConverter::Encoding encoding)

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

如果 `QTextStream ` 操作的对象是字符串，则此函数不执行任何操作。

该函数在 Qt 6.0 中引入。

另请参阅 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 。指定的区域设置用于在数字与其字符串表示形式之间进行转换。

默认区域设置为 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)

将当前字符串设置为string ，并使用给定的openMode 。如果设备已被分配，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()。

[explicit noexcept, since 6.10] QTextStream::operator bool() const

返回该流是否无错误（status() 返回Ok ）。

该函数在 Qt 6.10 中引入。

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)

将带符号整数i 写入流中。

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

将带符号的长整型i 写入流中。

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

将 qlonglong 类型的i 写入流中。

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

将 qulonglongi 写入流中。

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

将无符号整数i 写入流中。

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()。

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

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

该函数在 Qt 6.4 中引入。

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

将实数存储在双精度变量f 中。

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

将该整数存储在带符号整型变量i 中。

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

将该整数存储在带符号长整型变量i 中。

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

将该整数存储到 qlonglong 类型的变量 `i` 中。

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

将该整数存储到 qulonglong 类型的变量i 中。

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

将该整数存储在无符号整型变量i 中。

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

将该整数存储到无符号长整型变量i 中。

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

将该整数存储在无符号短整型变量i 中。