Document.h

Go to the documentation of this file.

/*
 * MIT License
 *
 * Copyright (c) 2025 nfx
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

 
#pragma once
 
#include <cstdint>
#include <iterator>
#include <memory>
#include <optional>
#include <span>
#include <string>
#include <string_view>
#include <type_traits>
#include <utility>
#include <vector>
 
#include "Concepts.h"
 
namespace nfx::serialization::json
{
    class Document_impl;
 
    //=====================================================================
    // Document class
    //=====================================================================

    class Document final
    {
    public:
        //----------------------------------------------
        // Forward declarations
        //----------------------------------------------
 
        class Array;
        class Object;
 
        //----------------------------------------------
        // Friends
        //----------------------------------------------
 
        friend class Document_impl;
        friend class SchemaValidator_impl;
 
        //----------------------------------------------
        // Construction
        //----------------------------------------------

        Document();

        Document( const Document& other );

        Document( Document&& other ) noexcept;
 
        //----------------------------------------------
        // Destruction
        //----------------------------------------------

        ~Document();
 
        //----------------------------------------------
        // Assignment
        //----------------------------------------------

        Document& operator=( const Document& other );

        Document& operator=( Document&& other ) noexcept;
 
        //----------------------------------------------
        // Comparison
        //----------------------------------------------

        bool operator==( const Document& other ) const;

        bool operator!=( const Document& other ) const;
 
        //----------------------------------------------
        // Factory
        //----------------------------------------------

        static std::optional<Document> fromString( std::string_view jsonStr );

        static bool fromString( std::string_view jsonStr, Document& doc );

        static std::optional<Document> fromBytes( std::span<const uint8_t> bytes );

        static bool fromBytes( std::span<const uint8_t> bytes, Document& doc );
 
        //----------------------------------------------
        // Output
        //----------------------------------------------

        std::string toString( int indent = 0 ) const;

        std::vector<uint8_t> toBytes() const;
 
        //----------------------------------------------
        // Merge / update operations
        //----------------------------------------------

        void merge( const Document& other, bool overwriteArrays = true );

        void update( std::string_view path, const Document& value );
 
        //----------------------------------------------
        // Value existence
        //----------------------------------------------

        bool contains( std::string_view path ) const;
 
        //----------------------------------------------
        // Value access
        //----------------------------------------------

        template <JsonValue T>
        std::optional<T> get( std::string_view path ) const;

        template <JsonValue T>
        bool get( std::string_view path, T& value ) const;
 
        //----------------------------------------------
        // Value modification
        //----------------------------------------------

        template <JsonValue T>
        void set( std::string_view path, const T& value );

        template <JsonValue T>
        void set( std::string_view path, T&& value );
 
        //-----------------------------
        // Type-only creation
        //-----------------------------

        template <JsonContainer T>
        void set( std::string_view path );
 
        //-----------------------------
        // Null operations
        //-----------------------------

        void setNull( std::string_view path );
 
        //----------------------------------------------
        // Type checking
        //----------------------------------------------

        template <JsonCheckable T>
        bool is( std::string_view path ) const;

        bool isNull( std::string_view path ) const;
 
        //----------------------------------------------
        // Validation and error handling
        //----------------------------------------------

        bool isValid() const;

        std::string lastError() const;
 
        //----------------------------------------------
        // Document::Object class
        //----------------------------------------------

        class Object final
        {
            //----------------------------------------------
            // Friends
            //----------------------------------------------
 
            friend class Document;
            friend class Document_impl;
 
            //-----------------------------
            // Construction
            //-----------------------------
 
        private:
            Object( Document* doc, std::string_view path );
 
        public:
            Object();

            Object( const Document::Object& other );

            Object( Document::Object&& other ) noexcept;
 
            //-----------------------------
            // Destruction
            //-----------------------------

            ~Object() = default;
 
            //-----------------------------
            // Assignment
            //-----------------------------

            Document::Object& operator=( const Document::Object& other );

            Document::Object& operator=( Document::Object&& other ) noexcept;
 
            //-----------------------------
            // Comparison
            //-----------------------------

            bool operator==( const Document::Object& other ) const;

            bool operator!=( const Document::Object& other ) const;
 
            //-----------------------------
            // Output
            //-----------------------------

            std::string toString( int indent = 0 ) const;

            std::vector<uint8_t> toBytes() const;
 
            //-----------------------------
            // Size
            //-----------------------------

            size_t size() const;
 
            //-----------------------------
            // Clearing
            //-----------------------------

            void clear();
 
            //-----------------------------
            // Field removal
            //-----------------------------

            bool removeField( std::string_view key );
 
            //-----------------------------
            // Field existence
            //-----------------------------

            bool contains( std::string_view fieldName ) const;
 
            //-----------------------------
            // Field access
            //-----------------------------

            template <JsonValue T>
            std::optional<T> get( std::string_view path ) const;

            template <JsonValue T>
            bool get( std::string_view path, T& value ) const;
 
            //-----------------------------
            // Field modification
            //-----------------------------

            template <JsonValue T>
            void set( std::string_view path, const T& value );

            template <JsonValue T>
            void set( std::string_view path, T&& value );
 
            //-----------------------------
            // Validation and error handling
            //-----------------------------

            bool isValid() const;

            std::string lastError() const;
 
            //----------------------------------------------
            // Document::Object::Iterator class
            //----------------------------------------------

            class Iterator
            {
            public:
                //-----------------------------
                // Iterator traits
                //-----------------------------

                using iterator_category = std::forward_iterator_tag;
                using value_type = std::pair<std::string, Document>;
                using difference_type = std::ptrdiff_t;
                using pointer = value_type*;
                using reference = value_type&;
 
                //-----------------------------
                // Construction
                //-----------------------------

                Iterator();

                Iterator( const Object* obj, size_t index );
 
                //-----------------------------
                // Operators
                //-----------------------------

                value_type operator*() const;

                Iterator& operator++();

                Iterator operator++( int );

                bool operator==( const Iterator& other ) const;

                bool operator!=( const Iterator& other ) const;
 
            private:
                const Object* m_obj; 
                size_t m_index;      
            };

            Iterator begin() const;

            Iterator end() const;
 
        private:
            //----------------------------------------------
            // Private helper methods for iterator
            //----------------------------------------------

            std::string keyAt( size_t index ) const;

            Document valueAt( size_t index ) const;
 
            //----------------------------------------------
            // Private data members
            //----------------------------------------------
 
            Document* m_doc;    
            std::string m_path; 
        };
 
        //----------------------------------------------
        // Document::Array class
        //----------------------------------------------

        class Array final
        {
            //-----------------------------
            // Friends
            //-----------------------------
 
            friend class Document;
            friend class Document_impl;
 
            //-----------------------------
            // Construction
            //-----------------------------
 
        private:
            Array( Document* doc, std::string_view path );
 
        public:
            Array();

            Array( const Document::Array& other );

            Array( Document::Array&& other ) noexcept;
 
            //-----------------------------
            // Destruction
            //-----------------------------

            ~Array() = default;
 
            //-----------------------------
            // Assignment
            //-----------------------------

            Document::Array& operator=( const Document::Array& other );

            Document::Array& operator=( Document::Array&& other ) noexcept;
 
            //-----------------------------
            // Comparison
            //-----------------------------

            bool operator==( const Document::Array& other ) const;

            bool operator!=( const Document::Array& other ) const;
 
            //-----------------------------
            // Output
            //-----------------------------

            std::string toString( int indent = 0 ) const;

            std::vector<uint8_t> toBytes() const;
 
            //-----------------------------
            // Size
            //-----------------------------

            size_t size() const;
 
            //-----------------------------
            // Clearing
            //-----------------------------

            void clear();
 
            //-----------------------------
            // Element removal
            //-----------------------------

            bool remove( size_t index );
 
            //-----------------------------
            // Element existence
            //-----------------------------

            bool contains( std::string_view indexStr ) const;
 
            //-----------------------------
            // Element access
            //-----------------------------

            template <JsonValue T>
            std::optional<T> get( size_t index ) const;

            template <JsonValue T>
            bool get( size_t index, T& value ) const;
 
            //-----------------------------
            // Nested element access
            //-----------------------------

            template <JsonValue T>
            std::optional<T> get( std::string_view path ) const;

            template <JsonValue T>
            bool get( std::string_view path, T& value ) const;
 
            //-----------------------------
            // Element modification
            //-----------------------------

            template <JsonValue T>
            void set( size_t index, const T& value );

            template <JsonValue T>
            void set( size_t index, T&& value );
 
            //-----------------------------
            // Nested element modification
            //-----------------------------

            template <JsonValue T>
            void set( std::string_view path, const T& value );

            template <JsonValue T>
            void set( std::string_view path, T&& value );
 
            //-----------------------------
            // Element addition
            //-----------------------------

            template <JsonValue T>
            void append( const T& value );

            template <JsonValue T>
            void append( T&& value );

            void append( Document& value );

            void append( Document::Array& value );

            void append( Document::Object& value );
 
            //-----------------------------
            // Element insertion
            //-----------------------------

            template <JsonValue T>
            void insert( size_t index, const T& value );

            template <JsonValue T>
            void insert( size_t index, T&& value );

            void insert( size_t index, Document& value );

            void insert( size_t index, Document::Array& value );

            void insert( size_t index, Document::Object& value );
 
            //-----------------------------
            // Validation and error handling
            //-----------------------------

            bool isValid() const;

            std::string lastError() const;
 
            //----------------------------------------------
            // Document::Array::Iterator class
            //----------------------------------------------

            class Iterator
            {
            public:
                //-----------------------------
                // Iterator traits
                //-----------------------------

                using iterator_category = std::forward_iterator_tag;
                using value_type = Document;
                using difference_type = std::ptrdiff_t;
                using pointer = value_type*;
                using reference = value_type&;
 
                //-----------------------------
                // Construction
                //-----------------------------

                Iterator();

                Iterator( const Array* arr, size_t index );
 
                //-----------------------------
                // Operators
                //-----------------------------

                value_type operator*() const;

                Iterator& operator++();

                Iterator operator++( int );

                bool operator==( const Iterator& other ) const;

                bool operator!=( const Iterator& other ) const;
 
            private:
                const Array* m_arr; 
                size_t m_index;     
            };

            Iterator begin() const;

            Iterator end() const;
 
        private:
            //-----------------------------
            // Private data members
            //-----------------------------
 
            Document* m_doc;    
            std::string m_path; 
        };
 
        //----------------------------------------------
        // Document::PathView class
        //----------------------------------------------

        class PathView final
        {
        public:
            //-----------------------------
            // Forward declaration
            //-----------------------------
 
            class Iterator;
 
            //-----------------------------
            // Format
            //-----------------------------

            enum class Format : bool
            {
                JsonPointer = 0, 
                DotNotation      
            };
 
            //-----------------------------
            // Path entry structure
            //-----------------------------

            struct Entry
            {
                std::string path;                   
                std::unique_ptr<Document> valuePtr; 
                size_t depth;                       
                bool isLeaf;                        

                const Document& value() const { return *valuePtr; }

                Entry() : depth{ 0 }, isLeaf{ false } {}

                Entry( Entry&& other ) noexcept = default;

                Entry& operator=( Entry&& other ) noexcept = default;

                Entry( const Entry& other );

                Entry& operator=( const Entry& other );
            };
 
            //----------------------------------------------
            // Construction
            //----------------------------------------------

            explicit PathView(
                const Document& doc,
                Format format = Format::JsonPointer,
                bool includeContainers = true );
 
            //----------------------------------------------
            // Range interface (for range-for loops)
            //----------------------------------------------

            Iterator begin() const { return Iterator{ &m_entries, 0 }; }

            Iterator end() const { return Iterator{ &m_entries, m_entries.size() }; }
 
            //----------------------------------------------
            // Direct access
            //----------------------------------------------

            size_t size() const { return m_entries.size(); }

            bool empty() const { return m_entries.empty(); }

            const Entry& operator[]( size_t index ) const { return m_entries[index]; }
 
            //----------------------------------------------
            // Filtering
            //----------------------------------------------

            std::vector<Entry> leaves() const;
 
            //----------------------------------------------
            // Document::PathView::Iterator class
            //----------------------------------------------

            class Iterator
            {
            public:
                using iterator_category = std::forward_iterator_tag;
                using value_type = Entry;
                using difference_type = std::ptrdiff_t;
                using pointer = const Entry*;
                using reference = const Entry&;

                Iterator()
                    : m_entries{ nullptr },
                      m_index{ 0 }
                {
                }

                Iterator( const std::vector<Entry>* entries, size_t index )
                    : m_entries{ entries },
                      m_index{ index }
                {
                }

                reference operator*() const { return ( *m_entries )[m_index]; }

                pointer operator->() const { return &( *m_entries )[m_index]; }

                Iterator& operator++()
                {
                    ++m_index;
                    return *this;
                }

                Iterator operator++( int )
                {
                    Iterator tmp = *this;
                    ++m_index;
                    return tmp;
                }

                bool operator==( const Iterator& other ) const
                {
                    if ( !m_entries && !other.m_entries )
                    {
                        return true;
                    }
                    if ( !m_entries )
                    {
                        return other.m_index >= other.m_entries->size();
                    }
                    if ( !other.m_entries )
                    {
                        return m_index >= m_entries->size();
                    }
                    return m_entries == other.m_entries && m_index == other.m_index;
                }

                bool operator!=( const Iterator& other ) const { return !( *this == other ); }
 
            private:
                const std::vector<Entry>* m_entries; 
                size_t m_index;                      
            };
 
        private:
            //----------------------------------------------
            // Private helper methods
            //----------------------------------------------

            void buildEntries( const Document& doc );

            std::string formatPath( const std::vector<std::string>& segments ) const;
 
            //----------------------------------------------
            // Private data members
            //----------------------------------------------
 
            Format m_format;              
            bool m_includeContainers;     
            std::vector<Entry> m_entries; 
        };
 
    private:
        //----------------------------------------------
        // Pimpl
        //----------------------------------------------
 
        void* m_impl;
    };
 
    //=====================================================================
    // Type trait specializations for Document nested classes
    //=====================================================================

    template <>
    struct is_json_container<Document::Object> : std::true_type
    {
    };

    template <>
    struct is_json_container<Document::Array> : std::true_type
    {
    };
} // namespace nfx::serialization::json