API — ICoreEssentials/System

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

ICoreCapabilities.h#

ICoreEssentials/System/ICoreCapabilities.h

ICoreCapabilities#

ICoreCapabilities.h:33 · class · 4 declaration(s)

ICoreCapabilities -- can THIS platform do X, asked at run time.

class ICoreCapabilities {
public:
    enum class Capability {
        // ICoreProcess. A page cannot start a program. Nothing replaces it in
        // the browser; a server-backed tier is the only way back.
        ChildProcess,

        // ICorePty. No shell, no terminal. Same answer as ChildProcess.
        PseudoTerminal,

        // ICoreTcpServer. A page cannot listen on a port.
        TcpServer,

        // ICoreTcpSocket. A page can open a WebSocket, not a raw TCP stream.
        TcpClient,

        // ICoreLibrary. No dlopen of a native library; a wasm side module is a
        // different artefact and is not what this wrapper loads.
        DynamicLibrary,

        // ICoreCredentialStore. No OS keychain. Browser storage is readable by
        // any script on the origin, so it is not a vault and must not be
        // presented as one.
        CredentialVault,

        // ICoreMachineId. A page has no stable hardware identity, by design.
        MachineId,

        // Filesystem/. A page sees a private, per-origin store (OPFS/IndexedDB)
        // plus whatever the user hands it through a picker -- not the disk.
        NativeFileSystem,

        // std::thread. A browser build has it only when configured with
        // ICORE_WEB_THREADS=ON, and that build loads only on a page served
        // cross-origin isolated (COOP/COEP headers). Without them it does not
        // fall back to one thread; it fails to start at all (WB0.11, measured
        // in Chrome and Safari). So when code is running at all, the build
        // answer is the whole answer. The default web build is single-thread,
        // and there std::thread's constructor throws std::system_error.
        Threads,

        // ICoreDialog::exec() and every prompt helper that returns its answer.
        // A browser cannot block the main thread waiting for a click.
        BlockingModal,

        // A second top-level window. A page is one tab; extra windows become
        // frames inside it.
        MultipleWindows,

        // More than 4 GB of address space. wasm32 caps a page there.
        LargeAddressSpace
    };

    // ⚠ A TEST CAN TAKE A CAPABILITY AWAY, NEVER GIVE ONE: the environment
    // variable ICORE_DENY_CAPABILITIES, a comma-separated list of name()s
    // ("Threads,ChildProcess"), makes has() answer false for those, read once at
    // the first call. It exists so a desktop suite can run the paths a browser
    // takes -- the solver's single-thread slices were proved that way (WB8.3).
    [[nodiscard]] static bool has(Capability capability);

    // True in a build compiled for a web browser (Emscripten), whichever UI
    // backend it selects.
    [[nodiscard]] static bool isWebPlatform();

    // The enumerator's own spelling ("ChildProcess"), for logs and tests.
    [[nodiscard]] static std::string name(Capability capability);

    // What a user is told when a feature is unavailable for this reason --
    // one sentence, platform-specific. EMPTY when has() is true: there is
    // nothing to explain, and a caller that shows it unconditionally shows
    // nothing on a platform where the feature works.
    [[nodiscard]] static std::string unavailableReason(Capability capability);

};

ICoreCommandLine.h#

ICoreEssentials/System/ICoreCommandLine.h

ICoreCommandLineOption#

ICoreCommandLine.h:58 · class · pImpl · 6 declaration(s)

ICoreCommandLineOption / ICoreCommandLine -- switches off the command line.

class ICoreCommandLineOption {
public:
    // `valueName` empty means this is a FLAG -- it takes no value and isSet()
    // is the only thing worth asking about it. That is how Qt distinguishes the
    // two as well, and how --tools is declared at the one call site.
    //
    // The defaults stay on the DECLARATION and are not repeated in the .cpp --
    // repeating them is an error, and the diagnostic points at the .cpp.
    ICoreCommandLineOption(const ICoreString& name,
                           const ICoreString& description,
                           const ICoreString& valueName    = ICoreString(),
                           const ICoreString& defaultValue = ICoreString());

    ~ICoreCommandLineOption();

    // An option is a small value 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 (H2.11, recipe trap 2). Nothing in the
    // tree copies one today -- this keeps it so that nothing has to stop.
    ICoreCommandLineOption(const ICoreCommandLineOption& other);
    ICoreCommandLineOption& operator=(const ICoreCommandLineOption& other);
    ICoreCommandLineOption(ICoreCommandLineOption&& other) noexcept;
    ICoreCommandLineOption& operator=(ICoreCommandLineOption&& other) noexcept;

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

ICoreCommandLine#

ICoreCommandLine.h:94 · class · pImpl · 12 declaration(s)

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

