Document.h

Go to the documentation of this file.

/*
 * MIT License
 *
 * Copyright (c) 2026 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 "Concepts.h"
 
#include <algorithm>
#include <compare>
#include <cstdint>
#include <memory>
#include <optional>
#include <span>
#include <stdexcept>
#include <string>
#include <string_view>
#include <variant>
#include <vector>
 
namespace nfx::json
{
    // Forward declarations
    class Document;

    enum class Type : uint8_t
    {
        Null,
        Boolean,
        Integer,
        UnsignedInteger,
        Double,
        String,
        Array,
        Object
    };

    using Object = std::vector<std::pair<std::string, Document>>;

    using Array = std::vector<Document>;
 
    //----------------------------------------------
    // Type trait specializations for Object and Array
    //----------------------------------------------

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

    template <>
    struct is_json_container<Array> : std::true_type
    {
    };
 
    //=====================================================================
    // Document class
    //=====================================================================

    class Document final
    {
    public:
        //----------------------------------------------
        // Construction
        //----------------------------------------------

        inline Document();

        inline Document( bool value ) noexcept;

        inline Document( int value ) noexcept;

        inline Document( unsigned int value ) noexcept;

        inline Document( int64_t value ) noexcept;

        inline Document( uint64_t value ) noexcept;

        inline Document( double value ) noexcept;

        inline explicit Document( std::string value );

        inline explicit Document( std::string_view value );

        inline explicit Document( const char* value );

        template <size_t N>
        inline Document( const char ( &value )[N] );

        inline Document( std::nullptr_t ) noexcept;

        inline explicit Document( Array value );

        inline explicit Document( Object value );

        template <typename T>
        inline Document(
            T value,
            std::enable_if_t<
                std::is_same_v<T, long> && !std::is_same_v<long, int> && !std::is_same_v<long, int64_t>,
                int> = 0 ) noexcept;

        template <typename T>
        inline Document(
            T value,
            std::enable_if_t<
                std::is_same_v<T, unsigned long> && !std::is_same_v<unsigned long, unsigned int> &&
                    !std::is_same_v<unsigned long, uint64_t>,
                int> = 0 ) noexcept;

        template <typename T>
        inline Document(
            T value,
            std::enable_if_t<std::is_same_v<T, long long> && !std::is_same_v<long long, int64_t>, int> = 0 ) noexcept;

        template <typename T>
        inline Document(
            T value,
            std::enable_if_t<
                std::is_same_v<T, unsigned long long> && !std::is_same_v<unsigned long long, uint64_t>,
                int> = 0 ) noexcept;

        Document( const Document& other ) = default;

#if defined( __GNUC__ ) && !defined( __clang__ )
#    pragma GCC diagnostic push
#    pragma GCC diagnostic ignored "-Wmaybe-uninitialized"
#endif
        Document( Document&& other ) noexcept = default;
#if defined( __GNUC__ ) && !defined( __clang__ )
#    pragma GCC diagnostic pop
#endif

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

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

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

        inline Document& operator=( std::string value );

        inline Document& operator=( bool value ) noexcept;

        inline Document& operator=( int64_t value ) noexcept;

        inline Document& operator=( uint64_t value ) noexcept;

        inline Document& operator=( double value ) noexcept;

        inline Document& operator=( std::nullptr_t ) noexcept;
 
        //----------------------------------------------
        // Comparison
        //----------------------------------------------

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

        std::strong_ordering operator<=>( const Document& other ) const noexcept;
 
        //----------------------------------------------
        // Static factory methods
        //----------------------------------------------

        [[nodiscard]] inline static Document object();

        [[nodiscard]] inline static Document array();
 
        //----------------------------------------------
        // Type queries
        //----------------------------------------------

        [[nodiscard]] inline Type type() const noexcept;
 
        //----------------------------------------------
        // Root value access
        //----------------------------------------------

        template <Value T>
        [[nodiscard]] inline std::optional<T> root() const;

        template <Value T>
        [[nodiscard]] inline bool root( T& out ) const;

        template <Value T>
        [[nodiscard]] inline std::optional<std::reference_wrapper<const T>> rootRef() const;

        template <Value T>
        [[nodiscard]] inline std::optional<std::reference_wrapper<T>> rootRef();

        template <Checkable T>
        [[nodiscard]] inline bool isRoot() const;

        template <typename Visitor>
        inline decltype( auto ) visit( Visitor&& visitor ) const;

        template <typename Visitor>
        inline decltype( auto ) visit( Visitor&& visitor );
 
        //----------------------------------------------
        // Object operations
        //----------------------------------------------

        [[nodiscard]] inline Document* find( std::string_view key ) noexcept;

        [[nodiscard]] inline const Document* find( std::string_view key ) const noexcept;

        inline void set( std::string key, Document value );

        [[nodiscard]] inline bool contains( std::string_view key ) const noexcept;

        [[nodiscard]] inline Document& at( std::string_view key );

        [[nodiscard]] inline const Document& at( std::string_view key ) const;

        [[nodiscard]] inline Document& at( size_t index );

        [[nodiscard]] inline const Document& at( size_t index ) const;

        inline Document& operator[]( std::string_view key );

        [[nodiscard]] inline const Document& operator[]( std::string_view key ) const;

        [[nodiscard]] inline Document& operator[]( size_t index );

        [[nodiscard]] inline const Document& operator[]( size_t index ) const;

        inline void clear();

        inline size_t erase( std::string_view key );

        inline size_t erase( const char* key );

        inline size_t erase( const std::string& key );

        template <typename iterator, typename = std::enable_if_t<!std::is_convertible_v<iterator, std::string_view>>>
        inline iterator erase( iterator it );

        template <typename iterator>
        inline iterator insert( iterator pos, Document value );
 
        //----------------------------------------------
        // Array operations
        //----------------------------------------------

        [[nodiscard]] inline size_t size() const noexcept;

        [[nodiscard]] inline bool empty() const noexcept;

        inline void push_back( Document value );

        inline void reserve( size_t capacity );

        [[nodiscard]] inline size_t capacity() const noexcept;

        [[nodiscard]] inline Document& front();

        [[nodiscard]] inline const Document& front() const;

        [[nodiscard]] inline Document& back();

        [[nodiscard]] inline const Document& back() const;

        [[nodiscard]] inline auto begin();

        [[nodiscard]] inline auto end();

        [[nodiscard]] inline auto begin() const;

        [[nodiscard]] inline auto end() const;
 
        //----------------------------------------------
        // Document::ObjectIterator
        //----------------------------------------------

        class ObjectIterator
        {
        public:
            using iterator_category = std::forward_iterator_tag;

            using value_type = std::pair<const std::string, Document>;

            using difference_type = std::ptrdiff_t;

            using pointer = const value_type*;

            using reference = const value_type&;

            using MapIterator = Object::const_iterator;

            MapIterator it;

            inline ObjectIterator( MapIterator iter );

            ObjectIterator( const ObjectIterator& ) = default;

            ObjectIterator( ObjectIterator&& ) noexcept = default;

            ObjectIterator& operator=( const ObjectIterator& ) = default;

            ObjectIterator& operator=( ObjectIterator&& ) noexcept = default;

            inline const std::string& key() const;

            inline const Document& value() const;

            inline Document& value();

            inline const Document& operator*() const;

            inline Document& operator*();

            inline ObjectIterator& operator++();

            inline bool operator!=( const ObjectIterator& other ) const;

            inline bool operator==( const ObjectIterator& other ) const;

            inline MapIterator base() const;
        };
 
        //----------------------------------------------
        // Object iteration
        //----------------------------------------------

        [[nodiscard]] inline ObjectIterator objectBegin() const;

        [[nodiscard]] inline ObjectIterator objectEnd() const;
 
        //----------------------------------------------
        // Document::KeysView class
        //----------------------------------------------

        class KeysView
        {
            const Object* m_obj;
 
        public:
            class iterator
            {
                Object::const_iterator m_it;
 
            public:
                using iterator_category = std::forward_iterator_tag;

                using value_type = std::string;

                using difference_type = std::ptrdiff_t;

                using pointer = const std::string*;

                using reference = const std::string&;

                inline iterator( Object::const_iterator it );

                iterator( const iterator& ) = default;

                iterator( iterator&& ) noexcept = default;

                iterator& operator=( const iterator& ) = default;

                iterator& operator=( iterator&& ) noexcept = default;

                inline reference operator*() const;

                inline pointer operator->() const;

                inline iterator& operator++();

                inline iterator operator++( int );

                inline bool operator==( const iterator& other ) const;

                inline bool operator!=( const iterator& other ) const;
            };

            inline KeysView( const Object* obj );

            inline iterator begin() const;

            inline iterator end() const;
        };

        class ValuesView
        {
            const Object* m_obj;
 
        public:
            class const_iterator
            {
                Object::const_iterator m_it;
 
            public:
                using iterator_category = std::forward_iterator_tag;

                using value_type = Document;

                using difference_type = std::ptrdiff_t;

                using pointer = const Document*;

                using reference = const Document&;

                inline const_iterator( Object::const_iterator it );

                const_iterator( const const_iterator& ) = default;

                const_iterator( const_iterator&& ) noexcept = default;

                const_iterator& operator=( const const_iterator& ) = default;

                const_iterator& operator=( const_iterator&& ) noexcept = default;

                inline reference operator*() const;

                inline pointer operator->() const;

                inline const_iterator& operator++();

                inline const_iterator operator++( int );

                inline bool operator==( const const_iterator& other ) const;

                inline bool operator!=( const const_iterator& other ) const;
            };

            class iterator
            {
                Object::iterator m_it;
 
            public:
                using iterator_category = std::forward_iterator_tag;

                using value_type = Document;

                using difference_type = std::ptrdiff_t;

                using pointer = Document*;

                using reference = Document&;

                inline iterator( Object::iterator it );

                iterator( const iterator& ) = default;

                iterator( iterator&& ) noexcept = default;

                iterator& operator=( const iterator& ) = default;

                iterator& operator=( iterator&& ) noexcept = default;

                inline reference operator*() const;

                inline pointer operator->() const;

                inline iterator& operator++();

                inline iterator operator++( int );

                inline bool operator==( const iterator& other ) const;

                inline bool operator!=( const iterator& other ) const;
            };

            inline ValuesView( const Object* obj );

            inline const_iterator begin() const;

            inline const_iterator end() const;
        };

        class MutableValuesView
        {
            Object* m_obj;
 
        public:
            class iterator
            {
                Object::iterator m_it;
 
            public:
                using iterator_category = std::forward_iterator_tag;
                using value_type = Document;
                using difference_type = std::ptrdiff_t;
                using pointer = Document*;
                using reference = Document&;

                inline iterator( Object::iterator it );

                iterator( const iterator& ) = default;

                iterator( iterator&& ) noexcept = default;

                iterator& operator=( const iterator& ) = default;

                iterator& operator=( iterator&& ) noexcept = default;

                inline reference operator*() const;

                inline pointer operator->() const;

                inline iterator& operator++();

                inline iterator operator++( int );

                inline bool operator==( const iterator& other ) const;

                inline bool operator!=( const iterator& other ) const;
            };

            inline MutableValuesView( Object* obj );

            inline iterator begin();

            inline iterator end();
        };

        [[nodiscard]] inline KeysView keys() const;

        [[nodiscard]] inline ValuesView values() const;

        [[nodiscard]] inline MutableValuesView values();
 
        //----------------------------------------------
        // Serialization
        //----------------------------------------------

        [[nodiscard]] std::string toString( int indent = 0, size_t bufferSize = 0 ) const;

        [[nodiscard]] inline std::vector<uint8_t> toBytes() const;
 
        //----------------------------------------------
        // High-level API with path support
        //----------------------------------------------

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

        [[nodiscard]] static bool fromString( std::string_view jsonStr, Document& value );

        [[nodiscard]] static std::optional<Document> fromBytes( const std::vector<uint8_t>& bytes );

        [[nodiscard]] static bool fromBytes( const std::vector<uint8_t>& bytes, Document& value );

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

        void update( std::string_view path, const Document& value );
 
        //----------------------------------------------
        // Template-based path operations
        //----------------------------------------------

        template <Value T>
        [[nodiscard]] std::optional<T> get( std::string_view path ) const;

        template <Value T>
        [[nodiscard]] bool get( std::string_view path, T& value ) const;

        template <Value T>
        [[nodiscard]] std::optional<std::reference_wrapper<const T>> getRef( std::string_view path ) const;

        template <Value T>
        [[nodiscard]] std::optional<std::reference_wrapper<T>> getRef( std::string_view path );

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

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

        template <Container T>
        void set( std::string_view path );

        void setNull( std::string_view path );

        template <Checkable T>
        [[nodiscard]] bool is( std::string_view path ) const;

        [[nodiscard]] bool isNull( std::string_view path ) const;

        [[nodiscard]] bool isValid() const;
 
        //----------------------------------------------
        // 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;                        

                inline Entry();

                Entry( Entry&& other ) noexcept = default;

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

                Entry( const Entry& other );

                Entry& operator=( const Entry& other );

                inline const Document& value() const;
            };
 
            //-----------------------------
            // Construction
            //-----------------------------

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

            inline iterator begin() const;

            inline iterator end() const;
 
            //-----------------------------
            // Direct access
            //-----------------------------

            inline size_t size() const;

            inline bool empty() const;

            inline const Entry& operator[]( size_t index ) const;
 
            //-----------------------------
            // 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&;

                inline iterator();

                inline iterator( const std::vector<Entry>* entries, size_t index );

                inline reference operator*() const;

                inline pointer operator->() const;

                inline iterator& operator++();

                inline iterator operator++( int );

                inline bool operator==( const iterator& other ) const;

                inline bool operator!=( const iterator& other ) const;
 
            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:
        //----------------------------------------------
        // Private internal access
        //----------------------------------------------

        template <typename T>
        const T& rootInternal() const;

        template <typename T>
        T& rootInternal();
 
        //----------------------------------------------
        // Private path helpers
        //----------------------------------------------

        bool containsPath( std::string_view path ) const;

        size_t erasePath( std::string_view path );
 
        //----------------------------------------------
        // Private navigation methods
        //----------------------------------------------

        Document* navigateToPath( std::string_view path, bool createPath = false );

        const Document* navigateToPath( std::string_view path ) const;

        Document* navigateToJsonPointer( std::string_view pointer, bool createPath = false );

        const Document* navigateToJsonPointer( std::string_view pointer ) const;

        static std::string unescapeJsonPointerToken( std::string_view token ) noexcept;

        static bool isValidArrayIndex( std::string_view token ) noexcept;
 
        //----------------------------------------------
        // Private members
        //----------------------------------------------
 
#if defined( __GNUC__ ) && !defined( __clang__ )
#    pragma GCC diagnostic push
#    pragma GCC diagnostic ignored "-Wmaybe-uninitialized"
#endif
        std::variant<std::nullptr_t, bool, int64_t, uint64_t, double, std::string, Array, Object> m_data;
#if defined( __GNUC__ ) && !defined( __clang__ )
#    pragma GCC diagnostic pop
#endif
    };
} // namespace nfx::json
 
#include "detail/Document.inl"