QGIS API Documentation 3.30.0-'s-Hertogenbosch (f186b8efe0)
Static Public Member Functions | List of all members
QgsFileUtils Class Reference

Class for file utilities. More...

#include <qgsfileutils.h>

Static Public Member Functions

static QString addExtensionFromFilter (const QString &fileName, const QString &filter)
 Ensures that a fileName ends with an extension from the specified filter string. More...
 
static Qgis::DriveType driveType (const QString &path) SIP_THROW(QgsNotSupportedException)
 Returns the drive type for the given path. More...
 
static QString ensureFileNameHasExtension (const QString &fileName, const QStringList &extensions)
 Ensures that a fileName ends with an extension from the provided list of extensions. More...
 
static QStringList extensionsFromFilter (const QString &filter)
 Returns a list of the extensions contained within a file filter string. More...
 
static bool fileMatchesFilter (const QString &fileName, const QString &filter)
 Returns true if the given fileName matches a file filter string. More...
 
static QString findClosestExistingPath (const QString &path)
 Returns the top-most existing folder from path. More...
 
static QStringList findFile (const QString &file, const QString &basepath=QString(), int maxClimbs=4, int searchCeiling=4, const QString &currentDir=QString())
 Will check basepath in an outward spiral up to maxClimbs levels to check if file exists. More...
 
static bool isCloseToLimitOfOpenedFiles (int filesToBeOpened=1)
 Returns whether when opening new file(s) will reach, or nearly reach, the limit of simultaneously opened files by the process. More...
 
static int openedFileCount ()
 Returns the number of currently opened files by the process. More...
 
static int openedFileLimit ()
 Returns the limit of simultaneously opened files by the process. More...
 
static bool pathIsSlowDevice (const QString &path)
 Returns true if the specified path is assumed to reside on a slow device, e.g. More...
 
static bool renameDataset (const QString &oldPath, const QString &newPath, QString &error, Qgis::FileOperationFlags flags=Qgis::FileOperationFlag::IncludeMetadataFile|Qgis::FileOperationFlag::IncludeStyleFile)
 Renames the dataset at oldPath to newPath, renaming both the file at oldPath and all associated sidecar files which exist for it. More...
 
static QString representFileSize (qint64 bytes)
 Returns the human size from bytes. More...
 
static QSet< QString > sidecarFilesForPath (const QString &path)
 Returns a list of the sidecar files which exist for the dataset a the specified path. More...
 
static QStringList splitPathToComponents (const QString &path)
 Given a file path, returns a list of all the components leading to that path. More...
 
static QString stringToSafeFilename (const QString &string)
 Converts a string to a safe filename, replacing characters which are not safe for filenames with an '_' character. More...
 
static QString uniquePath (const QString &path)
 Creates a unique file path name from a desired path by appending "_<n>" (where "<n>" is an integer number) before the file suffix. More...
 