    // Was implicitly copyable, and stays so -- see the option's note.
    ICoreCommandLine(const ICoreCommandLine& other);
    ICoreCommandLine& operator=(const ICoreCommandLine& other);
    ICoreCommandLine(ICoreCommandLine&& other) noexcept;
    ICoreCommandLine& operator=(ICoreCommandLine&& other) noexcept;

    void setApplicationDescription(const ICoreString& description);

    void addHelpOption();

    // Adding a nameless or duplicate option is a programming error at startup,
    // not a user error, so it is loud and fatal rather than a return value
    // nobody checks -- as B12's assert was.
    void addOption(const ICoreCommandLineOption& option);

    // Parses, and may end the program -- see the header note. argc/argv come
    // straight from main(); argv[0] is the program name and is skipped.
    void process(int argc, char** argv);

    [[nodiscard]] ICoreString value(const ICoreCommandLineOption& option) const;

    [[nodiscard]] bool isSet(const ICoreCommandLineOption& option) const;

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

ICoreConsoleHost.h#

ICoreEssentials/System/ICoreConsoleHost.h

ICoreConsoleHost#

ICoreConsoleHost.h:34 · class · 2 declaration(s)

Whether this process owns a console it can host a PSEUDO-console under.

class ICoreConsoleHost {
public:
    enum class Outcome {
        AlreadyPresent,   // launched with a real console; nothing was done
        Allocated,        // this process had none and one was created
        Inherited,        // attached to a parent's pseudo-console -- see the warning above
        Unavailable       // no console could be obtained
    };

    // Idempotent, and safe to call on any platform: everywhere but Windows a
    // process's stdio is already whatever it was given and this answers
    // AlreadyPresent without doing anything.
    //
    // When it allocates, it also reopens the standard streams onto the new
    // console -- but ONLY the ones that were not already redirected, so
    // `app --console ... > log.txt` keeps writing to the file.
    static Outcome ensureConsole();

    // What ensureConsole() found and did, in one line, for a diagnostic. Calls
    // ensureConsole() if it has not run.
    static std::string describe();
};
};

ICoreCredentialStore.h#

ICoreEssentials/System/ICoreCredentialStore.h

ICoreCredentialStore#

ICoreCredentialStore.h:40 · class · 6 declaration(s)

Stores a secret in the operating system's own credential vault, keyed by a (service, account) pair — the identifying tuple all three platform vaults agree on.

class ICoreCredentialStore {
public:
    // Empty string when no secret is stored (or the lookup failed — an absent
    // secret and an unreadable vault are not distinguished, because the
    // caller's response to both is the same: ask for it again).
    static ICoreString load(const ICoreString& service, const ICoreString& account);

    // Overwrites any existing secret for that pair. An empty `secret` clears
    // it, which is the same path as forget().
    static bool save(const ICoreString& service, const ICoreString& account,
                     const ICoreString& secret);

    static bool forget(const ICoreString& service, const ICoreString& account);

    static bool has(const ICoreString& service, const ICoreString& account);

    // False on platforms using the file fallback. Surface this in the UI.
    static bool isSecure();

    // Human-readable name of the backing store, for a settings panel
    // ("macOS Keychain", "Windows Credential Manager", "local file").
    static ICoreString backingStoreName();

    // Where the file fallback writes, on the platforms that use one. A host
    // application that already owns an application-home folder points this at
    // it once at startup; left unset, the fallback derives a directory from
    // ICoreStandardPaths::appDataLocation(service).
    //
    // No-op on macOS and Windows, where the OS vault is used and no file is
    // ever written — it is still safe (and expected) to call unconditionally.
    static void setFallbackDirectory(const std::filesystem::path& directory);

};

ICoreLibrary.h#

ICoreEssentials/System/ICoreLibrary.h

ICoreLibrary -- a dynamically loaded shared library and the symbols in it.

QT-FREE (phase 3). dlopen/dlsym/dlclose, and LoadLibrary/GetProcAddress on Windows; <QLibrary> is gone from this header and from the umbrella.

⚠ THIS IS THE FIRST .cpp IN ICoreEssentials, AND THAT WAS THE WHOLE BLOCKER.

