Класс QFileInfo

Класс QFileInfo предоставляет независимую от системы информацию о файле. Подробнее...

• Список всех членов, включая унаследованные
• Устаревшие члены

Примечание: Все функции в этом классе являются реентерабельными.

Открытые функции

Статические открытые члены

Связанные внешние члены

Подробное описание

Класс QFileInfo предоставляет независимую от системы информацию о файле.

QFileInfo предоставляет информацию о имени файла и его расположении (пути) в файловой системе, правах доступа и является ли он каталогом или символической ссылкой и т. д. Также доступны размер файла и время последнего изменения/чтения. QFileInfo также может использоваться для получения информации о Qt ресурсе.

QFileInfo может указывать на файл с относительным или абсолютным путем к файлу. Абсолютные пути к файлам начинаются с разделителя каталогов "/" (или с указания диска в Windows). Относительные имена файлов начинаются с имени каталога или имени файла и указывают путь относительно текущей рабочей директории. Пример абсолютного пути — строка "/tmp/quartz". Относительный путь может выглядеть как "src/fatlib". Вы можете использовать функцию isRelative() для проверки того, использует ли QFileInfo относительный или абсолютный путь к файлу. Вы можете вызвать функцию makeAbsolute() для преобразования относительного пути QFileInfo в абсолютный путь.

Файл, с которым работает QFileInfo, задаётся в конструкторе или позже с помощью setFile(). Используйте exists(), чтобы проверить, существует ли файл, и size(), чтобы получить его размер.

Тип файла получается с помощью isFile(), isDir() и isSymLink(). Функция symLinkTarget() возвращает имя файла, на который указывает символическая ссылка.

В Unix (включая macOS и iOS) символическая ссылка имеет тот же размер size(), что и файл, на который она указывает, поскольку Unix обрабатывает символические ссылки прозрачно; аналогично, открытие символической ссылки с помощью QFile фактически открывает целевой файл ссылки. Например:

#ifdef Q_OS_UNIX

QFileInfo info1("/home/bob/bin/untabify");
info1.isSymLink();          // returns true
info1.absoluteFilePath();   // returns "/home/bob/bin/untabify"
info1.size();               // returns 56201
info1.symLinkTarget();      // returns "/opt/pretty++/bin/untabify"

QFileInfo info2(info1.symLinkTarget());
info2.isSymLink();          // returns false
info2.absoluteFilePath();   // returns "/opt/pretty++/bin/untabify"
info2.size();               // returns 56201

#endif

В Windows символические ссылки (ярлыки) являются .lnk файлами. Сообщённый размер size() относится к размеру символической ссылки (а не целевому файлу), и открытие символической ссылки с помощью QFile открывает .lnk файл. Например:

#ifdef Q_OS_WIN

QFileInfo info1("C:\\Documents and Settings\\Bob\\untabify.lnk");
info1.isSymLink();          // returns true
info1.absoluteFilePath();   // returns "C:/Documents and Settings/Bob/untabify.lnk"
info1.size();               // returns 743
info1.symLinkTarget();      // returns "C:/Pretty++/untabify"

QFileInfo info2(info1.symLinkTarget());
info2.isSymLink();          // returns false
info2.absoluteFilePath();   // returns "C:/Pretty++/untabify"
info2.size();               // returns 63942

#endif

Элементы имени файла могут быть извлечены с помощью path() и fileName(). Части fileName() могут быть извлечены с помощью baseName(), suffix() или completeSuffix(). Объекты QFileInfo для каталогов, созданных классами Qt, не будут содержать конечный разделитель файла. Если вы хотите использовать конечные разделители в собственных объектах file info, просто добавьте один к имени файла, переданному конструкторам или setFile().

Даты файла возвращаются методами created(), lastModified(), lastRead() и fileTime(). Информация о правах доступа к файлу получается с помощью isReadable(), isWritable() и isExecutable(). Владелец файла доступен через owner(), ownerId(), group() и groupId(). Вы можете проверить права доступа и владение файлом в одном выражении с помощью функции permission().

Примечание: В файловых системах NTFS проверка владения и прав доступа по умолчанию отключена по соображениям производительности. Чтобы включить её, добавьте следующую строку:

extern Q_CORE_EXPORT int qt_ntfs_permission_lookup;

Проверка прав доступа затем включается и выключается путём инкремента и декремента qt_ntfs_permission_lookup на 1.

qt_ntfs_permission_lookup++; // turn checking on
qt_ntfs_permission_lookup--; // turn it off again

Проблемы производительности

Некоторые функции QFileInfo запрашивают информацию из файловой системы, но по соображениям производительности некоторые функции работают только с самим именем файла. Например: для возвращения абсолютного пути относительного имени файла, absolutePath() должна запросить информацию из файловой системы. Функция path(), однако, может работать непосредственно с именем файла, поэтому она быстрее.

Примечание: Для повышения производительности QFileInfo кэширует информацию о файле.

Поскольку файлы могут изменяться другими пользователями или программами, или даже другими частями одной и той же программы, существует функция, которая обновляет информацию о файле: refresh(). Если вы хотите отключить кэширование QFileInfo и заставить его каждый раз обращаться к файловой системе при запросе информации, вызовите setCaching(false).

См. также QDir и QFile.

Документация по членам-функциям

QFileInfo::QFileInfo()

Создаёт пустой объект QFileInfo.

Обратите внимание, что пустой объект QFileInfo не содержит ссылки на файл.

См. также setFile().

QFileInfo::QFileInfo(const QString &file)

Создаёт новый объект QFileInfo, содержащий информацию о заданном файле. file также может содержать абсолютный или относительный путь.

См. также setFile(), isRelative(), QDir::setCurrent() и QDir::isRelativePath().

QFileInfo::QFileInfo(const QFile &file)

Создаёт новый объект QFileInfo, содержащий информацию о файле file.

Если у file относительный путь, то у QFileInfo также будет относительный путь.

См. также isRelative().

QFileInfo::QFileInfo(const QDir &dir, const QString &file)

Создаёт новый объект QFileInfo, содержащий информацию о заданном file в каталоге dir.

Если у dir относительный путь, то у QFileInfo также будет относительный путь.

Если file — абсолютный путь, то каталог, указанный dir, будет проигнорирован.

См. также isRelative().

QFileInfo::QFileInfo(const QFileInfo &fileinfo)

Создаёт новый объект QFileInfo, являющийся копией заданного fileinfo.

QFileInfo::~QFileInfo()

Удаляет объект QFileInfo и освобождает его ресурсы.

QDir QFileInfo::absoluteDir() const

Возвращает абсолютный путь к файлу как объект QDir.

См. также dir(), filePath(), fileName() и isRelative().

QString QFileInfo::absoluteFilePath() const

Возвращает абсолютный путь, включая имя файла.

Абсолютный путь состоит из полного пути и имени файла. В Unix он всегда начинается с корневого каталога '/'. В Windows он всегда начинается с 'D:/', где D — буква диска, за исключением сетевых ресурсов, которые не отображаются в виде буквы диска, в этом случае путь будет начинаться с '//sharename/'. QFileInfo преобразует буквы дисков в верхний регистр. Обратите внимание, что QDir этого не делает. Ниже приведен фрагмент кода, демонстрирующий это.

    QFileInfo fi("c:/temp/foo"); => fi.absoluteFilePath() => "C:/temp/foo"

Эта функция возвращает то же, что и filePath(), если только isRelative() не равно true. В отличие от canonicalFilePath(), символические ссылки или избыточные элементы "." или ".." не обязательно удаляются.

Предупреждение: Если filePath() пустое, поведение этой функции не определено.

См. также filePath(), canonicalFilePath() и isRelative().

QString QFileInfo::absolutePath() const

Возвращает абсолютный путь к файлу. Он не включает имя файла.

В Unix абсолютный путь всегда начинается с корневого каталога '/'. В Windows он всегда начинается с 'D:/', где D — буква диска, за исключением сетевых ресурсов, которые не отображаются в виде буквы диска, в этом случае путь будет начинаться с '//sharename/'.

В отличие от canonicalPath(), символические ссылки или избыточные элементы "." или ".." не обязательно удаляются.

Предупреждение: Если filePath() пустое, поведение этой функции не определено.

