StringBuilderPool.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 <memory>
#include <string>
#include <string_view>
 
namespace nfx::string
{
    //=====================================================================
    // DynamicStringBuffer class
    //=====================================================================
 
    class DynamicStringBuffer final
    {
        friend class DynamicStringBufferPool;
 
    private:
        //----------------------------------------------
        // Construction
        //----------------------------------------------
 
        DynamicStringBuffer();
 
        explicit DynamicStringBuffer( size_t initialCapacity );
 
    public:
        DynamicStringBuffer( const DynamicStringBuffer& other );
 
        DynamicStringBuffer( DynamicStringBuffer&& other ) noexcept;
 
        //----------------------------------------------
        // Destruction
        //----------------------------------------------
 
        ~DynamicStringBuffer() = default;
 
        //----------------------------------------------
        // Assignment
        //----------------------------------------------
 
        DynamicStringBuffer& operator=( const DynamicStringBuffer& other );
 
        DynamicStringBuffer& operator=( DynamicStringBuffer&& other ) noexcept;
 
        //----------------------------------------------
        // Capacity and size information
        //----------------------------------------------
 
        [[nodiscard]] size_t size() const noexcept;
 
        [[nodiscard]] size_t capacity() const noexcept;
 
        [[nodiscard]] bool isEmpty() const noexcept;
 
        //----------------------------------------------
        // Buffer management
        //----------------------------------------------
 
        void clear() noexcept;
 
        void reserve( size_t newCapacity );
 
        void resize( size_t newSize );
 
        //----------------------------------------------
        // Data access
        //----------------------------------------------
 
        [[nodiscard]] char* data() noexcept;
 
        [[nodiscard]] const char* data() const noexcept;
 
        char& operator[]( size_t index );
 
        const char& operator[]( size_t index ) const;
 
        //----------------------------------------------
        // Content manipulation
        //----------------------------------------------
 
        void append( std::string_view str );
 
        void append( const std::string& str );
 
        void append( const char* str );
 
        void push_back( char c );
 
        //----------------------------------------------
        // String conversion
        //----------------------------------------------
 
        [[nodiscard]] std::string toString() const;
 
        [[nodiscard]] std::string_view toStringView() const noexcept;
 
        //----------------------------------------------
        // Iterator interface
        //----------------------------------------------
 
        using value_type = char;
 
        using iterator = char*;
 
        using const_iterator = const char*;
 
        [[nodiscard]] iterator begin() noexcept;
 
        [[nodiscard]] const_iterator begin() const noexcept;
 
        [[nodiscard]] iterator end() noexcept;
 
        [[nodiscard]] const_iterator end() const noexcept;
 
    private:
        //----------------------------------------------
        // Small buffer optimization constants
        //----------------------------------------------
 
        static constexpr size_t STACK_BUFFER_SIZE = 256;
 
        static constexpr auto GROWTH_FACTOR = 1.5;
 
        //----------------------------------------------
        // Private members
        //----------------------------------------------
 
        alignas( char ) char m_stackBuffer[STACK_BUFFER_SIZE];
 
        std::unique_ptr<char[]> m_heapBuffer;
 
        size_t m_size;
 
        size_t m_capacity;
 
        bool m_onHeap;
 
        //----------------------------------------------
        // Private methods
        //----------------------------------------------
 
        void ensureCapacity( size_t needed_capacity );
 
        char* currentBuffer() noexcept;
 
        const char* currentBuffer() const noexcept;
    };
 
    //=====================================================================
    // StringBuilder class
    //=====================================================================
 
    class StringBuilder final
    {
        friend class StringBuilderLease;
 
        //----------------------------------------------
        // Construction
        //----------------------------------------------
    private:
        inline explicit StringBuilder( DynamicStringBuffer& buffer );
 
    public:
        StringBuilder() = delete;
 
        StringBuilder( const StringBuilder& ) = default;
 
        StringBuilder( StringBuilder&& ) noexcept = delete;
 
        //----------------------------------------------
        // Destruction
        //----------------------------------------------
 
        ~StringBuilder() = default;
 
        //----------------------------------------------
        // Assignment
        //----------------------------------------------
 
        StringBuilder& operator=( const StringBuilder& ) = delete;
 
        StringBuilder& operator=( StringBuilder&& ) noexcept = delete;
 
        //----------------------------------------------
        // Array access operators
        //----------------------------------------------
 
        inline char& operator[]( size_t index );
 
        inline const char& operator[]( size_t index ) const;
 