This wrapper looked trivial for months and was not. dlopen is twenty lines, but Windows needs <windows.h>, and this layer was HEADER-ONLY with its umbrella force-included into ~2,600 translation units. Putting <windows.h> there would have dragged the Win32 API -- and its macros, min/max and friends -- into every file in the project. So the row was blocked on an architectural decision rather than on difficulty, and it stayed blocked.

ICoreLibrary#

ICoreLibrary.h:69 · class · pImpl · 10 declaration(s)

class ICoreLibrary {
public:
    using FunctionPointer = void (*)();

    ICoreLibrary();
    ~ICoreLibrary();

    ICoreLibrary(const ICoreLibrary&) = delete;
    ICoreLibrary& operator=(const ICoreLibrary&) = delete;

    // Names the image to load. Does not touch the filesystem -- load() does.
    // Setting a new name while loaded unloads the old image first, per QLibrary.
    void setFileName(const ICoreString& fileName);

    // Map the image. False if it is missing, unreadable, or built for another
    // architecture -- errorString() says which.
    bool load();

    // Drop this handle. The OS keeps the image mapped while another handle on
    // it is still open, which is dlclose's own reference counting.
    bool unload();

    [[nodiscard]] bool isLoaded() const;

    // Address of an exported symbol, or nullptr if the image does not export it.
    // Loads the image on demand if it is not already, as QLibrary::resolve does.
    [[nodiscard]] FunctionPointer resolve(const char* symbol);

    // Why the last load/unload/resolve failed. Only meaningful after one of
    // them has returned a failure.
    [[nodiscard]] ICoreString errorString() const;

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

ICoreMachineId.h#

ICoreEssentials/System/ICoreMachineId.h

ICoreMachineId#

ICoreMachineId.h:50 · class · 4 declaration(s)

ICoreMachineId -- a stable identifier for THIS machine.

class ICoreMachineId {
public:
    enum class Source {
        PlatformUuid,     // macOS IOPlatformUUID
        MachineGuid,      // Windows registry
        MachineIdFile,    // Linux /etc/machine-id or the dbus one
        VaultRandom,      // minted here, kept in the credential vault
        Unavailable       // no platform id AND no vault -- process-lifetime only
    };

    // Lowercase, hyphenated where the platform gives a UUID, never empty.
    static std::string value();

    // SHA-256 of (salt + ":" + value()), lowercase hex. This is what may be
    // sent. An empty salt is accepted and is a mistake -- it makes the hash a
    // cross-product identifier again.
    static std::string hashed(std::string_view salt);

    static Source source();

    // Human-readable, for a diagnostics line or an account panel.
    static std::string sourceName();

};

ICoreOs.h#

ICoreEssentials/System/ICoreOs.h

Which OS this build targets, without a client naming the toolkit's own platform macros. Exactly one of these is defined.

A macro rather than a constant because the call sites are #if branches around whole blocks -- code that only COMPILES on one platform (a registry path, a bundle layout) cannot be selected by a runtime test.

⚠ THIS HEADER HOLDS DIRECTIVES AND NOTHING ELSE, AND THAT IS ITS POINT. It contributes no token to a translation unit, so any file may include it without changing what the compiler sees on a platform whose arm it already took. That is how the tablet arms were threaded through shipped files with byte-identical preprocessed output on macOS (tablet backend plan §0.2). It sits under System/ rather than UI/ so the non-UI tree can ask the question without including a UI header. UI/System/ICorePlatform.h includes it, so a

Declares no class of its own — see the file.

ICoreOsVersion.h#

ICoreEssentials/System/ICoreOsVersion.h

ICoreOsVersion#

ICoreOsVersion.h:44 · class · 4 declaration(s)

ICoreOsVersion -- what operating system version this machine is running, and how to compare two of them.

class ICoreOsVersion {
public:
    // "14.5", "10.0.19045", "22.04" -- the vendor's own spelling, untouched.
    // Empty when it could not be read. Computed once per process: it cannot
    // change while the process runs, and the macOS call is a syscall.
    [[nodiscard]] static std::string current();

    // Component-wise numeric comparison, shorter side zero-extended, so
    // "14" == "14.0" == "14.0.0". Returns <0, 0 or >0 like strcmp.
    //
    // A component that is not a number compares as 0 rather than poisoning the
    // whole answer: "22.04-LTS" must still order against "22.04".
    [[nodiscard]] static int compare(std::string_view a, std::string_view b);