См. также absoluteFilePath(), path(), canonicalPath(), fileName() и isRelative().

QString QFileInfo::baseName() const

Возвращает имя файла без пути.

Имя файла состоит из всех символов в имени файла до (но не включая) первого символа ".".

Пример:

QFileInfo fi("/tmp/archive.tar.gz");
QString base = fi.baseName();  // base = "archive"

Имя файла вычисляется одинаково на всех платформах, независимо от соглашений об именовании файлов (например, ".bashrc" в Unix имеет пустое имя файла, а расширение — "bashrc").

См. также fileName(), suffix(), completeSuffix() и completeBaseName().

QDateTime QFileInfo::birthTime() const

Возвращает дату и время создания файла.

Если время создания файла недоступно, эта функция возвращает недействительный объект QDateTime.

Эта функция была введена в Qt 5.10.

См. также lastModified(), lastRead() и metadataChangeTime().

QString QFileInfo::bundleName() const

Возвращает имя пакета.

На macOS и iOS эта функция возвращает правильное локализованное имя пакета, если путь isBundle() указывает на пакет. На всех остальных платформах возвращается пустая QString.

Пример:

QFileInfo fi("/Applications/Safari.app");
QString bundle = fi.bundleName();                // name = "Safari"

Эта функция была добавлена в Qt 4.3.

См. также isBundle(), filePath(), baseName() и suffix().

bool QFileInfo::caching() const

Возвращает true , если кеширование включено; в противном случае возвращает false.

См. также setCaching() и refresh().

QString QFileInfo::canonicalFilePath() const

Возвращает канонический путь, включая имя файла, т.е. абсолютный путь без символических ссылок и лишних элементов «.» или «..».

Если файл не существует, canonicalFilePath() возвращает пустую строку.

См. также filePath(), absoluteFilePath() и dir().

QString QFileInfo::canonicalPath() const

Возвращает канонический путь к файлу (исключая имя файла), т.е. абсолютный путь без символических ссылок и лишних элементов «.» или «..».

Если файл не существует, canonicalPath() возвращает пустую строку.

См. также path() и absolutePath().

QString QFileInfo::completeBaseName() const

Возвращает полное имя файла без пути.

Полное имя файла состоит из всех символов в имени файла до (но не включая) последнего символа «.».

Пример:

QFileInfo fi("/tmp/archive.tar.gz");
QString base = fi.completeBaseName();  // base = "archive.tar"

См. также fileName(), suffix(), completeSuffix() и baseName().

QString QFileInfo::completeSuffix() const

Возвращает полное расширение файла.

Полное расширение состоит из всех символов в имени файла после (но не включая) первого символа «.».

Пример:

QFileInfo fi("/tmp/archive.tar.gz");
QString ext = fi.completeSuffix();  // ext = "tar.gz"

См. также fileName(), suffix(), baseName() и completeBaseName().

QDir QFileInfo::dir() const

Возвращает путь родительской директории объекта как объект QDir.

Примечание: Возвращаемый QDir всегда соответствует родительской директории объекта, даже если QFileInfo представляет директорию.

В каждом из следующих случаев dir() возвращает QDir "~/examples/191697".

    QFileInfo fileInfo1("~/examples/191697/.");
    QFileInfo fileInfo2("~/examples/191697/..");
    QFileInfo fileInfo3("~/examples/191697/main.cpp");

В каждом из следующих случаев dir() возвращает QDir ".".

    QFileInfo fileInfo4(".");
    QFileInfo fileInfo5("..");
    QFileInfo fileInfo6("main.cpp");

См. также absolutePath(), filePath(), fileName(), isRelative() и absoluteDir().

bool QFileInfo::exists() const

Возвращает true , если файл существует; в противном случае возвращает false.

Примечание: Если файл является символической ссылкой, которая указывает на несуществующий файл, возвращается false.

[static] bool QFileInfo::exists(const QString &file)

Возвращает true , если файл file существует; в противном случае возвращает false.

Примечание: Если file является символической ссылкой, которая указывает на несуществующий файл, возвращается false.

Примечание: Использование этой функции быстрее, чем использование QFileInfo(file).exists() для доступа к файловой системе.

