1 | /* |
2 | This file is part of the KDE libraries |
3 | |
4 | SPDX-FileCopyrightText: 2000-2005 David Faure <faure@kde.org> |
5 | SPDX-FileCopyrightText: 2021 Alexander Lohnau <alexander.lohnau@gmx.de> |
6 | |
7 | SPDX-License-Identifier: LGPL-2.0-or-later |
8 | */ |
9 | #ifndef KFILEUTILS_H |
10 | #define KFILEUTILS_H |
11 | |
12 | #include "kcoreaddons_export.h" |
13 | |
14 | #include <QString> |
15 | #include <QUrl> |
16 | |
17 | /*! |
18 | * \namespace KFileUtils |
19 | * \inmodule KCoreAddons |
20 | * \brief A namespace for KFileUtils globals. |
21 | */ |
22 | namespace KFileUtils |
23 | { |
24 | /*! |
25 | * Given a directory path and a string representing a file or directory |
26 | * (which usually exist already), this function returns a suggested name |
27 | * for a file/directory that doesn't exist in \a baseURL. |
28 | * |
29 | * The suggested file name is of the form "foo (1)", "foo (2)" etc. |
30 | * |
31 | * For local URLs, this function will check if there is already a file/directory |
32 | * with the new suggested name and will keep incrementing the number in the above |
33 | * format until it finds one that doesn't exist. Note that this function uses a |
34 | * blocking I/O call (using QFileInfo) to check the existence of the file/directory, |
35 | * this could be problematic for network mounts (e.g. SMB, NFS) as these are treated |
36 | * as local files by the upstream QFile code. An alternative is to use makeSuggestedName() |
37 | * and use KIO to stat the new file/directory in an asynchronous way. |
38 | * |
39 | * \since 5.61 |
40 | */ |
41 | KCOREADDONS_EXPORT QString suggestName(const QUrl &baseURL, const QString &oldName); |
42 | |
43 | /*! |
44 | * Given a string, "foo", representing a file/directory (which usually exists already), |
45 | * this function returns a suggested name for a file/directory in the form "foo (1)", |
46 | * "foo (2)" etc. |
47 | * |
48 | * Unlike the suggestName() method, this function doesn't check if there is a file/directory |
49 | * with the newly suggested name; the idea being that this responsibility falls on |
50 | * the caller, e.g. one can use KIO::stat() to check asynchronously whether the new |
51 | * name already exists (in its parent directory) or not. |
52 | * |
53 | * \since 5.76 |
54 | */ |
55 | KCOREADDONS_EXPORT QString makeSuggestedName(const QString &oldName); |
56 | |
57 | /*! |
58 | * Locates all files matching the \a nameFilters in the given \a dirs |
59 | * The returned list does not contain duplicate file names. |
60 | * In case there are multiple files the one which comes first in the dirs list is returned. |
61 | * For example: |
62 | * \code |
63 | * QStringList dirs = QStandardPaths::locateAll(QStandardPaths::GenericDataLocation, QStringLiteral("krunner/dbusplugins"), QStandardPaths::LocateDirectory); |
64 | * KFileUtils::findAllUniqueFiles(dirs, QStringList{QStringLiteral("*.desktop")}); |
65 | * \endcode |
66 | * |
67 | * \a location standard location for the dir |
68 | * |
69 | * \a dir directory in which the files are located |
70 | * |
71 | * \a nameFilters filters that get passed to the QDirIterator that is used internally to |
72 | * iterate over the files in each dir in the list |
73 | * |
74 | * Returns list of absolute file paths |
75 | * \since 5.85 |
76 | */ |
77 | KCOREADDONS_EXPORT QStringList findAllUniqueFiles(const QStringList &dirs, const QStringList &nameFilters = {}); |
78 | } |
79 | #endif |
80 | |