API — ICoreEssentials/Serialization

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

ICoreJsonArray.h#

src/ICoreEssentials/Serialization/ICoreJsonArray.h

ICoreJsonArray#

ICoreJsonArray.h:43 · class · pImpl · nested const_iterator · 21 declaration(s)

ICoreJsonArray -- an ordered list of JSON values.

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

    // ⚠ COPY ONLY, AND THE MOVES ARE ABSENT ON PURPOSE. Declaring the copy
    // suppresses the implicit moves, so `ICoreJsonArray b = std::move(a)`
    // copies and leaves `a` intact and usable. A pointer-stealing move would
    // leave `a` holding a null Impl, and every method here dereferences it --
    // where the old std::vector member left a moved-from array EMPTY and
    // perfectly valid. Nothing in the tree moves one of these.
    ICoreJsonArray(const ICoreJsonArray& other);
    ICoreJsonArray& operator=(const ICoreJsonArray& other);

    ICoreJsonArray(std::initializer_list<ICoreJsonValue> values);

    // --- reading ------------------------------------------------------------
    [[nodiscard]] bool isEmpty() const;
    [[nodiscard]] std::ptrdiff_t size() const;
    [[nodiscard]] std::ptrdiff_t count() const;

    // Out of range yields an undefined value, as QJsonArray::at() did rather
    // than reading past the end.
    [[nodiscard]] ICoreJsonValue at(std::ptrdiff_t i) const;
    [[nodiscard]] ICoreJsonValue first() const;
    [[nodiscard]] ICoreJsonValue last() const;
    [[nodiscard]] ICoreJsonValue operator[](std::ptrdiff_t i) const;

    [[nodiscard]] bool contains(const ICoreJsonValue& value) const;

    // --- writing ------------------------------------------------------------
    void append(const ICoreJsonValue& value);
    void removeAt(std::ptrdiff_t i);

    // --- iteration ----------------------------------------------------------
    class const_iterator {
    public:
        // The array pointer and the index, measured on this tree: two 8-byte
        // trivially-copyable members. Pinned by static_asserts in the .cpp, so
        // a change to either is a build error rather than a silent overrun.
        static constexpr std::size_t kStateSize = 16;
        static constexpr std::size_t kStateAlign = 8;

        const_iterator(const ICoreJsonArray* a, std::ptrdiff_t i);

        ICoreJsonValue operator*() const;
        const_iterator& operator++();
        bool operator==(const const_iterator& o) const;
        bool operator!=(const const_iterator& o) const;

    private:
        alignas(kStateAlign) std::byte m_storage[kStateSize];
    };

    [[nodiscard]] const_iterator begin() const;
    [[nodiscard]] const_iterator end() const;
    [[nodiscard]] const_iterator constBegin() const;
    [[nodiscard]] const_iterator constEnd() const;

    bool operator==(const ICoreJsonArray& other) const;
    bool operator!=(const ICoreJsonArray& other) const;

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

ICoreJsonDocument.h#

src/ICoreEssentials/Serialization/ICoreJsonDocument.h

ICoreJsonParseError#

ICoreJsonDocument.h:51 · class · pImpl · 6 declaration(s)

ICoreJsonDocument (+ ICoreJsonParseError) -- a whole JSON document, and the parser and writer for the family.

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

    // Copy only; see ICoreJsonArray.h on why the moves are not declared.
    ICoreJsonParseError(const ICoreJsonParseError& other);
    ICoreJsonParseError& operator=(const ICoreJsonParseError& other);

    [[nodiscard]] bool hasError() const;
    [[nodiscard]] ICoreString errorString() const;

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

ICoreJsonDocument#

ICoreJsonDocument.h:77 · class · pImpl · 15 declaration(s)

class ICoreJsonDocument {
public:
    enum JsonFormat { Indented, Compact };

    ICoreJsonDocument();
    ~ICoreJsonDocument();

    // Copy only; see ICoreJsonArray.h on why the moves are not declared.
    // fromJson() returns a local by value, which C++17 elides.
    ICoreJsonDocument(const ICoreJsonDocument& other);
    ICoreJsonDocument& operator=(const ICoreJsonDocument& other);

    explicit ICoreJsonDocument(const ICoreJsonObject& o);
    explicit ICoreJsonDocument(const ICoreJsonArray& a);

    static ICoreJsonDocument fromJson(const ICoreByteArray& json);
    static ICoreJsonDocument fromJson(const ICoreByteArray& json, ICoreJsonParseError* error);

    [[nodiscard]] ICoreByteArray toJson(JsonFormat format = Indented) const;

    [[nodiscard]] bool isNull() const;
    [[nodiscard]] bool isEmpty() const;
    [[nodiscard]] bool isObject() const;
    [[nodiscard]] bool isArray() const;

    [[nodiscard]] ICoreJsonObject object() const;
    [[nodiscard]] ICoreJsonArray  array() const;

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

ICoreJsonObject.h#

src/ICoreEssentials/Serialization/ICoreJsonObject.h

ICoreJsonObject#

ICoreJsonObject.h:57 · class · pImpl · nested Ref, const_iterator · 22 declaration(s)

ICoreJsonObject -- a JSON object: string keys to values.

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

    // Copy only -- see the note on ICoreJsonArray's: declaring the copy
    // suppresses the implicit moves, and a moved-from object with a null Impl
    // would crash where the old vector member left it empty and valid.
    ICoreJsonObject(const ICoreJsonObject& other);
    ICoreJsonObject& operator=(const ICoreJsonObject& other);

    ICoreJsonObject(std::initializer_list<std::pair<ICoreString, ICoreJsonValue>> entries);

    // --- reading ------------------------------------------------------------
    [[nodiscard]] bool isEmpty() const;
    [[nodiscard]] std::ptrdiff_t size() const;
    [[nodiscard]] std::ptrdiff_t count() const;
    [[nodiscard]] bool contains(const ICoreString& key) const;

    // A missing key yields UNDEFINED, as QJsonObject::value() does. Call sites
    // lean on it: `obj.value(k).toString()` on an absent key gives "" rather
    // than inserting anything.
    [[nodiscard]] ICoreJsonValue value(const ICoreString& key) const;

    [[nodiscard]] ICoreList<ICoreString> keys() const;

    // --- writing ------------------------------------------------------------
    // Replaces an existing key rather than duplicating it, which is also what
    // makes a parsed document's duplicate keys resolve last-wins, as Qt's do.
    void insert(const ICoreString& key, const ICoreJsonValue& value);
    void remove(const ICoreString& key);
    ICoreJsonValue take(const ICoreString& key);

    // --- subscript ----------------------------------------------------------
    class Ref {
    public:
        Ref(ICoreJsonObject* owner, ICoreString key);
        ~Ref();

        // The full set, because a Ref had every one of these implicitly before
        // the unique_ptr member deleted them. It is a proxy call sites build,
        // assign through and drop on the same line, so none of them is hot.
        Ref(const Ref& other);
        Ref& operator=(const Ref& other);

        Ref& operator=(const ICoreJsonValue& value);
        operator ICoreJsonValue() const;

    private:
        class Impl;
        std::unique_ptr<Impl> impl;
    };

    Ref operator[](const ICoreString& key);
    [[nodiscard]] ICoreJsonValue operator[](const ICoreString& key) const;

    // --- iteration ----------------------------------------------------------
    class const_iterator {
    public:
        using Underlying = std::vector<std::pair<ICoreString, ICoreJsonValue>>::const_iterator;

        // One vector iterator, measured on this tree. Pinned by static_asserts
        // in the .cpp, so a change is a build error rather than an overrun.
        static constexpr std::size_t kStateSize = 8;
        static constexpr std::size_t kStateAlign = 8;

        explicit const_iterator(Underlying it);

        [[nodiscard]] ICoreString    key() const;
        [[nodiscard]] ICoreJsonValue value() const;

        const_iterator& operator++();
        bool operator==(const const_iterator& o) const;
        bool operator!=(const const_iterator& o) const;

    private:
        alignas(kStateAlign) std::byte m_storage[kStateSize];
    };

    [[nodiscard]] const_iterator begin() const;
    [[nodiscard]] const_iterator end() const;
    [[nodiscard]] const_iterator constBegin() const;
    [[nodiscard]] const_iterator constEnd() const;

    bool operator==(const ICoreJsonObject& other) const;
    bool operator!=(const ICoreJsonObject& other) const;

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

ICoreJsonValue.h#

src/ICoreEssentials/Serialization/ICoreJsonValue.h

ICoreJsonValue#

ICoreJsonValue.h:70 · class · pImpl · 32 declaration(s)

class ICoreJsonValue {
public:
    // The two JSON "empties". Spelled as an enum so the call site reads
    // ICoreJsonValue::Null exactly as it read QJsonValue::Null.
    enum SpecialValue { Null, Undefined };

    ICoreJsonValue();
    ~ICoreJsonValue();

    ICoreJsonValue(const ICoreJsonValue& other);
    ICoreJsonValue(ICoreJsonValue&& other) noexcept;
    ICoreJsonValue& operator=(const ICoreJsonValue& other);
    ICoreJsonValue& operator=(ICoreJsonValue&& other) noexcept;

    explicit ICoreJsonValue(SpecialValue v);

    ICoreJsonValue(bool b);
    ICoreJsonValue(int n);
    ICoreJsonValue(std::int64_t n);
    ICoreJsonValue(double d);
    ICoreJsonValue(const char* s);
    ICoreJsonValue(const ICoreString& s);
    ICoreJsonValue(const ICoreJsonObject& o);
    ICoreJsonValue(const ICoreJsonArray& a);

    // --- interrogation ------------------------------------------------------
    [[nodiscard]] bool isNull() const;
    [[nodiscard]] bool isUndefined() const;
    [[nodiscard]] bool isBool() const;
    [[nodiscard]] bool isDouble() const;
    [[nodiscard]] bool isString() const;
    [[nodiscard]] bool isObject() const;
    [[nodiscard]] bool isArray() const;

    // --- extraction ---------------------------------------------------------
    [[nodiscard]] ICoreString toString() const;
    [[nodiscard]] ICoreString toString(const ICoreString& defaultValue) const;
    [[nodiscard]] bool toBool(bool defaultValue = false) const;

    // Integral doubles only -- see the coercion note.
    [[nodiscard]] int toInt(int defaultValue = 0) const;
    [[nodiscard]] std::int64_t toInteger(std::int64_t defaultValue = 0) const;
    [[nodiscard]] double toDouble(double defaultValue = 0.0) const;

    [[nodiscard]] ICoreJsonObject toObject() const;
    [[nodiscard]] ICoreJsonArray toArray() const;

    bool operator==(const ICoreJsonValue& other) const;
    bool operator!=(const ICoreJsonValue& other) const;

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

ICoreSettings.h#

src/ICoreEssentials/Serialization/ICoreSettings.h

ICoreSettings#

ICoreSettings.h:53 · class · pImpl · 16 declaration(s)

ICoreSettings -- a persisted key/value file, in QSettings' INI dialect.

class ICoreSettings {
public:
    explicit ICoreSettings(const ICoreString& path);
    ~ICoreSettings();

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

    [[nodiscard]] bool hasError() const;

    [[nodiscard]] bool contains(const ICoreString& key) const;

    [[nodiscard]] ICoreVariant value(const ICoreString& key) const;
    [[nodiscard]] ICoreVariant value(const ICoreString& key,
                                     const ICoreVariant& defaultValue) const;

    void setValue(const ICoreString& key, const ICoreVariant& value);

    void remove(const ICoreString& key);

    // --- groups and arrays --------------------------------------------------
    void beginGroup(const ICoreString& prefix);
    void endGroup();

    int beginReadArray(const ICoreString& prefix);
    void beginWriteArray(const ICoreString& prefix, int size = -1);
    void setArrayIndex(int i);
    void endArray();

    void sync();

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