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>

#if defined( _MSC_VER )
#    define NFX_STRINGBUILDER_FORCE_INLINE __forceinline
#elif defined( __GNUC__ ) || defined( __clang__ )
#    define NFX_STRINGBUILDER_FORCE_INLINE __attribute__( ( always_inline ) ) inline
#else
#    define NFX_STRINGBUILDER_FORCE_INLINE inline
#endif
 
namespace nfx::string
{
    //=====================================================================
    // StringBuilder class
    //=====================================================================

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

        StringBuilder();

        explicit StringBuilder( size_t initialCapacity );

        StringBuilder( const StringBuilder& other );

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

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

        StringBuilder& operator=( const StringBuilder& other );

        StringBuilder& operator=( StringBuilder&& other ) noexcept;
 
        //----------------------------------------------
        // Capacity and size information
        //----------------------------------------------

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

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

        [[nodiscard]] inline bool isEmpty() const noexcept;
 
        //----------------------------------------------
        // Data access
        //----------------------------------------------

        [[nodiscard]] inline char* data() noexcept;

        [[nodiscard]] inline const char* data() const noexcept;

        inline char& operator[]( size_t index );

        inline const char& operator[]( size_t index ) const;
 
        //----------------------------------------------
        // Buffer management
        //----------------------------------------------

        inline void clear() noexcept;

 
        inline void reserve( size_t newCapacity );

        inline void resize( size_t newSize );
 
        //----------------------------------------------
        // Append operations
        //----------------------------------------------

        inline StringBuilder& append( std::string_view str );

        inline StringBuilder& append( const std::string& str );

        inline StringBuilder& append( const char* str );

        template <size_t N>
        NFX_STRINGBUILDER_FORCE_INLINE StringBuilder& append( const char ( &str )[N] );

        inline StringBuilder& append( char c );

        inline StringBuilder& append( std::int8_t value );

        inline StringBuilder& append( std::uint8_t value );

        inline StringBuilder& append( std::int16_t value );

        inline StringBuilder& append( std::uint16_t value );

        inline StringBuilder& append( std::int32_t value );

        inline StringBuilder& append( std::uint32_t value );

        inline StringBuilder& append( std::int64_t value );

        inline StringBuilder& append( std::uint64_t value );

        inline StringBuilder& append( float value );

        inline StringBuilder& append( double value );
 
        //----------------------------------------------
        // Line operations
        //----------------------------------------------

        inline StringBuilder& appendLine( std::string_view str = "" );

        inline StringBuilder& appendLine( const std::string& str );

        inline StringBuilder& appendLine( const char* str );
 
        //----------------------------------------------
        // Prepend operations
        //----------------------------------------------

        StringBuilder& prepend( std::string_view str );

        inline StringBuilder& prepend( const std::string& str );

        inline StringBuilder& prepend( const char* str );

        inline StringBuilder& prepend( char c );

        inline StringBuilder& prepend( std::int8_t value );

        inline StringBuilder& prepend( std::uint8_t value );

        inline StringBuilder& prepend( std::int16_t value );

        inline StringBuilder& prepend( std::uint16_t value );

        inline StringBuilder& prepend( std::int32_t value );

        inline StringBuilder& prepend( std::uint32_t value );

        inline StringBuilder& prepend( std::int64_t value );

        inline StringBuilder& prepend( std::uint64_t value );

        inline StringBuilder& prepend( float value );

        inline StringBuilder& prepend( double value );
 
        //----------------------------------------------
        // Batch operations
        //----------------------------------------------

        template <typename T, typename... Args, typename = std::enable_if_t<( sizeof...( Args ) > 0 )>>
        inline StringBuilder& append( T&& first, Args&&... args );
 
        //----------------------------------------------
        // Join operations
        //----------------------------------------------

        template <typename Container>
        inline StringBuilder& join( const Container& items, std::string_view delimiter );

        template <typename Container>
        inline StringBuilder& join( const Container& items, char delimiter );
 
        //----------------------------------------------
        // Stream operators
        //----------------------------------------------

        inline StringBuilder& operator<<( std::string_view str );

        inline StringBuilder& operator<<( const std::string& str );

        inline StringBuilder& operator<<( const char* str );

        template <size_t N>
        NFX_STRINGBUILDER_FORCE_INLINE StringBuilder& operator<<( const char ( &str )[N] );

        inline StringBuilder& operator<<( char c );

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

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

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

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

        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 );
 
        //----------------------------------------------
        // String conversion
        //----------------------------------------------

        [[nodiscard]] inline std::string toString() const&;

        [[nodiscard]] std::string toString() &&;

        [[nodiscard]] inline std::string_view toStringView() const noexcept;
 
        //----------------------------------------------
        // STL support
        //----------------------------------------------

        inline void push_back( char c );
 
        //----------------------------------------------
        // Iterator interface
        //----------------------------------------------

        using value_type = char;

        using Iterator = char*;

        using ConstIterator = const char*;

        using iterator = Iterator;

        using const_iterator = ConstIterator;

        [[nodiscard]] inline Iterator begin() noexcept;

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

        [[nodiscard]] inline Iterator end() noexcept;

        [[nodiscard]] inline ConstIterator end() const noexcept;
 
    private:
        //----------------------------------------------
        // Private members
        //----------------------------------------------

        static constexpr size_t STACK_BUFFER_SIZE = 256;

        static constexpr size_t GROWTH_THRESHOLD = 8192;
        static constexpr double AGGRESSIVE_GROWTH_FACTOR = 2.0;
        static constexpr double STANDARD_GROWTH_FACTOR = 1.5;

        alignas( 32 ) char m_stackBuffer[STACK_BUFFER_SIZE];

        std::unique_ptr<char[]> m_heapBuffer;

        char* m_buffer;

        size_t m_size;

        size_t m_capacity;

        bool m_onHeap;
 
        //----------------------------------------------
        // Private methods
        //----------------------------------------------

        void ensureCapacity( size_t neededCapacity );
    };
} // namespace nfx::string
 
#include "nfx/detail/string/StringBuilder.inl"