    // a >= b, for the one question a floor asks. Spelled out so no call site
    // has to remember which way round compare()'s sign runs -- an inverted
    // comparison here withholds every update from every machine.
    [[nodiscard]] static bool atLeast(std::string_view version, std::string_view floor);

    // Returns the failure count and appends a sentence per failure.
    static int selfTest(std::vector<std::string>* failures);

};

ICorePowerAssertion.h#

ICoreEssentials/System/ICorePowerAssertion.h

ICorePowerAssertion -- keep the machine awake through a long job.

ICorePowerAssertion awake; awake.acquire(ICorePowerAssertion::Kind::PreventSystemSleep, "Exporting 40 GB of HDL"); runTheJob(); // released by release() or by destruction

While an assertion is held the operating system does not put the machine to sleep for being IDLE. It never overrides the user: closing a laptop's lid or choosing Sleep still sleeps. The reason is shown by the system's own tools (pmset -g assertions on macOS, powercfg /requests on Windows, systemd-inhibit --list on Linux), so write it for the person reading them.

Each object holds at most one assertion; acquire() on an active one

ICorePowerAssertion#

ICorePowerAssertion.h:42 · class · pImpl · 11 declaration(s)

Opened by row PS5.25 of the Platform SDK product plan.

class ICorePowerAssertion {
public:
    enum class Kind : int {
        PreventSystemSleep  = 0,   // the display may still turn off
        PreventDisplaySleep = 1,   // the display stays on, and so does the system
    };

    ICorePowerAssertion();
    ~ICorePowerAssertion();

    ICorePowerAssertion(const ICorePowerAssertion&) = delete;
    ICorePowerAssertion& operator=(const ICorePowerAssertion&) = delete;

    // False, with errorString() set, when the platform refuses or has no seat.
    // An empty reason is refused: the system tools show it to the user.
    bool acquire(Kind kind, const std::string& reason);

    // Does nothing when nothing is held.
    void release();

    [[nodiscard]] bool isActive() const noexcept;
    [[nodiscard]] Kind kind() const noexcept;
    [[nodiscard]] std::string reason() const;

    [[nodiscard]] std::string errorString() const;

    // Whether this platform has a seat at all (on Linux: whether
    // `systemd-inhibit` can be found on PATH).
    [[nodiscard]] static bool isSupported();

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

ICoreSemanticVersion.h#

ICoreEssentials/System/ICoreSemanticVersion.h

ICoreSemanticVersion -- a Semantic Versioning 2.0.0 version number.

auto v = ICoreSemanticVersion::parse("1.4.0-rc.2+build.77"); v->majorVersion(); // 1 v->preRelease(); // "rc.2" v->buildMetadata(); // "build.77" *v < *ICoreSemanticVersion::parse("1.4.0"); // true: a pre-release sorts first

parse() is strict: it accepts exactly the grammar of semver.org, section 2 to 10 -- three dot-separated numbers with no leading zeros, an optional "-pre.release" part whose numeric identifiers have no leading zeros, and an optional "+build" part. Anything else, including "v1.2.3", "1.2" and "01.2.3", is std::nullopt. A number too large for 64 bits is refused.

ICoreSemanticVersion#

ICoreSemanticVersion.h:35 · class · pImpl · 15 declaration(s)

Opened by row PS5.10 of the Platform SDK product plan.

class ICoreSemanticVersion {
public:
    // 0.0.0
    ICoreSemanticVersion();
    ICoreSemanticVersion(std::uint64_t major, std::uint64_t minor, std::uint64_t patch);
    ~ICoreSemanticVersion();

    ICoreSemanticVersion(const ICoreSemanticVersion& other);
    ICoreSemanticVersion& operator=(const ICoreSemanticVersion& other);

    [[nodiscard]] static std::optional<ICoreSemanticVersion> parse(std::string_view text);

    [[nodiscard]] std::uint64_t majorVersion() const noexcept;
    [[nodiscard]] std::uint64_t minorVersion() const noexcept;
    [[nodiscard]] std::uint64_t patchVersion() const noexcept;

    // The parts after '-' and '+', without the separator; empty when absent.
    [[nodiscard]] std::string preRelease() const;
    [[nodiscard]] std::string buildMetadata() const;
    [[nodiscard]] bool isPreRelease() const noexcept;

    [[nodiscard]] std::string toString() const;

    // < 0, 0 or > 0 by precedence (build metadata ignored).
    [[nodiscard]] int compare(const ICoreSemanticVersion& other) const noexcept;

