StringBuilder.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 <format>
#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 append( 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 ConstIterator = const char*;

        using iterator = Iterator;

        using const_iterator = ConstIterator;

        [[nodiscard]] Iterator begin() noexcept;

        [[nodiscard]] ConstIterator begin() const noexcept;

        [[nodiscard]] Iterator end() noexcept;

        [[nodiscard]] ConstIterator 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;
        friend class std::back_insert_iterator<StringBuilder>;
 
        //----------------------------------------------
        // 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 append( 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 );

        inline StringBuilder& operator<<( std::int32_t value );

        inline StringBuilder& operator<<( std::uint32_t value );

        inline StringBuilder& operator<<( std::int64_t value );

        inline StringBuilder& operator<<( std::uint64_t value );

        inline StringBuilder& operator<<( float value );

        inline StringBuilder& operator<<( double value );
 
        //----------------------------------------------
        // Formatting operations
        //----------------------------------------------

        template <typename... Args>
        inline StringBuilder& format( std::format_string<Args...> fmt, Args&&... args );
 
        //----------------------------------------------
        // 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 ConstIterator = const char*;

        using iterator = Iterator;

        using const_iterator = ConstIterator;

        inline Iterator begin();

        inline ConstIterator begin() const;

        inline Iterator end();

        inline ConstIterator end() const;
 
    private:
        //----------------------------------------------
        // Container interface (for std::back_inserter support)
        //----------------------------------------------

        inline void push_back( char c ) { append( c ); }
 
        //----------------------------------------------
        // 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();

        [[nodiscard]] static StringBuilderLease lease( size_t capacityHint );
 
        //----------------------------
        // 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/StringBuilder.inl"