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)
	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.

Definition at line 31 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 134 of file qgsfileutils.cpp.

◆ driveType()

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

static

Returns the drive type for the given path.

Exceptions

QgsNotSupportedException if determining the drive type is not supported on the current platform.

Since: QGIS 3.20

Definition at line 367 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 107 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 148 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

file	Name or full path of the file to find
basepath	current basepath of the file, needed if only the name is specified in file
maxClimbs	limit the number of time the search can move up from the basepath
searchCeiling	limits 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.
currentDir	alternative 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 181 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

filesToBeOpened Number 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 573 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 561 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 549 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 425 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

oldPath	original path to dataset
newPath	new path for dataset
error	will be set to a descriptive error message if the rename operation fails
flags	optional 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 477 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 457 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 582 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 140 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

path	the 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 610 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:

/build/qgis-3.37.0+git20240325+fdefdf9c27f+17bookworm/src/core/qgsfileutils.h
/build/qgis-3.37.0+git20240325+fdefdf9c27f+17bookworm/src/core/qgsfileutils.cpp

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ addExtensionFromFilter()

◆ driveType()

◆ ensureFileNameHasExtension()

◆ extensionsFromFilter()

◆ fileMatchesFilter()

◆ findClosestExistingPath()

◆ findFile()

◆ isCloseToLimitOfOpenedFiles()

◆ openedFileCount()

◆ openedFileLimit()

◆ pathIsSlowDevice()

◆ renameDataset()

◆ representFileSize()

◆ sidecarFilesForPath()

◆ splitPathToComponents()

◆ stringToSafeFilename()

◆ uniquePath()

◆ wildcardsFromFilter()