static QString wildcardsFromFilter (const QString &filter)
 Given a filter string like "GeoTIFF Files (*.tiff *.tif)", extracts the wildcard portion of this filter (i.e. More...
 

Detailed Description

Class for file utilities.

Since
QGIS 3.0

Definition at line 32 of file qgsfileutils.h.

Member Function Documentation

◆ addExtensionFromFilter()

QString QgsFileUtils::addExtensionFromFilter ( const QString &  fileName,
const QString &  filter 
)
static

Ensures that a fileName ends with an extension from the specified filter string.

E.g. a fileName of "d:/my_file" with a filter of "GeoTIFF Files (*.tiff *.tif)" will return "d:/my_file.tif", where as fileName of "d:/my_file.TIFF" or "d:/my_file.TIF" will be returned unchanged.

See also
extensionsFromFilter()
ensureFileNameHasExtension()

Definition at line 138 of file qgsfileutils.cpp.

◆ driveType()

Qgis::DriveType QgsFileUtils::driveType ( const QString &  path)
static

Returns the drive type for the given path.

Exceptions
QgsNotSupportedExceptionif determining the drive type is not supported on the current platform.
Since
QGIS 3.20

Definition at line 295 of file qgsfileutils.cpp.

◆ ensureFileNameHasExtension()

QString QgsFileUtils::ensureFileNameHasExtension ( const QString &  fileName,
const QStringList &  extensions 
)
static

Ensures that a fileName ends with an extension from the provided list of extensions.

E.g. if extensions contains "tif" and "tiff", then a fileName of "d:/my_file" will return "d:/my_file.tif". A fileName of "d:/my_file.TIFF" or "d:/my_file.TIF" will be returned unchanged.

See also
extensionsFromFilter()
addExtensionFromFilter()

Definition at line 111 of file qgsfileutils.cpp.

◆ extensionsFromFilter()

QStringList QgsFileUtils::extensionsFromFilter ( const QString &  filter)
static

Returns a list of the extensions contained within a file filter string.

E.g. a filter of "GeoTIFF Files (*.tiff *.tif)" would return a list containing "tiff", "tif". The initial '.' is stripped off the extension.

See also
ensureFileNameHasExtension()
addExtensionFromFilter()

Definition at line 58 of file qgsfileutils.cpp.

◆ fileMatchesFilter()

bool QgsFileUtils::fileMatchesFilter ( const QString &  fileName,
const QString &  filter 
)
static

Returns true if the given fileName matches a file filter string.

E.g a filter of "GeoTIFF Files (*.tiff *.tif)" would return true for a fileName of "/home/test.tif", or false for "/home/test.jpg".

Since
QGIS 3.18

Definition at line 87 of file qgsfileutils.cpp.

◆ findClosestExistingPath()

QString QgsFileUtils::findClosestExistingPath ( const QString &  path)
static

Returns the top-most existing folder from path.

E.g. if path is "/home/user/projects/2018/P4343" and "/home/user/projects" exists but no "2018" subfolder exists, then the function will return "/home/user/projects".

Since
QGIS 3.2

Definition at line 152 of file qgsfileutils.cpp.

◆ findFile()

QStringList QgsFileUtils::findFile ( const QString &  file,
const QString &  basepath = QString(),
int  maxClimbs = 4,
int  searchCeiling = 4,
const QString &  currentDir = QString() 
)
static

Will check basepath in an outward spiral up to maxClimbs levels to check if file exists.

Parameters
fileName or full path of the file to find
basepathcurrent basepath of the file, needed if only the name is specified in file
maxClimbslimit the number of time the search can move up from the basepath
searchCeilinglimits where in the folder hierarchy the search can be performed, 1 = root/drive, 2 = first folder level, 3 = sub folders ( Unix: /usr/bin, Win: C:/Users/Admin ), etc.
currentDiralternative default directory to override the actual current directory during the search
Returns
List of strings of the first matching path in unix format.
Since
QGIS 3.12

Definition at line 185 of file qgsfileutils.cpp.

◆ isCloseToLimitOfOpenedFiles()

bool QgsFileUtils::isCloseToLimitOfOpenedFiles ( int  filesToBeOpened = 1)
static

Returns whether when opening new file(s) will reach, or nearly reach, the limit of simultaneously opened files by the process.

Currently only implemented on Linux.

Parameters
filesToBeOpenedNumber of files that will be opened.
Returns
true if close to the limit, or false if not, or unknown.
Note
not available in Python bindings
Since
QGIS 3.22

Definition at line 496 of file qgsfileutils.cpp.

◆ openedFileCount()

int QgsFileUtils::openedFileCount ( )
static

Returns the number of currently opened files by the process.

Currently only implemented on Linux.

Returns
Number of files, or -1 if unknown
Note
not available in Python bindings
Since
QGIS 3.22

Definition at line 484 of file qgsfileutils.cpp.

◆ openedFileLimit()

int QgsFileUtils::openedFileLimit ( )
static

Returns the limit of simultaneously opened files by the process.

Currently only implemented on Unix.

Returns
Limit, or -1 if unknown.
Note
not available in Python bindings
Since
QGIS 3.22

Definition at line 472 of file qgsfileutils.cpp.

◆ pathIsSlowDevice()

bool QgsFileUtils::pathIsSlowDevice ( const QString &  path)
static

Returns true if the specified path is assumed to reside on a slow device, e.g.

a remote network drive or other non-fixed device.

Since
QGIS 3.20

Definition at line 349 of file qgsfileutils.cpp.

◆ renameDataset()

bool QgsFileUtils::renameDataset ( const QString &  oldPath,
const QString &  newPath,
QString &  error,
Qgis::FileOperationFlags  flags = Qgis::FileOperationFlag::IncludeMetadataFile | Qgis::FileOperationFlag::IncludeStyleFile 
)
static

Renames the dataset at oldPath to newPath, renaming both the file at oldPath and all associated sidecar files which exist for it.

For instance, if oldPath specified a .shp file then the corresponding .dbf, .idx and .prj files would be renamed (amongst others).

The destination directory must already exist.

The optional flags argument can be used to control whether QMD metadata files and QML styling files should also be renamed accordingly. By default these will be renamed, but manually specifying a different set of flags allows callers to avoid this when desired.

Parameters
oldPathoriginal path to dataset
newPathnew path for dataset
errorwill be set to a descriptive error message if the rename operation fails
flagsoptional flags to control file operation behavior
Returns
true if the dataset was successfully renamed, or false if an error occurred
Since
QGIS 3.22

Definition at line 400 of file qgsfileutils.cpp.

◆ representFileSize()

QString QgsFileUtils::representFileSize ( qint64  bytes)
static

Returns the human size from bytes.

Definition at line 41 of file qgsfileutils.cpp.

◆ sidecarFilesForPath()

QSet< QString > QgsFileUtils::sidecarFilesForPath ( const QString &  path)
static

Returns a list of the sidecar files which exist for the dataset a the specified path.

In this context a sidecar file is defined as a file which shares the same base filename as a dataset, but which differs in file extension. It defines the list of additional files which must be renamed or deleted alongside the main file associated with the dataset in order to completely rename/delete the dataset.

For instance, if path specified a .shp file then the corresponding .dbf, .idx and .prj files would be returned (amongst others).

Note
QGIS metadata files (.qmd) and map layer styling files (.qml) are NOT included in the returned list.
Since
QGIS 3.22

Definition at line 380 of file qgsfileutils.cpp.

◆ splitPathToComponents()

QStringList QgsFileUtils::splitPathToComponents ( const QString &  path)
static

Given a file path, returns a list of all the components leading to that path.

E.g. if path is "/home/user/Pictures/test.png", the returned list will contain "/" , "home", "user", "Pictures", "test.png".

Since
QGIS 3.28

Definition at line 505 of file qgsfileutils.cpp.

◆ stringToSafeFilename()

QString QgsFileUtils::stringToSafeFilename ( const QString &  string)
static

Converts a string to a safe filename, replacing characters which are not safe for filenames with an '_' character.

Warning
This method strips slashes from the filename, so it is safe to call with file names only, not complete paths.

Definition at line 144 of file qgsfileutils.cpp.

◆ uniquePath()

QString QgsFileUtils::uniquePath ( const QString &  path)
static

Creates a unique file path name from a desired path by appending "_<n>" (where "<n>" is an integer number) before the file suffix.

E.g. if "/path/my_image.png" already exists "/path/my_image_2.png" (and "_3", "_4" etc.) will be checked until a file path that does not already exist is found.

Parameters
paththe desired path.
Returns
the unmodified path if path is already unique or the new path with "_<n>" (where "<n>" is an integer number) appended to the file name before the suffix.
Note
This function does not make any check on path validity and write permissions.
Since
QGIS 3.30

Definition at line 533 of file qgsfileutils.cpp.

◆ wildcardsFromFilter()

QString QgsFileUtils::wildcardsFromFilter ( const QString &  filter)
static

Given a filter string like "GeoTIFF Files (*.tiff *.tif)", extracts the wildcard portion of this filter (i.e.

"*.tiff *.tif").

Since
QGIS 3.18

Definition at line 77 of file qgsfileutils.cpp.


The documentation for this class was generated from the following files: