API — ICoreEssentials/Filesystem

The public contract of 7 header(s) under src/ICoreEssentials/Filesystem — 7 class/struct definition(s), 79 declaration(s). Each section shows the header's banner and its public (and protected-virtual) surface exactly as the file writes it.

ICoreDir.h#

src/ICoreEssentials/Filesystem/ICoreDir.h

The path primitives this class shares with ICorePath (they were ICorePath's private statics until H2.7) moved to the .cpp with the bodies that call them, along with <filesystem> and the rest of the std set. Only the two classes' declarations are left here, so only <memory> is needed.

ICoreDir#

ICoreDir.h:87 · class · pImpl · nested Filters, SortFlags · 23 declaration(s)

ICoreDir (+ ICoreDirIterator) -- listing a directory.

class ICoreDir {
public:
    enum FilterFlag {
        NoFilter       = 0x0000,
        Dirs           = 0x0001,
        Files          = 0x0002,
        NoDotAndDotDot = 0x0004,
    };

    class Filters {
    public:
        constexpr Filters() : m_v(0) {}
        constexpr Filters(FilterFlag f) : m_v(static_cast<int>(f)) {}
        constexpr Filters operator|(Filters o) const { return Filters(m_v | o.m_v); }
        constexpr bool testFlag(FilterFlag f) const {
            return (m_v & static_cast<int>(f)) == static_cast<int>(f);
        }
        constexpr bool isEmpty() const { return m_v == 0; }

    private:
        constexpr explicit Filters(int v) : m_v(v) {}
        int m_v;
    };

    enum SortFlag {
        NoSort   = 0x0000,
        Name     = 0x0001,
        Time     = 0x0002,
        Reversed = 0x0004,
    };

    class SortFlags {
    public:
        constexpr SortFlags() : m_v(0) {}
        constexpr SortFlags(SortFlag f) : m_v(static_cast<int>(f)) {}
        constexpr SortFlags operator|(SortFlags o) const { return SortFlags(m_v | o.m_v); }
        constexpr bool testFlag(SortFlag f) const {
            return (m_v & static_cast<int>(f)) == static_cast<int>(f);
        }

    private:
        constexpr explicit SortFlags(int v) : m_v(v) {}
        int m_v;
    };

    ICoreDir();
    explicit ICoreDir(const ICoreString& path);
    ~ICoreDir();

    // A directory handle is a string in a coat and WAS implicitly copyable; a
    // unique_ptr member deletes that, so the four are written out in the .cpp
    // rather than silently narrowing the contract (recipe trap 2). Every one of
    // the nine call sites constructs its own and none copies -- this keeps it
    // so that none has to stop.
    ICoreDir(const ICoreDir& other);
    ICoreDir& operator=(const ICoreDir& other);
    ICoreDir(ICoreDir&& other) noexcept;
    ICoreDir& operator=(ICoreDir&& other) noexcept;

    [[nodiscard]] ICoreString filePath(const ICoreString& fileName) const;
    [[nodiscard]] ICoreString absoluteFilePath(const ICoreString& fileName) const;
    [[nodiscard]] ICoreString absolutePath() const;

    [[nodiscard]] bool exists() const;

    // Creates every missing component, and succeeds when the directory is
    // already there -- both as QDir::mkpath does. A relative path is resolved
    // against this directory, which is why `ICoreDir().mkpath(absolute)` at two
    // call sites works: the default directory is ".", and joining leaves an
    // absolute argument alone.
    bool mkpath(const ICoreString& path) const;

    bool cd(const ICoreString& name);

    bool cdUp();

    // The NAMES of the matching entries. Was QStringList in and out; see the
    // header note on the narrowing. The defaults stay on these declarations and
    // are NOT repeated in the .cpp.
    [[nodiscard]] ICoreStringList entryList(const ICoreStringList& nameFilters,
                                            Filters filters = Filters(),
                                            SortFlags sort = SortFlags()) const;

    [[nodiscard]] ICoreList<ICorePath> entryInfoList(const ICoreStringList& nameFilters,
                                                     Filters filters = Filters(),
                                                     SortFlags sort = SortFlags()) const;
    [[nodiscard]] ICoreList<ICorePath> entryInfoList(Filters filters,
                                                     SortFlags sort = SortFlags()) const;

    static ICoreString currentPath();

    static ICoreString homePath();

    static ICoreString tempPath();

    static ICoreString rootPath();

    static ICoreString toNativeSeparators(const ICoreString& path);

    static bool isAbsolutePath(const ICoreString& path);

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICoreDirIterator#

ICoreDir.h:204 · class · pImpl · 5 declaration(s)

Depth-first, name-ordered within each directory -- see the emission-order warning in the header note.

class ICoreDirIterator {
public:
    enum IteratorFlag { NoIteratorFlags = 0, Subdirectories = 1 };

    // The default stays on the declaration and is NOT repeated in the .cpp.
    ICoreDirIterator(const ICoreString& path,
                     const ICoreStringList& nameFilters,
                     ICoreDir::Filters filters,
                     IteratorFlag flags = NoIteratorFlags);

    ~ICoreDirIterator();

    [[nodiscard]] bool hasNext() const;

    // Advances and returns the path it moved onto, as QDirIterator::next does.
    ICoreString next();

    [[nodiscard]] ICoreString fileName() const;
    [[nodiscard]] ICoreString filePath() const;

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICoreEmbeddedResources.h#

src/ICoreEssentials/Filesystem/ICoreEmbeddedResources.h

ICoreEmbeddedResources#

ICoreEmbeddedResources.h:26 · class · 0 declaration(s)

ICoreEmbeddedResources -- files compiled INTO the binary, and the one thing worth doing with them from outside the toolkit: putting them on real disk.

class ICoreEmbeddedResources {
public:
    // Copies every file under `resourceRoot` (a ":/..." path, with or without
    // a trailing slash) into `targetRoot`, recreating the subfolder structure
    // and leaving each copy WRITABLE -- files copied out of the binary
    // otherwise keep the resource's read-only permissions, which is what makes
    // the next launch unable to replace them.
    //
    // Creates targetRoot and any parents it needs. Does NOT wipe it first:
    // whether a stale mirror should be cleared is the caller's policy, and
    // std::filesystem::remove_all is the caller's to call.
    //
    // Returns the resource paths it could NOT copy, in the order it met them,
    // so the caller reports them in its own voice. Best-effort by design: one
    // unreadable file does not abandon the rest of the tree. An empty return
    // means everything copied -- OR that the root held no files at all, which
    // for a mistyped root is the same answer, so pass a root you are sure of.
    [[nodiscard]] static std::vector<std::string> copyTreeToDisk(
        const std::string& resourceRoot,
        const std::filesystem::path& targetRoot);
};
};

ICoreFile.h#

src/ICoreEssentials/Filesystem/ICoreFile.h

ICoreFile -- a file on disk, opened, read or written, closed.

QT-FREE (phase 3). std::fstream for the contents, std::filesystem for the operations on the name; <QFile>, <QFileDevice> and this file's <QIODevice> are all gone. It could only happen once ICoreIODevice's vtable stopped naming Qt -- read that header's note first.

OPEN-MODE SEMANTICS, matched to QFile rather than to std::fstream, because the two genuinely differ:

• WriteOnly IMPLIES TRUNCATE, which is Qt's documented behaviour and also

what std::ios::out alone does, so the two agree by luck rather than by design. ICoreChart's CSV export relies on it -- it opens WriteOnly|Text with no Truncate and expects a fresh file.

ICoreFile#

ICoreFile.h:47 · class · final · bases public ICoreIODevice · pImpl · 21 declaration(s)

class ICoreFile final : public ICoreIODevice {
public:
    explicit ICoreFile(const ICoreString& path);

    ~ICoreFile() override;

    // Owns an open file handle; copying one is meaningless.
    ICoreFile(const ICoreFile&) = delete;
    ICoreFile& operator=(const ICoreFile&) = delete;

    bool open(OpenMode mode) override;

    void close() override;

    [[nodiscard]] bool isOpen() const override;

    std::int64_t write(const ICoreByteArray& data) override;

    std::int64_t write(const char* data, std::int64_t length) override;

    ICoreByteArray readAll() override;

    bool flush() override;

    [[nodiscard]] ICoreString errorString() const override;

    [[nodiscard]] bool exists() const;

    bool remove();

    [[nodiscard]] std::int64_t size() const;

    bool setOwnerReadWrite();

    [[nodiscard]] static bool exists(const ICoreString& path);

    static bool remove(const ICoreString& path);

    // Overwrites the destination, as QFile::copy does NOT -- see the note.
    //
    // ⚠ QFile::copy FAILS when the destination exists; std::filesystem's
    // copy_file skips it by default. Neither is what the one caller wants: the
    // template copier writes into a folder it has just created, and a stale
    // file there should lose. overwrite_existing makes the two agree on every
    // case that caller can reach, and is the safer answer for the case it
    // cannot.
    static bool copy(const ICoreString& from, const ICoreString& to);

    static bool rename(const ICoreString& from, const ICoreString& to);

    static bool setOwnerAndUserReadWrite(const ICoreString& path);

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICorePath.h#

src/ICoreEssentials/Filesystem/ICorePath.h

ICorePath -- what a path says about itself, and what is on disk there.

QT-FREE (phase 3). std::filesystem plus one stat() for the mtime; <QFileInfo> is gone from this header, and with it the LAST claimant of <QDateTime> in the whole layer -- both are now out of the umbrella.

This one was cheap for the reason B26 made it cheap: every method already spoke ICore vocabulary, so there was no signature to change. The only Qt in the public surface was the private QFileInfo constructor ICoreDir used as a friend, and ICoreDir is Qt-free in this same change, so it hands over a path instead.

DECOMPOSITION IS PURE STRING WORK, on the file name only, and it is NOT what std::filesystem's stem()/extension() do. Verified against QFileInfo rather

ICorePath#

ICorePath.h:88 · class · pImpl · 18 declaration(s)

class ICorePath {
public:
    ICorePath();
    ~ICorePath();

    explicit ICorePath(const ICoreString& path);

    // A path is a value and is copied as one. Written out because a
    // unique_ptr<Impl> member deletes the implicit copy.
    ICorePath(const ICorePath& other);
    ICorePath& operator=(const ICorePath& other);

    [[nodiscard]] bool exists() const;

    [[nodiscard]] ICoreString fileName() const;

    // Up to the FIRST dot -- see the table in the header note.
    [[nodiscard]] ICoreString baseName() const;

    // Up to the LAST dot.
    [[nodiscard]] ICoreString completeBaseName() const;

    // After the LAST dot.
    [[nodiscard]] ICoreString suffix() const;

    [[nodiscard]] ICoreString absoluteFilePath() const;

    [[nodiscard]] ICoreString absolutePath() const;

    // The directory part AS WRITTEN -- see the header note.
    [[nodiscard]] ICoreString path() const;

    [[nodiscard]] bool isDir() const;

    [[nodiscard]] bool isFile() const;

    // Invalid when the file does not exist, matching QFileInfo -- and the
    // runner's cache reads that case, so it is load-bearing rather than tidy.
    [[nodiscard]] ICoreDateTime lastModified() const;

    // Milliseconds since the epoch, or 0 when there is nothing to stat. Exists
    // for ICoreDir's Time sort: ICoreDateTime deliberately exposes no epoch
    // accessor and offers no ordering (Rule 3), so there is nothing else to
    // sort by. Public since H2.7 -- see the note above.
    [[nodiscard]] std::int64_t mtimeMs() const;

    [[nodiscard]] static bool exists(const ICoreString& path);

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICorePathAlgebra.h#

src/ICoreEssentials/Filesystem/ICorePathAlgebra.h

ICorePathAlgebra -- the pure string operations underneath ICorePath and ICoreDir.

WHY THIS FILE EXISTS (H2.7, 2026-08-14). These seven functions were private statics of ICorePath, reached by friend class ICoreDir. The header surface rule moved ICorePath's implementation into ICorePath.cpp, which put them out of ICoreDir's reach -- and unlike the friendships on H2.14 and H2.17, this one could not be answered by widening one accessor or deleting one duplicate, because SEVEN primitives were shared and none of them is a query about a particular path object.

So they are what they always were underneath: free functions on strings, with no ICorePath in sight. That is the third answer DEVELOPER_GUIDELINES describes -- an internal module shared by two implementations -- and it is

Declares no class of its own — see the file.

ICoreStandardPaths.h#

src/ICoreEssentials/Filesystem/ICoreStandardPaths.h

Named in the two known-folder signatures below. Included here rather than leaned on from pch.h because ICorePreReleaseTests force-includes the ICoreEssentials.h umbrella WITHOUT the platform PCH's std block.

ICoreStandardPaths#

ICoreStandardPaths.h:94 · class · 4 declaration(s)

ICoreStandardPaths -- where an executable lives.

class ICoreStandardPaths {
public:
    ICoreStandardPaths() = delete;

    // The absolute, lexically normalised path of `name`, or an empty string.
    // See the header note for the semantics this matches and where it stops
    // short of resolving symlinks.
    [[nodiscard]] static ICoreString findExecutable(const ICoreString& name);

    // The per-OS application data folder for `appName`, NOT created. Empty if
    // the OS cannot say where it is.
    [[nodiscard]] static std::filesystem::path appDataLocation(const ICoreString& appName);

    // The user's Documents folder, NOT created. Empty if the OS cannot say
    // where it is.
    [[nodiscard]] static std::filesystem::path documentsLocation();
};
};

ICoreTempDir.h#

src/ICoreEssentials/Filesystem/ICoreTempDir.h

ICoreTempDir -- a private directory that deletes itself.

QT-FREE (phase 3, B29). std::filesystem only; <QTemporaryDir> is gone from this header and from the umbrella.

⚠ THIS IS THE ONE WRAPPER IN THE LAYER WHOSE DESTRUCTOR DELETES A DIRECTORY TREE, so the invariants below are safety properties, not style:

• remove_all() runs ONLY when m_valid is true, and m_valid is set in

exactly one place -- immediately after create_directory() returned TRUE, meaning this object created that directory itself. An ICoreTempDir can therefore never delete a directory it merely pointed at.

• THE TYPE IS NON-COPYABLE, DECLARED RATHER THAN INHERITED, and that is the

single most important line in this file. It used to hold a QTemporaryDir,

ICoreTempDir#

ICoreTempDir.h:58 · class · pImpl · 8 declaration(s)

class ICoreTempDir {
public:
    ICoreTempDir();

    // Removes the directory and everything in it, best effort, as
    // QTemporaryDir does. Defined in the .cpp: destroying a unique_ptr<Impl>
    // needs Impl complete.
    ~ICoreTempDir();

    // See the header note -- this is a safety property, not a style choice.
    ICoreTempDir(const ICoreTempDir&)            = delete;
    ICoreTempDir& operator=(const ICoreTempDir&) = delete;

    [[nodiscard]] bool isValid() const noexcept;

    [[nodiscard]] ICoreString errorString() const;

    [[nodiscard]] ICoreString path() const;

    // Qt returns an empty string for an invalid directory and does NOT check
    // that the file exists; both are matched here.
    [[nodiscard]] ICoreString filePath(const ICoreString& fileName) const;

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};