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 */
22namespace 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 */
41KCOREADDONS_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 */
55KCOREADDONS_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 */
77KCOREADDONS_EXPORT QStringList findAllUniqueFiles(const QStringList &dirs, const QStringList &nameFilters = {});
78}
79#endif
80

source code of kcoreaddons/src/lib/io/kfileutils.h