Эта функция была добавлена в Qt 5.2.

QString QFileInfo::fileName() const

Возвращает имя файла, исключая путь.

Пример:

QFileInfo fi("/tmp/archive.tar.gz");
QString name = fi.fileName();                // name = "archive.tar.gz"

Обратите внимание, что если у этого объекта QFileInfo указан путь, заканчивающийся слешем, имя файла считается пустым.

См. также isRelative(), filePath(), baseName() и suffix().

QString QFileInfo::filePath() const

Возвращает имя файла, включая путь (который может быть абсолютным или относительным).

См. также absoluteFilePath(), canonicalFilePath() и isRelative().

QDateTime QFileInfo::fileTime(QFile::FileTime time) const

Возвращает время файла, указанное параметром time. Если время определить невозможно, возвращается недействимая дата и время.

Эта функция была добавлена в Qt 5.10.

См. также QFile::FileTime и QDateTime::isValid().

QString QFileInfo::group() const

Возвращает группу файла. В Windows, на системах, где у файлов нет групп, или при возникновении ошибки, возвращается пустая строка.

Эта функция может быть затратной по времени под Unix (порядка миллисекунд).

См. также groupId(), owner() и ownerId().

uint QFileInfo::groupId() const

Возвращает идентификатор группы, к которой принадлежит файл.

В Windows и на системах, где у файлов нет групп, эта функция всегда возвращает (uint) -2.

См. также group(), owner() и ownerId().

bool QFileInfo::isAbsolute() const

Возвращает true , если путь к файлу является абсолютным, в противном случае возвращает false, если путь относительный.

См. также isRelative().

bool QFileInfo::isBundle() const

Возвращает true , если этот объект указывает на пакет или символическую ссылку на пакет на macOS и iOS; в противном случае возвращает false.

Эта функция была добавлена в Qt 4.3.

См. также isDir(), isSymLink() и isFile().

bool QFileInfo::isDir() const

Возвращает true , если этот объект указывает на директорию или символическую ссылку на директорию; в противном случае возвращает false.

См. также isFile(), isSymLink() и isBundle().

bool QFileInfo::isExecutable() const

Возвращает true , если файл исполняемый; в противном случае возвращает false.

См. также isReadable(), isWritable() и permission().

bool QFileInfo::isFile() const

Возвращает true , если этот объект указывает на файл или символическую ссылку на файл. Возвращает false , если объект указывает на элемент, не являющийся файлом, например, директорию.

См. также isDir(), isSymLink() и isBundle().

bool QFileInfo::isHidden() const

Возвращает true , если это скрытый файл; в противном случае возвращает false.

Примечание: Эта функция возвращает true для специальных записей «.» и «..» под Unix, даже если QDir::entryList рассматривает их иначе.

bool QFileInfo::isNativePath() const

Возвращает true , если путь к файлу может быть использован непосредственно с системными API. Возвращает false , если файл иначе поддерживается виртуальной файловой системой внутри Qt, например, системой ресурсов Qt.

Примечание: Системные пути могут по-прежнему потребовать преобразования разделителей путей и кодировки символов в зависимости от платформы и требований системного API.

Эта функция была добавлена в Qt 5.0.

См. также QDir::toNativeSeparators(), QFile::encodeName(), filePath(), absoluteFilePath() и canonicalFilePath().

bool QFileInfo::isReadable() const

Возвращает true , если пользователь может читать файл; в противном случае возвращает false.

Примечание: Если проверка прав NTFS не включена, результат в Windows будет просто отражать существование файла.

См. также isWritable(), isExecutable() и permission().

bool QFileInfo::isRelative() const

Возвращает true , если путь к файлу является относительным, в противном случае возвращает false, если путь абсолютный (например, под Unix путь является абсолютным, если он начинается с «/»).

См. также isAbsolute().

bool QFileInfo::isRoot() const

Возвращает true , если объект указывает на каталог или символическую ссылку на каталог, и этот каталог является корневым каталогом; в противном случае возвращает false.

bool QFileInfo::isSymLink() const

Возвращает true , если этот объект указывает на символическую ссылку; в противном случае возвращает false.

Символические ссылки существуют в Unix (включая macOS и iOS) и Windows и обычно создаются с помощью команд ln -s или mklink соответственно. Открытие символической ссылки фактически открывает цель ссылки.

Кроме того, true будет возвращено для ярлыков (файлы *.lnk ) в Windows. Открытие их откроет сам файл .lnk.

Пример:

QFileInfo info(fileName);
if (info.isSymLink())
    fileName = info.symLinkTarget();

Примечание: Если символическая ссылка указывает на несуществующий файл, exists() возвращает false.

См. также isFile(), isDir() и symLinkTarget().

bool QFileInfo::isWritable() const

Возвращает true , если пользователь может записывать в файл; в противном случае возвращает false.

Примечание: Если проверка прав NTFS не включена, результат в Windows просто отразит, помечен ли файл как только для чтения.

См. также isReadable(), isExecutable() и permission().

QDateTime QFileInfo::lastModified() const

Возвращает дату и локальное время последнего изменения файла.

См. также birthTime(), lastRead(), metadataChangeTime() и fileTime().

QDateTime QFileInfo::lastRead() const

Возвращает дату и локальное время последнего чтения (доступа) к файлу.

На платформах, где эта информация недоступна, возвращает то же, что и lastModified().

См. также birthTime(), lastModified(), metadataChangeTime() и fileTime().

bool QFileInfo::makeAbsolute()

Преобразует путь к файлу в абсолютный путь, если он не находится в этом формате. Возвращает true , чтобы указать, что путь был преобразован; в противном случае возвращает false , чтобы указать, что путь уже был абсолютным.

См. также filePath() и isRelative().

QDateTime QFileInfo::metadataChangeTime() const

Возвращает дату и время изменения метаданных файла. Изменение метаданных происходит при создании файла, а также всякий раз, когда пользователь записывает или устанавливает информацию об инходе (например, изменяет права доступа к файлу).

Эта функция была добавлена в Qt 5.10.

См. также lastModified() и lastRead().

QString QFileInfo::owner() const

Возвращает владельца файла. На системах, где файлы не имеют владельцев, или если произошла ошибка, возвращается пустая строка.

Эта функция может быть длительной при использовании в Unix (в порядке миллисекунд). В Windows она вернёт пустую строку, если не включена проверка прав NTFS.

См. также ownerId(), group() и groupId().

uint QFileInfo::ownerId() const

Возвращает идентификатор владельца файла.

В Windows и на системах, где файлы не имеют владельцев, эта функция возвращает ((uint) -2).

См. также owner(), group() и groupId().

QString QFileInfo::path() const

Возвращает путь к файлу. Он не включает имя файла.

Обратите внимание, что, если этому объекту QFileInfo предоставлен путь, заканчивающийся косой чертой, имя файла считается пустым, и эта функция вернёт весь путь.

См. также filePath(), absolutePath(), canonicalPath(), dir(), fileName() и isRelative().

bool QFileInfo::permission(QFile::Permissions permissions) const

Проверяет разрешения на доступ к файлу. Аргумент permissions может быть несколькими флагами типа QFile::Permissions, объединёнными оператором OR, для проверки комбинаций разрешений.

На системах, где файлы не имеют разрешений, эта функция всегда возвращает true.

Примечание: Результат может быть неточным в Windows, если проверка прав NTFS не включена.

Пример:

QFileInfo fi("/tmp/archive.tar.gz");
if (fi.permission(QFile::WriteUser | QFile::ReadGroup))
    qWarning("I can change the file; my group can read the file");
if (fi.permission(QFile::WriteGroup | QFile::WriteOther))
    qWarning("The group or others can change the file");

См. также isReadable(), isWritable() и isExecutable().

QFile::Permissions QFileInfo::permissions() const

Возвращает полную объединённую комбинацию QFile::Permissions для файла.

Примечание: Результат может быть неточным в Windows, если проверка прав NTFS не включена.

void QFileInfo::refresh()

Обновляет информацию о файле, то есть считывает информацию из файловой системы при следующем обращении к кэшированному свойству.

void QFileInfo::setCaching(bool enable)

Если enable равно true, включить кеширование информации о файле. Если enable равно false, кеширование отключено.

