Класс 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(). Части имени файла можно извлечь с помощью baseName(), suffix() или completeSuffix(). Объекты QFileInfo для директорий, созданных классами Qt, не будут иметь конечного разделителя файла. Если вы хотите использовать конечные разделители в собственных объектах информации о файлах, просто добавьте его к имени файла, переданному в конструкторы или 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!=().