    // Every part equal, build metadata included.
    [[nodiscard]] bool isIdenticalTo(const ICoreSemanticVersion& other) const noexcept;

    friend bool operator==(const ICoreSemanticVersion& a, const ICoreSemanticVersion& b) noexcept;
    friend bool operator!=(const ICoreSemanticVersion& a, const ICoreSemanticVersion& b) noexcept;
    friend bool operator<(const ICoreSemanticVersion& a, const ICoreSemanticVersion& b) noexcept;
    friend bool operator<=(const ICoreSemanticVersion& a, const ICoreSemanticVersion& b) noexcept;
    friend bool operator>(const ICoreSemanticVersion& a, const ICoreSemanticVersion& b) noexcept;
    friend bool operator>=(const ICoreSemanticVersion& a, const ICoreSemanticVersion& b) noexcept;

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

ICoreSingleInstance.h#

ICoreEssentials/System/ICoreSingleInstance.h

ICoreSingleInstance -- one running copy of an application per user; a second launch hands its arguments to the first and exits.

int main(int argc, char** argv) { ICoreSingleInstance instance("com.example.editor"); if (!instance.isPrimary()) { return instance.sendToPrimary(argumentsOf(argc, argv)) ? 0 : 1; } ICoreApplication app(argc, argv); instance.setMessageHandler([&](const std::vector<std::string>& args) { openFiles(args); }); ... }

WHO IS PRIMARY is decided by an ICoreLockFile, not by the socket: the

ICoreSingleInstance#

ICoreSingleInstance.h:46 · class · pImpl · 9 declaration(s)

Opened by row PS5.21 of the Platform SDK product plan.

class ICoreSingleInstance {
public:
    // Decides at once whether this process is the primary for `key`.
    explicit ICoreSingleInstance(const std::string& key);

    // The primary stops listening and releases the lock: the next launch
    // becomes the primary.
    ~ICoreSingleInstance();

    ICoreSingleInstance(const ICoreSingleInstance&) = delete;
    ICoreSingleInstance& operator=(const ICoreSingleInstance&) = delete;

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

    // Secondary only: hands `arguments` to the primary. Waits up to
    // `timeoutMs` for the primary to be listening and to confirm receipt.
    bool sendToPrimary(const std::vector<std::string>& arguments, int timeoutMs = 5000);

    // Primary only: receives each later launch's arguments.
    void setMessageHandler(std::function<void(const std::vector<std::string>&)> handler);

    // The primary's process id, as its lock file records it.
    [[nodiscard]] std::optional<std::int64_t> primaryProcessId() const;

    // Why the primary could not listen, or why sendToPrimary() failed.
    [[nodiscard]] std::string errorString() const;

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

ICoreSystemInfo.h#

ICoreEssentials/System/ICoreSystemInfo.h

ICoreSystemInfo -- facts about the machine and the running process.

logicalCpuCount() hardware threads the OS schedules on (>= 1) physicalCpuCount() cores; equals logicalCpuCount() where the platform does not say (a browser, some Android devices) physicalMemoryBytes() installed RAM; 0 when the platform does not say hostName() this machine's network name userName() the login name of the user running the process cpuArchitecture() the architecture THIS PROCESS was built for: "arm64", "x86_64", "x86", "arm", "wasm32", "riscv64" or "unknown". An x86_64 build running under translation on an arm64 Mac says "x86_64". processId() this process's id

ICoreSystemInfo#

ICoreSystemInfo.h:30 · class · 8 declaration(s)

Opened by row PS5.11 of the Platform SDK product plan.

class ICoreSystemInfo {
public:
    ICoreSystemInfo() = delete;