Когда кеширование включено, QFileInfo считывает информацию о файле из файловой системы в первый раз, когда она необходима, но обычно не позже.

Кеширование включено по умолчанию.

См. также refresh() и caching().

void QFileInfo::setFile(const QString &file)

Устанавливает файл, о котором QFileInfo предоставляет информацию, на file.

file может также содержать абсолютный или относительный путь к файлу. Абсолютные пути начинаются с разделителя каталогов (например, "/" в Unix) или указания диска (в Windows). Относительные имена файлов начинаются с имени каталога или имени файла и указывают путь относительно текущего каталога.

Пример:

QString absolute = "/local/bin";
QString relative = "local/bin";
QFileInfo absFile(absolute);
QFileInfo relFile(relative);

QDir::setCurrent(QDir::rootPath());
// absFile and relFile now point to the same file

QDir::setCurrent("/tmp");
// absFile now points to "/local/bin",
// while relFile points to "/tmp/local/bin"

См. также isFile(), isRelative(), QDir::setCurrent() и QDir::isRelativePath().

void QFileInfo::setFile(const QFile &file)

Это перегруженная функция.

Устанавливает файл, о котором QFileInfo предоставляет информацию, на file.

Если file включает относительный путь, у QFileInfo также будет относительный путь.

См. также isRelative().

void QFileInfo::setFile(const QDir &dir, const QString &file)

Это перегруженная функция.

Устанавливает файл, о котором QFileInfo предоставляет информацию, на file в каталоге dir.

Если file включает относительный путь, у QFileInfo также будет относительный путь.

См. также isRelative().

qint64 QFileInfo::size() const

Возвращает размер файла в байтах. Если файл не существует или не может быть получен, возвращается 0.

См. также exists().

QString QFileInfo::suffix() const

Возвращает суффикс (расширение) файла.

Суффикс состоит из всех символов в имени файла после (но не включая) последней точки.

Пример:

QFileInfo fi("/tmp/archive.tar.gz");
QString ext = fi.suffix();  // ext = "gz"

Суффикс файла вычисляется одинаково на всех платформах, независимо от соглашений об именовании файлов (например, ".bashrc" в Unix имеет пустое имя базы, и суффикс — "bashrc").

См. также fileName(), completeSuffix(), baseName() и completeBaseName().

void QFileInfo::swap(QFileInfo &other)

Меняет местами информацию о файлах этого объекта с other. Эта функция очень быстрая и никогда не приводит к ошибке.

Эта функция была добавлена в Qt 5.0.

QString QFileInfo::symLinkTarget() const

Возвращает абсолютный путь к файлу или каталогу, на который указывает символическая ссылка, или пустую строку, если объект не является символической ссылкой.

Это имя может не соответствовать существующему файлу; это всего лишь строка. QFileInfo::exists() возвращает true если символическая ссылка указывает на существующий файл.

Эта функция была представлена в Qt 4.2.

См. также exists(), isSymLink(), isDir() и isFile().

bool QFileInfo::operator!=(const QFileInfo &fileinfo) const

Возвращает true если этот объект QFileInfo ссылается на другой файл, чем тот, который указан в fileinfo; в противном случае возвращает false.

См. также operator==().

QFileInfo &QFileInfo::operator=(const QFileInfo &fileinfo)

Создаёт копию заданного fileinfo и присваивает её этому объекту QFileInfo.

QFileInfo &QFileInfo::operator=(QFileInfo &&other)

Переносит other в этот объект QFileInfo.

Эта функция была представлена в Qt 5.2.

bool QFileInfo::operator==(const QFileInfo &fileinfo) const

Возвращает true если этот объект QFileInfo ссылается на файл в том же расположении, что и fileinfo; в противном случае возвращает false.

Обратите внимание, что результат сравнения двух пустых объектов QFileInfo, не содержащих ссылок на файлы (пути к файлам, которые не существуют или пустые), является неопределённым.

Предупреждение: Это не сравнит две разные символические ссылки, указывающие на один и тот же файл.

Предупреждение: Длинные и короткие имена файлов, которые ссылаются на один и тот же файл в Windows, обрабатываются как если бы они ссылались на разные файлы.

См. также operator!=().