This class represents absolute, well-formatted paths to files or directories.
More...
|
| | FilePath () noexcept |
| | The default constructor (this will create an invalid object!)
|
| |
| | FilePath (const QString &filepath) noexcept |
| | Constructor to create a librepcb::FilePath object from a QString.
|
| |
| | FilePath (const FilePath &other) noexcept |
| | The copy constructor.
|
| |
| bool | setPath (const QString &filepath) noexcept |
| | Set a new filepath.
|
| |
| bool | isValid () const noexcept |
| | Check whether this object contains a valid filepath or not.
|
| |
| bool | isExistingFile () const noexcept |
| | Check if the specified filepath is an existing file.
|
| |
| bool | isExistingDir () const noexcept |
| | Check if the specified filepath is an existing directory.
|
| |
| bool | isEmptyDir () const noexcept |
| | Check if the specified filepath is an existing, empty directory.
|
| |
| bool | isRoot () const noexcept |
| | Check if the specified filepath is the root directory.
|
| |
| bool | isLocatedInDir (const FilePath &dir) const noexcept |
| | Check if the filepath is located inside another directory.
|
| |
| QString | toStr () const noexcept |
| | Get the absolute and well-formatted filepath as a QString.
|
| |
| QString | toNative () const noexcept |
| | Get the absolute filepath with native directory separators.
|
| |
| FilePath | toUnique () const noexcept |
| | Get a unique version of the filepath (resolve symbolic links if possible)
|
| |
| QString | toRelative (const FilePath &base) const noexcept |
| | Convert an absolute filepath to a relative filepath (relative to another filepath)
|
| |
| QString | toRelativeNative (const FilePath &base) const noexcept |
| | Same as toRelative(), but with native directory separators.
|
| |
| QUrl | toQUrl () const noexcept |
| | Create and return a QUrl object with this filepath.
|
| |
| QString | getBasename () const noexcept |
| | Get the basename of the file or directory.
|
| |
| QString | getCompleteBasename () const noexcept |
| | Get the complete basename of the file or directory.
|
| |
| QString | getSuffix () const noexcept |
| | Get the suffix of the file or directory.
|
| |
| QString | getCompleteSuffix () const noexcept |
| | Get the complete suffix of the file or directory.
|
| |
| QString | getFilename () const noexcept |
| | Get the whole filename (without the path) of the file or directory.
|
| |
| FilePath | getParentDir () const noexcept |
| | Get the filepath of the parent directory of the file or directory.
|
| |
| FilePath | getPathTo (const QString &filename) const noexcept |
| | Get the filepath to a file or directory which is relative to this filepath.
|
| |
| FilePath & | operator= (const FilePath &rhs) noexcept |
| | The assign operator to copy a FilePath into another FilePath object.
|
| |
| bool | operator== (const FilePath &rhs) const noexcept |
| | The "==" operator to compare two FilePath objects.
|
| |
| bool | operator!= (const FilePath &rhs) const noexcept |
| | The "!=" operator to compare two FilePath objects.
|
| |
| bool | operator< (const FilePath &rhs) const noexcept |
| | The "<" operator to compare two FilePath objects.
|
| |
This class represents absolute, well-formatted paths to files or directories.
Why we need well-formatted paths and what do they look like
Using QString for paths to directories or files works not bad, but there are some disadventages. As the receiver of a filepath in form of a QString, you...
- never know whether it uses native separators or not ("/" or "\", depends
on the OS)
- never know whether it is an absolute or a relative filepath
- never know whether it contains redundant separators ("//" or "\")
- never know whether it contains "." or ".." entries
- never know whether a filepath to a directory ends with a separator or not
This means, you have to make a lot of checks at runtime to verify the
filepath. But that's annoying and can lead into problems if you do not make
these checks always solid.
The class ::librepcb::FilePath provides a way to avoid such problems and
tries to reduce the count of runtime checks you have to perform yourself
(the checks will be performed anyway, but the class #FilePath will do this
for you).
For compatibility reasons between different operating systems, we should
follow these rules for all paths in the whole project (if not explicitly
needed other formats):
- Always use absolute paths, never relative paths (relative paths can be
dangerous!)
- Always use "/" as directory separator (UNIX style), never "" (Windows style)
- A filepath to a directory must never end with a slash (except the UNIX root "/")
- Never use redundant separators ("//") in paths
- Never use "." and ".." in paths
- Note
- For convenience, a filepath which satisfies ALL these rules is called a "well formatted filepath" in this documentation.
To reach this goal, you need to convert each filepath which comes from outside the application (user input, read from file, ...) immediately into such a well-formatted filepath (make absolute, convert separators, remove redundant entries and so on). Then the filepath can be processed by the application. If a filepath must be printed to outside the application (print to a message box, write to a file, ...), the filepath can be converted (back) to the needed format (maybe "\" instead of "/", maybe relative instead of
absolute, ...).
<b>How the class ::librepcb::FilePath works and how to use it</b>
The class ::librepcb::FilePath represents a well-formatted filepath to a file
or directory and provides methods to convert paths between different formats.
Every ::librepcb::FilePath object represents either a well-formatted filepath
or an invalid object (see #isValid()). It's not possible to create
::librepcb::FilePath objects with non-well-formatted filepaths.
<b>Example:</b>
@code
FilePath fp("C:\foo\bar.txt"); // a file
qDebug(fp.toStr()); // "C:/foo/bar.txt"
qDebug(fp.toNative()); // "C:/foo/bar.txt"; Windows: "C:\foo\bar.txt"
fp.setPath("/foo/bar/"); // a directory
qDebug(fp.toStr()); // "/foo/bar" (trailing slash removed!)
qDebug(fp.toNative()); // "/foo/bar" ("\foo\bar" on Windows)
@endcode
@note A filepath represented by a FilePath object do not need to exist on
the file system. Most methods of this class do not depend on whether a
filepath exists or not. Exceptions: #toUnique(), #isExistingFile(),
#isExistingDir().
@warning Please consider that the conversion from filepaths with backslashes
as directory separator (Windows style) to filepaths with slashes as directory
separator (UNIX style, well-formatted paths) will work only on
windows! The reason is that backslashes are allowed in UNIX filepaths (and
are NOT interpreted as directory separator), so it's not allowed to replace
all backslashes in a UNIX filepath with slashes!
@warning Be careful with special characters in filepaths! Especially
(relative) filepaths in the library or in projects must always work on all
operating systems (the whole workspace must be platform independent!). This
means that only characters are allowed which can be used in filepaths on all
operating systems (for example the backslash "" is allowed in UNIX filenames, but not in Windows filenames). Other filepaths, like filepaths to recently used projects (which are stored in the user's profile), do not need to be platform independent.
Collaboration diagram for FilePath:
1.9.8