    [[nodiscard]] static int logicalCpuCount();
    [[nodiscard]] static int physicalCpuCount();
    [[nodiscard]] static std::uint64_t physicalMemoryBytes();
    [[nodiscard]] static std::string hostName();
    [[nodiscard]] static std::string userName();
    [[nodiscard]] static std::string cpuArchitecture();
    [[nodiscard]] static std::int64_t processId();
};
};

ICoreUndoStack.h#

ICoreEssentials/System/ICoreUndoStack.h

ICoreUndoStack -- undo and redo for any kind of document, with no UI.

ICoreUndoStack stack; const std::string before = doc.text(), after = before + "x"; stack.push("Type", [&doc, after] { doc.setText(after); }, // redo -- runs now [&doc, before] { doc.setText(before); }); // undo stack.undo(); // doc.text() == before stack.redo(); // doc.text() == after

A command is a pair of functions rather than a class to derive from: push() runs redo at once and records both. Capture the STATE each function needs (as above) rather than a pointer to live state the next command will change.

ICoreUndoStack#

ICoreUndoStack.h:50 · class · pImpl · 25 declaration(s)

Opened by row PS5.27 of the Platform SDK product plan.

class ICoreUndoStack {
public:
    using Action = std::function<void()>;

    ICoreUndoStack();
    ~ICoreUndoStack();

    ICoreUndoStack(const ICoreUndoStack&) = delete;
    ICoreUndoStack& operator=(const ICoreUndoStack&) = delete;

    void push(const std::string& text, Action redo, Action undo);
    void push(const std::string& text, Action redo, Action undo, int mergeId);

    void beginMacro(const std::string& text);
    void endMacro();
    [[nodiscard]] bool isInMacro() const noexcept;

    [[nodiscard]] bool canUndo() const noexcept;
    [[nodiscard]] bool canRedo() const noexcept;
    void undo();
    void redo();

    // The text of the step undo() / redo() would apply; empty when none.
    [[nodiscard]] std::string undoText() const;
    [[nodiscard]] std::string redoText() const;

    // Steps recorded, and how many of them are applied (0..count()).
    [[nodiscard]] int count() const noexcept;
    [[nodiscard]] int index() const noexcept;

    // Undo or redo until index() == `index` (clamped to 0..count()).
    void setIndex(int index);

    void setClean();
    [[nodiscard]] bool isClean() const noexcept;

    // The index setClean() recorded, or -1 when it is unreachable.
    [[nodiscard]] int cleanIndex() const noexcept;

    // 0 (the default) keeps every step.
    void setUndoLimit(int limit);
    [[nodiscard]] int undoLimit() const noexcept;

    // Forgets every step without running any action. Clean again afterwards.
    void clear();

    void setChangedHandler(std::function<void()> handler);

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

ICoreUuid.h#

ICoreEssentials/System/ICoreUuid.h

ICoreUuid -- a 128-bit universally unique identifier (RFC 9562).

ICoreUuid id = ICoreUuid::createV7(); std::string text = id.toString(); // "01920fd2-3b4e-7c1a-9f00-8d2e4b6a1c55" std::optional<ICoreUuid> back = ICoreUuid::fromString(text);

Two generators:

createV4() 122 random bits. Use it when an id must reveal nothing. createV7() a 48-bit Unix-millisecond timestamp followed by random bits, so ids sort by creation time. Use it for database keys and anything that is listed in order. Within one process every createV7() is strictly greater than the one before, even within a single millisecond.

ICoreUuid#

ICoreUuid.h:38 · class · 11 declaration(s)

Opened by row PS5.2 of the Platform SDK product plan.

class ICoreUuid {
public:
    // The nil UUID.
    ICoreUuid() noexcept;

    [[nodiscard]] static ICoreUuid createV4();
    [[nodiscard]] static ICoreUuid createV7();

    [[nodiscard]] static std::optional<ICoreUuid> fromString(std::string_view text);

    // Exactly 16 bytes in network order, or std::nullopt.
    [[nodiscard]] static std::optional<ICoreUuid> fromBytes(const ICoreByteArray& bytes);

    [[nodiscard]] std::string toString() const;
    [[nodiscard]] ICoreByteArray toBytes() const;

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

    // The version nibble: 4 or 7 for this class's generators, 0 for nil.
    [[nodiscard]] int version() const noexcept;

    // For a v7 UUID, the Unix time in milliseconds it was made at.
    [[nodiscard]] std::optional<std::int64_t> unixMilliseconds() const noexcept;

    // A well-mixed hash of the 16 bytes, for unordered containers.
    [[nodiscard]] std::size_t hash() const noexcept;

    friend bool operator==(const ICoreUuid& a, const ICoreUuid& b) noexcept;
    friend bool operator!=(const ICoreUuid& a, const ICoreUuid& b) noexcept;
    friend bool operator<(const ICoreUuid& a, const ICoreUuid& b) noexcept;
    friend bool operator<=(const ICoreUuid& a, const ICoreUuid& b) noexcept;
    friend bool operator>(const ICoreUuid& a, const ICoreUuid& b) noexcept;
    friend bool operator>=(const ICoreUuid& a, const ICoreUuid& b) noexcept;

};