        //----------------------------------------------
        // String append operations
        //----------------------------------------------
 
        inline void append( std::string_view str );
 
        inline void append( const std::string& str );
 
        inline void append( const char* str );
 
        inline void push_back( char c );
 
        //----------------------------------------------
        // Stream operators
        //----------------------------------------------
 
        inline StringBuilder& operator<<( std::string_view str );
 
        inline StringBuilder& operator<<( const std::string& str );
 
        inline StringBuilder& operator<<( const char* str );
 
        inline StringBuilder& operator<<( char c );
 
        //----------------------------------------------
        // Size and capacity management
        //----------------------------------------------
 
        inline size_t length() const noexcept;
 
        inline void resize( size_t newSize );
 
        //----------------------------------------------
        // Iterator interface
        //----------------------------------------------
 
        using value_type = char;
 
        using iterator = char*;
 
        using const_iterator = const char*;
 
        inline iterator begin();
 
        inline const_iterator begin() const;
 
        inline iterator end();
 
        inline const_iterator end() const;
 
        //----------------------------------------------
        // StringBuilder::Enumerator class
        //----------------------------------------------
 
        class Enumerator
        {
        public:
            //----------------------------
            // Construction
            //----------------------------
 
            inline Enumerator( const StringBuilder& builder );
 
            //----------------------------
            // Destruction
            //----------------------------
 
            ~Enumerator() = default;
 
            //----------------------------
            // Enumerator operations
            //----------------------------
 
            inline bool next();
 
            inline char current() const;
 
            inline void reset();
 
        private:
            //----------------------------
            // Private member variables
            //----------------------------
 
            const char* m_data;
 
            const char* m_end;
 
            const char* m_current;
        };
 
    private:
        //----------------------------------------------
        // Private member variables
        //----------------------------------------------
 
        DynamicStringBuffer& m_buffer;
    };
 
    //=====================================================================
    // StringBuilderLease class
    //=====================================================================
 
    class StringBuilderLease final
    {
        friend class StringBuilderPool;
 
        //----------------------------------------------
        // Construction
        //----------------------------------------------
    private:
        inline explicit StringBuilderLease( DynamicStringBuffer* buffer );
 
    public:
        StringBuilderLease() = delete;
 
        StringBuilderLease( const StringBuilderLease& ) = delete;
 
        inline StringBuilderLease( StringBuilderLease&& other ) noexcept;
 
        //----------------------------------------------
        // Destruction
        //----------------------------------------------
 
        ~StringBuilderLease();
 
        //----------------------------------------------
        // Assignment
        //----------------------------------------------
 
        StringBuilderLease& operator=( const StringBuilderLease& ) = delete;
 
        inline StringBuilderLease& operator=( StringBuilderLease&& other ) noexcept;
 
        //----------------------------------------------
        // Public interface methods
        //----------------------------------------------
 
        [[nodiscard]] inline StringBuilder create();
 
        [[nodiscard]] inline DynamicStringBuffer& buffer();
 
        [[nodiscard]] inline std::string toString() const;
 
    private:
        //----------------------------------------------
        // Private implementation methods
        //----------------------------------------------
 
        void dispose();
 
        [[noreturn]] void throwInvalidOperation() const;
 
        //----------------------------------------------
        // Private member variables
        //----------------------------------------------
 
        DynamicStringBuffer* m_buffer;
 
        bool m_valid;
    };
 
    //=====================================================================
    // StringBuilderPool class
    //=====================================================================
 
    class StringBuilderPool final
    {
    public:
        //----------------------------------------------
        // Pool statistics structure
        //----------------------------------------------
 
        struct PoolStatistics
        {
            uint64_t threadLocalHits;
 
            uint64_t dynamicStringBufferPoolHits;
 
            uint64_t newAllocations;
 
            uint64_t totalRequests;
 
            double hitRate;
        };
 
    private:
        //----------------------------------------------
        // Construction
        //----------------------------------------------
 
        StringBuilderPool() = default;
 
    public:
        //----------------------------------------------
        // Static factory methods
        //----------------------------------------------
 
        [[nodiscard]] static StringBuilderLease lease();
 
        //----------------------------
        // Statistics methods
        //----------------------------
 
        static PoolStatistics stats() noexcept;
 
        static void resetStats() noexcept;
 
        //----------------------------
        // Lease management
        //----------------------------
 
        static size_t clear();
 
        static size_t size() noexcept;
    };
} // namespace nfx::string
 
#include "nfx/detail/string/StringBuilderPool.inl"