Qt-快速上手-QTextStream

QTextStream

QTextStream 属于 Qt Core 模块，头文件：#include <QTextStream>，需要 QT += core。

作用：对 QIODevice（文件、socket、内存缓冲区 QByteArray）做文本读写，自动处理编码、换行、格式化输入输出，类似 C++ std::iostream。

注意：QTextStream 不是读写二进制，是文本流；二进制请用 QDataStream。

常用成员

/**
* @class QTextStream
* @brief Qt 文本流类，用于文本的格式化读写，类似C++ std::iostream
*
* QTextStream 可以操作 QFile、QBuffer、QTcpSocket 等 QIODevice 子类，
* 也可以直接操作 QString / QByteArray。支持编码设置、字段宽度、对齐、数字进制等格式化。
*
* @headerfile <QTextStream>
* @note QT += core
*
* 典型使用场景：
* – 读写文本文件(.txt/.csv)
* – 字符串文本解析与组装
* – 控制台 stdin/stdout 读写
*
* 编码默认：系统本地编码；推荐手动 setCodec() / setEncoding() 指定 UTF‑8
*/
class QTextStream
{
public:

/**
* @brief 构造函数：绑定一个IO设备
* @param device 已打开的 QIODevice 指针，所有权不归QTextStream
*/
explicit QTextStream(QIODevice *device);

/**
* @brief 构造函数：直接读写 QByteArray 内存缓冲区
* @param array 字节数组缓冲区
* @param openMode 打开模式 QIODevice::ReadOnly / WriteOnly / ReadWrite
*/
QTextStream(QByteArray *array, QIODevice::OpenMode openMode = QIODevice::ReadWrite);

/**
* @brief 构造函数：读写 QString 字符串缓冲区
* @param str QString对象，用于in‑memory文本流
*/
QTextStream(QString *str);

/**
* @brief 默认构造，无绑定设备，后续使用 setDevice() 绑定
*/
QTextStream();

//————————————————————————–
/// 设备绑定相关
/**
* @brief 设置流绑定的IODevice
* @param dev IO设备指针，nullptr解除绑定
*/
void setDevice(QIODevice *dev);

/**
* @brief 获取当前绑定的IODevice
* @return QIODevice*，没有则返回nullptr
*/
QIODevice *device() const;

/**
* @brief 设置内部字符串缓冲区，不再使用device
* @param str 目标QString
*/
void setString(QString *str);

//————————————————————————–
/// 编码设置（Qt5/Qt6差异重点）
#if QT_VERSION < QT_VERSION_CHECK(6,0,0)
/**
* @brief 设置文本编码(Qt5)，推荐 QTextCodec::codecForName("UTF‑8")
* @param codec 编码对象指针
*/
void setCodec(QTextCodec *codec);
QTextCodec *codec() const;
#else
/**
* @brief 设置文本编码(Qt6)
* @param encoding QStringConverter::Encoding 如 QStringConverter::Utf8
*/
void setEncoding(QStringConverter::Encoding encoding);
QStringConverter::Encoding encoding() const;
#endif

//————————————————————————–
/// 读行、读取内容
/**
* @brief 读取一行文本，自动丢弃行尾换行符 \\n / \\r\\n
* @return QString 读到的一行；读到末尾返回空字符串，需要用 atEnd() 判断
* @warning 不要用返回空串判断文件结束，必须使用 atEnd()
*/
QString readLine(qint64 maxlen = 0);

/**
* @brief 读取全部剩余文本
* @return QString 全部内容
*/
QString readAll();

/**
* @brief 读取最多maxlen个字符
* @param maxlen 最大字符数
* @return QString
*/
QString read(qint64 maxlen);

//————————————————————————–
/// 流状态判断
/**
* @brief 是否到达流末尾（文件/缓冲区读完）
* @return true 已经读到末尾
*/
bool atEnd() const;

/**
* @brief 流是否发生错误
* @return true 读写出错
*/
bool hasError() const;

/**
* @brief 重置流错误状态
*/
void resetStatus();

//————————————————————————–
/// 输出格式化：对齐、宽度、填充、数字进制
/**
* @brief 设置输出字段宽度，单位：字符数
* @param width 宽度，0代表自动
* @return 返回自身引用，支持链式调用
*/
QTextStream &setFieldWidth(int width);

/**
* @brief 设置填充字符，不足宽度时填充
* @param ch 填充字符，如 ' '、'0'
* @return QTextStream&
*/
QTextStream &setPadChar(QChar ch);

/**
* @brief 设置对齐方式 Qt::AlignLeft / Qt::AlignRight / Qt::AlignCenter
* @param align 对齐标记
* @return QTextStream&
*/
QTextStream &setFieldAlignment(Qt::Alignment align);

enum NumberBase {
Dec = 10, ///< 十进制
Hex = 16, ///< 十六进制
Oct = 8, ///< 八进制
Bin = 2 ///< 二进制
};

/**
* @brief 设置整数输出进制 Dec/Hex/Oct/Bin
* @param base 进制
* @return QTextStream&
*/
QTextStream &setIntegerBase(int base);

/**
* @brief 设置浮点数输出精度
* @param digits 有效数字位数
* @return QTextStream&
*/
QTextStream &setRealNumberPrecision(int digits);

//————————————————————————–
/// 流运算符 << 输出； >> 输入
/*
* 支持类型：QString, QByteArray, int, long long, double, bool, char 等
*
* 示例：
* @code
* QTextStream out(&file);
* out << "value=" << 123 << "\\n";
* int a;
* in >> a;
* @endcode
*/
QTextStream &operator<<(const QString &str);
QTextStream &operator<<(int val);
QTextStream &operator<<(double val);

QTextStream &operator>>(QString &str);
QTextStream &operator>>(int &i);
QTextStream &operator>>(double &d);

//————————————————————————–
/// 全局标准流对象
/**
* @brief 标准输出（控制台 stdout）
*/
static QTextStream &stdout();
/**
* @brief 标准输入（控制台 stdin）
*/
static QTextStream &stdin();
/**
* @brief 标准错误输出 stderr
*/
static QTextStream &stderr();
};

