Contains utilities for working with files. More...

#include <qgsfileutils.h>

Public Types
enum class	CopyFlag : int { NoSymLinks = 1 << 0 }
	Creates a unique file path name from a desired path by appending _<n> (where <n> is an integer number) before the file suffix. More...
typedef QFlags< CopyFlag >	CopyFlags
	Flags controlling behavior of file copy operations.

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.
static bool	copyDirectory (const QString &source, const QString &destination, QgsFileUtils::CopyFlags flags=QgsFileUtils::CopyFlags())
	Recursively copies a whole directory.
static Qgis::DriveType	driveType (const QString &path)
	Returns the drive type for the given path.
static QString	ensureFileNameHasExtension (const QString &fileName, const QStringList &extensions)
	Ensures that a fileName ends with an extension from the provided list of extensions.
static QStringList	extensionsFromFilter (const QString &filter)
	Returns a list of the extensions contained within a file filter string.
static bool	fileMatchesFilter (const QString &fileName, const QString &filter)
	Returns `true` if the given fileName matches a file filter string.
static QString	findClosestExistingPath (const QString &path)
	Returns the top-most existing folder from path.
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.
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.
static int	openedFileCount ()
	Returns the number of currently opened files by the process.
static int	openedFileLimit ()
	Returns the limit of simultaneously opened files by the process.
static bool	pathIsSlowDevice (const QString &path)
	Returns `true` if the specified path is assumed to reside on a slow device, e.g.
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.
static bool	replaceTextInFile (const QString &path, const QString &searchString, const QString &replacement)
	Replaces all occurrences of a given string in a file.
static QString	representFileSize (qint64 bytes)
	Returns the human size from bytes.
static QSet< QString >	sidecarFilesForPath (const QString &path)
	Returns a list of the sidecar files which exist for the dataset a the specified path.
static QStringList	splitPathToComponents (const QString &path)
	Given a file path, returns a list of all the components leading to that path.
static QString	stringToSafeFilename (const QString &string)
	Converts a string to a safe filename, replacing characters which are not safe for filenames with an '_' character.
static QString	wildcardsFromFilter (const QString &filter)
	Given a filter string like GeoTIFF Files (.tiff .tif), extracts the wildcard portion of this filter (i.e.

Detailed Description

Contains utilities for working with files.

Definition at line 32 of file qgsfileutils.h.

Member Typedef Documentation

◆ CopyFlags

typedef QFlags< CopyFlag > QgsFileUtils::CopyFlags

Flags controlling behavior of file copy operations.

Since: QGIS 4.0.1

Definition at line 259 of file qgsfileutils.h.

Member Enumeration Documentation

◆ CopyFlag

enum class QgsFileUtils::CopyFlag : int

strong

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 */ static QString uniquePath( const QString &path );

/** Flags controlling behavior of file copy operations.

Since: QGIS 4.0.1

Enumerator
NoSymLinks	If present, indicates that symbolic links should be skipped during the copy.

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

◆ copyDirectory()

bool QgsFileUtils::copyDirectory	(	const QString &	source,
		const QString &	destination,
		QgsFileUtils::CopyFlags	flags = QgsFileUtils::CopyFlags() )

static

Recursively copies a whole directory.

Returns true if the copy was successful and all files and folders were copied.

Note: If an error occurs while copying a file, this method still attempts to copy all remaining files and folders.

Since QGIS 4.0.1 the flags argument can be used to specify flags controlling the behavior of the copy operation.

Since: QGIS 4.0

Definition at line 638 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 368 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 115 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 66 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 95 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 156 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 189 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 581 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 558 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 546 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 424 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 474 of file qgsfileutils.cpp.

◆ replaceTextInFile()

bool QgsFileUtils::replaceTextInFile	(	const QString &	path,
		const QString &	searchString,
		const QString &	replacement )

static

Replaces all occurrences of a given string in a file.

Returns true if the replacement was successful and the file updated.

Replacement is case-sensitive.

Since: QGIS 4.0

Definition at line 694 of file qgsfileutils.cpp.

◆ representFileSize()

QString QgsFileUtils::representFileSize ( qint64 bytes )

static

Returns the human size from bytes.

Definition at line 49 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 454 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 590 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 148 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 85 of file qgsfileutils.cpp.

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

/build/qgis-4.1.0+git20260308+60fea48833c+99sid/src/core/qgsfileutils.h
/build/qgis-4.1.0+git20260308+60fea48833c+99sid/src/core/qgsfileutils.cpp

Public Types

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ CopyFlags

Member Enumeration Documentation

◆ CopyFlag

Member Function Documentation

◆ addExtensionFromFilter()

◆ copyDirectory()

◆ driveType()

◆ ensureFileNameHasExtension()

◆ extensionsFromFilter()

◆ fileMatchesFilter()

◆ findClosestExistingPath()

◆ findFile()

◆ isCloseToLimitOfOpenedFiles()

◆ openedFileCount()

◆ openedFileLimit()

◆ pathIsSlowDevice()

◆ renameDataset()

◆ replaceTextInFile()

◆ representFileSize()

◆ sidecarFilesForPath()

◆ splitPathToComponents()

◆ stringToSafeFilename()

◆ wildcardsFromFilter()