QFile 类提供用于读写文件的接口。 更多...
头: | #include <QFile> |
qmake: | QT += core |
继承: | QFileDevice |
继承者: |
注意: 此类的所有函数 可重入 .
typedef | DecoderFn |
QFile (const QString & name , QObject * parent ) | |
QFile (QObject * parent ) | |
QFile (const QString & name ) | |
QFile () | |
virtual | ~QFile () |
bool | copy (const QString & newName ) |
bool | exists () const |
bool | link (const QString & linkName ) |
bool | moveToTrash () |
bool | open (FILE * fh , QIODevice::OpenMode mode , QFileDevice::FileHandleFlags handleFlags = DontCloseHandle) |
bool | open (int fd , QIODevice::OpenMode mode , QFileDevice::FileHandleFlags handleFlags = DontCloseHandle) |
bool | remove () |
bool | rename (const QString & newName ) |
void | setFileName (const QString & name ) |
QString | symLinkTarget () const |
virtual QString | fileName () const override |
virtual bool | open (QIODevice::OpenMode mode ) override |
virtual QFileDevice::Permissions | permissions () const override |
virtual bool | resize (qint64 sz ) override |
virtual bool | setPermissions (QFileDevice::Permissions permissions ) override |
virtual qint64 | size () const override |
bool | copy (const QString & fileName , const QString & newName ) |
QString | decodeName (const QByteArray & localFileName ) |
QString | decodeName (const char * localFileName ) |
QByteArray | encodeName (const QString & fileName ) |
bool | exists (const QString & fileName ) |
bool | link (const QString & fileName , const QString & linkName ) |
bool | moveToTrash (const QString & fileName , QString * pathInTrash = nullptr) |
QFileDevice::Permissions | permissions (const QString & fileName ) |
bool | remove (const QString & fileName ) |
bool | rename (const QString & oldName , const QString & newName ) |
bool | resize (const QString & fileName , qint64 sz ) |
bool | setPermissions (const QString & fileName , QFileDevice::Permissions permissions ) |
QString | symLinkTarget (const QString & fileName ) |
QFile 是 I/O 设备用于读写文本、二进制文件及 resources 。QFile 可以单独使用,或更方便一起使用与 QTextStream or QDataStream .
通常在构造函数中传递文件名,但可以随时设置它使用 setFileName ()。QFile 期望文件分隔符为 / 不管操作系统。不支持使用其它分隔符 (如:\)。
可以检查文件是否存在使用 exists (),和移除文件使用 remove ()。(更高级的文件系统相关操作的提供由 QFileInfo and QDir )。
打开文件采用 open (),关闭采用 close (),和刷新采用 flush ()。数据的读写通常是使用 QDataStream or QTextStream ,但也可以调用 QIODevice 继承函数 read (), readLine (), readAll (), write ()。QFile 还继承 getChar (), putChar (),和 ungetChar (),每次操控一字符。
文件大小的返回是通过
size
()。可以获取当前文件位置使用
pos
(),或移至新文件位置使用
seek
()。若已到达 EOF (文件末尾),
atEnd
() 返回
true
.
以下范例逐行读取文本文件:
QFile file("in.txt"); if (!file.open(QIODevice::ReadOnly | QIODevice::Text)) return; while (!file.atEnd()) { QByteArray line = file.readLine(); process_line(line); }
The QIODevice::Text flag passed to open () 告诉 Qt 要转换 Windows 样式行终止符 \r\n 成 C++ 样式终止符 \n。默认情况下,QFile 假定为二进制 (即:对存储在文件中的字节,不履行任何转换)。
下一范例使用 QTextStream 以逐行读取文本文件:
QFile file("in.txt"); if (!file.open(QIODevice::ReadOnly | QIODevice::Text)) return; QTextStream in(&file); while (!in.atEnd()) { QString line = in.readLine(); process_line(line); }
QTextStream 负责将存储在磁盘中的 8 位数据转换成 16 位 Unicode QString . By default, it assumes that the user system's local 8-bit encoding is used (e.g., UTF-8 on most unix based operating systems; see QTextCodec::codecForLocale () for details). This can be changed using QTextStream::setCodec ().
要写入文本,可以使用操作符 <<(),重载以接受 QTextStream 在左侧和各种数据类型 (包括 QString ) 在右侧:
QFile file("out.txt"); if (!file.open(QIODevice::WriteOnly | QIODevice::Text)) return; QTextStream out(&file); out << "The magic number is: " << 49 << "\n";
QDataStream 类似,可以使用操作符 <<() 写入数据,和使用操作符 >>() 读回它。见类文档编制,了解细节。
When you use QFile,
QFileInfo
,和
QDir
to access the file system with Qt, you can use Unicode file names. On Unix, these file names are converted to an 8-bit encoding. If you want to use standard C++ APIs (
<cstdio>
or
<iostream>
) or platform-specific APIs to access files instead of QFile, you can use the
encodeName
() 和
decodeName
() functions to convert between Unicode file names and 8-bit file names.
在 Unix,有一些特殊系统文件 (如在
/proc
) 其中
size
() 将始终返回 0,仍然可以从这种文件读取更多数据;直接生成数据是为响应调用
read
()。在此情况下,不管怎样,不可以使用
atEnd
() 以确定是否有更多数据要读取 (由于
atEnd
() 将返回 true 对于声明拥有大小 0 的文件)。相反,应该调用
readAll
(),或调用
read
() 或
readLine
() 重复,直到无法读取更多数据。下一范例使用
QTextStream
以读取
/proc/modules
逐行:
QFile file("/proc/modules"); if (!file.open(QIODevice::ReadOnly | QIODevice::Text)) return; QTextStream in(&file); QString line = in.readLine(); while (!line.isNull()) { process_line(line); line = in.readLine(); }
不像其它 QIODevice 实现,譬如 QTcpSocket ,QFile 不会发射 aboutToClose (), bytesWritten (),或 readyRead () 信号。此实现细节意味着 QFile 不适合读写某些类型的文件,譬如 Unix 平台中的设备文件。
文件权限的处理是不同的,在像 Unix 系统和 Windows。在非 writable 目录像 Unix 系统,无法创建文件。在 Windows 并不始终如此,例如,"我的文档" 目录通常不可写,但可以在其中创建文件仍然是可能的。
Qt 对文件权限的理解是有限的,这尤其影响 QFile::setPermissions () 函数。在 Windows,Qt 将只设置遗留只读标志,且仅当未传递 Write* 标志时。Qt 不操纵 ACL (访问控制列表),这使得此函数对 NTFS 卷几乎无用。它仍然可以用于使用 VFAT 文件系统的 U 盘。也不操纵 POSIX ACL。
在 Android,会应用一些局限性当处理 内容 URI (统一资源标识符) :
另请参阅 QTextStream , QDataStream , QFileInfo , QDir ,和 Qt 资源系统 .
这是采用以下签名的函数指针的 typedef:
QString myDecoderFunc(const QByteArray &localFileName);
另请参阅 setDecodingFunction ().
构造新文件对象采用给定 parent 表示文件采用指定 name .
构造新文件对象采用给定 parent .
构造新文件对象以表示文件采用给定 name .
构造 QFile 对象。
[虚拟]
QFile::
~QFile
()
销毁文件对象,关闭它若有必要。
拷贝文件命名 fileName () 到 newName .
此文件被关闭,在拷贝它之前。
若拷贝的文件是 symlink (符号链接),拷贝的就是它引用的文件,而不是链接本身。除拷贝权限外,不会拷贝其它文件元数据。
返回
true
若成功;否则返回
false
.
注意:若文件采用名称
newName
已存在,copy() 返回
false
。这意味着
QFile
不会覆写它。
注意:
在 Android,此操作尚不支持
content
方案 URI (统一资源标识符)。
另请参阅 setFileName ().
[static]
bool
QFile::
copy
(const
QString
&
fileName
, const
QString
&
newName
)
这是重载函数。
拷贝文件命名 fileName to newName .
此文件被关闭,在拷贝它之前。
若拷贝的文件是 symlink (符号链接),拷贝的就是它引用的文件,而不是链接本身。除拷贝权限外,不会拷贝其它文件元数据。
返回
true
若成功;否则返回
false
.
注意:若文件采用名称
newName
已存在,copy() 返回
false
。这意味着
QFile
不会覆写它。
注意:
在 Android,此操作尚不支持
content
方案 URI (统一资源标识符)。
另请参阅 rename ().
[static]
QString
QFile::
decodeName
(const
QByteArray
&
localFileName
)
这做反向 QFile::encodeName () 使用 localFileName .
另请参阅 encodeName ().
[static]
QString
QFile::
decodeName
(const
char
*
localFileName
)
这是重载函数。
返回 Unicode 版本为给定 localFileName 。见 encodeName () 了解细节。
[static]
QByteArray
QFile::
encodeName
(const
QString
&
fileName
)
转换 fileName to the local 8-bit encoding determined by the user's locale. This is sufficient for file names that the user chooses. File names hard-coded into the application should only use 7-bit ASCII filename characters.
另请参阅 decodeName ().
[static]
bool
QFile::
exists
(const
QString
&
fileName
)
返回
true
若文件指定通过
fileName
存在;否则返回
false
.
注意: 若 fileName 是指向不存在文件的符号链接,返回 false。
这是重载函数。
返回
true
若文件指定通过
fileName
() 存在;否则返回
false
.
另请参阅 fileName () 和 setFileName ().
[override virtual]
QString
QFile::
fileName
() const
重实现: QFileDevice::fileName () const.
返回名称设置通过 setFileName () 或到 QFile 构造函数。
另请参阅 setFileName () 和 QFileInfo::fileName ().
创建链接命名
linkName
指向文件目前指定通过
fileName
()。链接是什么从属底层文件系统 (不管是 Windows 快捷方式,还是 Unix 符号链接)。返回
true
若成功;否则返回
false
.
此函数不会覆写文件系统中已存在的实体;在此情况下,
link()
将返回 false 并设置
error()
to return
RenameError
.
注意:
要在 Windows 创建有效链接,
linkName
必须拥有
.lnk
文件扩展名。
另请参阅 setFileName ().
[static]
bool
QFile::
link
(const
QString
&
fileName
, const
QString
&
linkName
)
这是重载函数。
创建链接命名
linkName
指向文件
fileName
。链接是什么从属底层文件系统 (不管是 Windows 快捷方式,还是 Unix 符号链接)。返回
true
若成功;否则返回
false
.
另请参阅 link ().
移动指定文件按
fileName
() 到垃圾桶。返回
true
若成功,并设置
fileName
() 为可以在垃圾桶中找到的文件路径;否则返回
false
.
注意: 在系统 API 不报告垃圾桶中文件位置的系统中, fileName () 会被设为 null 字符串,一旦移动文件。在没有垃圾桶的系统中,此函数始终返回 false。
该函数在 Qt 5.15 引入。
[static]
bool
QFile::
moveToTrash
(const
QString
&
fileName
,
QString
*
pathInTrash
= nullptr)
这是重载函数。
移动指定文件按
fileName
() 到垃圾桶。返回
true
若成功,并设置
pathInTrash
(若有提供) 为可以在垃圾桶中找到的文件路径;否则返回
false
.
注意: 在系统 API 不报告垃圾桶中文件路径在哪里的系统中, pathInTrash 会被设为 null 字符串,一旦移动文件。在没有垃圾桶的系统中,此函数始终返回 false。
该函数在 Qt 5.15 引入。
[override virtual]
bool
QFile::
open
(
QIODevice::OpenMode
mode
)
重实现: QIODevice::open (QIODevice::OpenMode mode).
打开文件使用 OpenMode mode ,返回 true,若成功;否则返回 false。
The mode 必须为 QIODevice::ReadOnly , QIODevice::WriteOnly ,或 QIODevice::ReadWrite 。它还可以拥有额外标志,譬如 QIODevice::Text and QIODevice::Unbuffered .
注意: 在 WriteOnly or ReadWrite mode, if the relevant file does not already exist, this function will try to create a new file before opening it. On Android, it's expected to have access permission to the parent of the file name, otherwise, it won't be possible to create this non-existing file.
另请参阅 QIODevice::OpenMode and setFileName ().
这是重载函数。
打开现有文件句柄
fh
以给定
mode
.
handleFlags
可以用于指定额外选项。返回
true
若成功;否则返回
false
.
范例:
#include <stdio.h> void printError(const char* msg) { QFile file; file.open(stderr, QIODevice::WriteOnly); file.write(msg, qstrlen(msg)); // write to stderr file.close(); }
当 QFile 是使用此函数打开的,行为对于 close () is controlled by the AutoCloseHandle flag. If AutoCloseHandle is specified, and this function succeeds, then calling close () 会关闭采纳句柄。否则, close () 不会实际关闭文件,而仅刷新它。
警告:
stdin
,
stdout
,或
stderr
,可能无法
seek
().
size
() 返回
0
在此情况下。见
QIODevice::isSequential
() 了解更多信息。
Windows 平台注意事项
fh must be opened in binary mode (i.e., the mode string must contain 'b', as in "rb" or "wb") when accessing files and other random-access devices. Qt will translate the end-of-line characters if you pass QIODevice::Text to mode 。顺序设备 (譬如:stdin 和 stdout) 不受此局限性的影响。
需要启用对控制台应用程序的支持,为在控制台使用 stdin (标准输入)、stdout (标准输出) 及 stderr (标准错误) 流。要做到这,把以下声明添加到应用程序工程文件:
CONFIG += console
另请参阅 close ().
这是重载函数。
打开现有文件描述符
fd
以给定
mode
.
handleFlags
可以用于指定额外选项。返回
true
若成功;否则返回
false
.
当 QFile 是使用此函数打开的,行为对于 close () is controlled by the AutoCloseHandle flag. If AutoCloseHandle is specified, and this function succeeds, then calling close () 会关闭采纳句柄。否则, close () 不会实际关闭文件,而仅刷新它。
警告:
若
fd
不是常规文件,如为 0 (
stdin
), 1 (
stdout
),或 2 (
stderr
),可能无法
seek
()。在此情况下,
size
() 返回
0
。见
QIODevice::isSequential
() 了解更多信息。
警告: 由于此函数打开文件不用指定文件名,所以,无法使用此 QFile 采用 QFileInfo .
另请参阅 close ().
[override virtual]
QFileDevice::Permissions
QFile::
permissions
() const
重实现: QFileDevice::permissions () const.
另请参阅 setPermissions ().
[static]
QFileDevice::Permissions
QFile::
permissions
(const
QString
&
fileName
)
这是重载函数。
Returns the complete OR-ed together combination of QFile::Permission for fileName .
移除文件指定通过
fileName
()。返回
true
若成功;否则返回
false
.
文件被关闭,在移除它之前。
另请参阅 setFileName ().
[static]
bool
QFile::
remove
(const
QString
&
fileName
)
这是重载函数。
移除文件指定通过 fileName 给定。
返回
true
若成功;否则返回
false
.
另请参阅 remove ().
重命名文件目前指定通过
fileName
() 到
newName
。返回
true
若成功;否则返回
false
.
若文件采用名称
newName
已存在,rename() 返回
false
(即,
QFile
不会覆写它)。
文件关闭,在重命名之前。
若重命名操作失败,Qt 将试图把此文件的内容拷贝到 newName ,然后移除此文件,仅保持 newName 。若该拷贝操作失败 (或无法移除此文件),目的地文件 newName 被移除以还原旧状态。
另请参阅 setFileName ().
[static]
bool
QFile::
rename
(const
QString
&
oldName
, const
QString
&
newName
)
这是重载函数。
重命名文件
oldName
to
newName
。返回
true
若成功;否则返回
false
.
若文件采用名称
newName
已存在,rename() 返回
false
(即,
QFile
不会覆写它)。
另请参阅 rename ().
[override virtual]
bool
QFile::
resize
(
qint64
sz
)
重实现: QFileDevice::resize (qint64 sz).
[static]
bool
QFile::
resize
(const
QString
&
fileName
,
qint64
sz
)
这是重载函数。
设置
fileName
到大小 (以字节为单位)
sz
。返回
true
若重置大小成功;否则 false。若
sz
>
fileName
目前是新字节数将被设为 0,若
sz
更小,只需截取文件。
警告: 此函数可能失败,若文件不存在。
另请参阅 resize ().
设置 name 为文件。名称可以没有路径、相对路径或绝对路径。
不要调用此函数,若文件已打开。
若文件名没有路径 (或相对路径),使用的路径将是应用程序的当前目录路径 当 open () 调用。
范例:
QFile file; QDir::setCurrent("/tmp"); file.setFileName("readme.txt"); QDir::setCurrent("/home"); file.open(QIODevice::ReadOnly); // opens "/home/readme.txt" under Unix
注意,目录分隔符 / 工作于由 Qt 支持的所有操作系统。
另请参阅 fileName (), QFileInfo ,和 QDir .
[override virtual]
bool
QFile::
setPermissions
(
QFileDevice::Permissions
permissions
)
重实现: QFileDevice::setPermissions (QFileDevice::Permissions permissions).
将文件权限设为
permissions
指定。返回
true
若成功,或
false
若权限不能被修改。
警告: 此函数不操纵 ACL (访问控制列表),这可能限制其有效性。
另请参阅 permissions () 和 setFileName ().
[static]
bool
QFile::
setPermissions
(const
QString
&
fileName
,
QFileDevice::Permissions
permissions
)
这是重载函数。
设置权限为 fileName 文件到 permissions .
[override virtual]
qint64
QFile::
size
() const
重实现: QFileDevice::size () const.
[static]
QString
QFile::
symLinkTarget
(const
QString
&
fileName
)
返回符号链接 (或 Windows 快捷方式) 引用文件 (或目录) 的绝对路径指定通过 fileName ,或返回空字符串若 fileName 不对应于符号链接。
此名称可能不表示现有文件;它只是字符串。
QFile::exists
() 返回
true
若符号链接指向现有文件。
该函数在 Qt 4.2 引入。
这是重载函数。
返回符号链接 (或 Windows 快捷方式) 指向文件 (或目录) 的绝对路径,或空字符串若对象不是符号链接。
此名称可能不表示现有文件;它只是字符串。
QFile::exists
() 返回
true
若符号链接指向现有文件。
该函数在 Qt 4.2 引入。
另请参阅 fileName () 和 setFileName ().