/// 流操纵符（全局函数，直接写在流中）
/**
* @brief endl：输出换行，并flush刷新缓冲区
*/
QTextStream &endl(QTextStream &s);

/**
* @brief flush：强制刷新缓冲区，把缓存写入底层设备
*/
QTextStream &flush(QTextStream &s);

/**
* @brief ws：跳过输入流中的空白字符(空格、tab、换行)
*/
QTextStream &ws(QTextStream &s);

快速上手

练习一：写文本文件 + 格式化输出

打开文本文件，并且格式化输出字符到文件。

#include <QCoreApplication>
#include <QFile>
#include <QTextStream>

#include <QApplication>

int main(int argc, char *argv[])
{
QCoreApplication a(argc, argv);

QFile file("test.txt");
if (!file.open(QIODevice::WriteOnly | QIODevice::Text)) {
qWarning() << "open filed:" << file.errorString();
return -1;
}

QTextStream out(&file);
#if QT_VERSION >= QT_VERSION_CHECK(6,0,0)
out.setEncoding(QStringConverter::Utf8);
#else
out.setCodec("UTF-8");
#endif

// 格式化输出
out.setFieldWidth(10);
out.setFieldAlignment(QTextStream::AlignRight);
out.setPadChar(' ');

out << "ID" << "Name" << "Score" << "\\n";
out << 1 << "ZhangSan" << 95.5 << "\\n";
out << 2 << "LiSi" << 88.0 << "\\n";

file.close();
qDebug() << "write done";
return a.exec();
}

练习 2：读取文本文件，逐行解析

打开文本，逐行读并打印在控制台

#include <QCoreApplication>
#include <QFile>
#include <QTextStream>

#include <QApplication>

int main(int argc, char *argv[])
{
QCoreApplication a(argc, argv);

QFile file("test.txt");
if (!file.open(QIODevice::ReadOnly | QIODevice::Text)) {
qWarning() << "open read file:" << file.errorString();
return -1;
}

QTextStream in(&file);
#if QT_VERSION >= QT_VERSION_CHECK(6,0,0)
in.setEncoding(QStringConverter::Utf8);
#else
in.setCodec("UTF-8");
#endif

while(!in.atEnd()){
qDebug() << in.readLine();
}

file.close();
qDebug() << "read done";
return a.exec();
}

练习 3：内存流，直接读写 QString（不操作磁盘）

直接读写内存中的QString

#include <QCoreApplication>
#include <QFile>
#include <QTextStream>

#include <QApplication>

int main(int argc, char *argv[])
{
QCoreApplication a(argc, argv);

QString s;
QTextStream stream(&s);

stream << "Hello";
stream << 123;
stream << 1.23;

QString res1;
int res2;
double res3;

stream.seek(0);
stream >> res1 >> res2 >> res3;
qDebug() << res1 << res2 << res3;

return a.exec();
}