localstring.hpp

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of module \alib_strings of the \aliblong.
///
/// Copyright 2013-2026 A-Worx GmbH, Germany.
/// Published under #"mainpage_license".
//==================================================================================================
ALIB_EXPORT namespace alib { namespace strings {
 
//==================================================================================================
/// This type specializes class #"%AString" by adding a character array member of templated size
/// which is used as the "external" string buffer. The single motivation for the use of this
/// class is performance optimization.
///
/// Assembled character strings often have a rather short lifetime and are disposed quickly
/// after their usage. If the maximum length of the assembled string is known, such strings
/// may be created as local values of this type, with that maximum length given as template
/// parameter \p{TCapacity}. With that, the allocation and deallocation of heap memory
/// (or whatever is used with the provided allocator) for the string is omitted and allocation
/// and destruction of the local string is performed in constant time O(1).
///
/// But even if an instance of this class is allocated (instead of being a local variable on the
/// stack), in common cases, still a performance improvement applies. This is due to the fact that
/// besides the class object itself, no second memory allocation for the string buffer is performed.
///
/// If during the use of an instance of this class the buffer's fixed \p{TCapacity} is exceeded,
/// a new buffer is allocated from the given allocator, just as it is always done with growing
/// strings managed in #"%AString" objects. This means, the use of this class is safe and no
/// restrictions apply.
/// Of course, if possible, for performance-critical code sections, the predefined size
/// \p{TCapacity} should be chosen large enough to allow the internal buffer to survive
/// the use.<br>
/// With debug-builds of \alib, parent class #"AString" optionally (and by default)
/// #"alib_mod_assert;raises a warning" if an external buffer is replaced by a
/// new (heap) allocation. (Note that from an #"%AString" perspective, this class's internal
/// field #"%.buffer" is an external character array).
/// With use cases that do not allow foreseeing a maximum buffer size, the warning has to be
/// disabled by invoking #"TAString::DbgDisableBufferReplacementWarning".
///
/// For more information on warnings, see #"TAString::SetBuffer(integer)".
///
/// With the provision of an assignment operator, the explicit restriction of parent class to
/// #"alib_ns_strings_astring_copymove;not allow assignments" is lifted with this type.
///
/// \note
///   For commonly used sizes and character types, some convenient typedefs exists in namespace
///   alib, which use #"HeapAllocator".
///   These type definitions are:
///   - #"String8", #"String16", #"String32" ... #"String1K", #"String2K", #"String4K",
///   - #"NString8", #"NString16", #"NString32" ... #"NString1K", #"NString2K", #"NString4K", and
///   - #"WString8", #"WString16", #"WString32" ... #"WString1K", #"WString2K", #"WString4K".
///
/// @tparam TChar The #"alib_characters_chars;character type" of this string.
///   Alias names for specializations of this class are provided in namespace #"alib" with type
///   definitions #"%LocalString",
///   #"%NLocalString", #"%WLocalString",
///   #"%XLocalString", #"%ComplementLocalString" and
///   #"%StrangeLocalString".
/// @tparam TCapacity  The capacity of the string buffer allocated locally "inside" the class.
/// @tparam TAllocator The allocator type to use. Defaults to #"HeapAllocator".
//==================================================================================================
template <typename TChar, integer TCapacity, typename TAllocator= lang::HeapAllocator>
class TLocalString : public TAString<TChar, TAllocator> {
  //################################################################################################
  //  protected fields
  //################################################################################################
  protected:
    /// The base AString-type.
    using base=   TAString<TChar, TAllocator>;
 
    /// The base String-type.
    using sBase=  TString<TChar>;
 
    /// The internal buffer with size specified by the template parameter \p{TCapacity}.
    /// Passed as an external buffer to parent class #"%AString".
    TChar         localBuffer[TCapacity];
 
  //################################################################################################
  //  Constructors/Destructor
  //################################################################################################
  public:
    /// Constructs an empty #"%LocalString". Inherited field #"TString::buffer"
    /// will be set as an the external buffer of parent #"%AString".
    /// Unlike all other \alib string classes, objects of this type are not \e nulled
    /// after default construction.
    /// @param pAllocator      The allocator to use.
    constexpr
    TLocalString(TAllocator& pAllocator)
    : base( pAllocator, localBuffer, TCapacity )
    , localBuffer {}                                                                              {}
 
    /// Constructs an empty #"%LocalString". Inherited field #"TString::buffer"
    /// will be set as an the external buffer of parent #"%AString".
    /// Unlike all other \alib string classes, objects of this type are not \e nulled
    /// after default construction.
    constexpr
    TLocalString()
    : base( localBuffer, TCapacity )
    , localBuffer {}                                                                              {}
 
    /// Copy constructor. Copies the string data of parameter \p{copy} to this instance
    /// @param copy The object to copy the contents from.
    TLocalString(const TLocalString& copy)
    : base( localBuffer, TCapacity )
    {
        ALIB_DBG( base::dbgWarnWhenExternalBufferIsReplaced= copy.dbgWarnWhenExternalBufferIsReplaced; )
        base::Append( copy.Buffer(), copy.Length() );
    }
 
    /// Move constructor.
    /// See #"alib_ns_strings_astring_copymove;Copy/Move Constructor and Assignment"
    /// for details.
    /// @param move The object to move.
    TLocalString(TLocalString&& move)                                                   noexcept
    : base( localBuffer, TCapacity ) {
        // given move object has external buffer: we have to copy
        if ( !move.HasInternalBuffer() ) {
            ALIB_DBG( base::dbgWarnWhenExternalBufferIsReplaced= move.dbgWarnWhenExternalBufferIsReplaced; )
            base::Append( move );
            return;
        }
 
        // copy values
        sBase::buffer =  move.buffer;
        sBase::length =  move.length;
        base::capacity=  move.capacity;
 
        // clean moved object (buffer does not need to be nulled as AString destructor
        // checks capacity > 0  )
        move.capacity= 0;
 
        // in debug mode, more copying and more destructor prevention is needed
        #if ALIB_DEBUG
            base::dbgWarnWhenExternalBufferIsReplaced= move.dbgWarnWhenExternalBufferIsReplaced;
            #if ALIB_DEBUG_STRINGS
                base::debugLastAllocRequest  = move.debugLastAllocRequest;
                move.buffer                 = nullptr;
                move.length                 = 0;
            #endif
        #endif
    }
 
    /// Copy assign operator.
    /// Copies the contents of the given object \p{copy}.
    ///
    /// @param  copy  The object to copy the contents from.
    /// @return \c *this to allow concatenated calls.
    TLocalString& operator= (const TLocalString&  copy) {
        if ( copy.IsNull()) {
            base::SetNull();
            return *this;
        }
        base::Reset();
        return static_cast<TLocalString&>( base::template Append<NC>( copy.Buffer(), copy.Length() ) );
    }
 
    /// Move assign operator.
    /// Copies the contents of the given object \p{copy}.
    ///
    /// @param  move  The object to move the contents from.
    /// @return \c *this to allow concatenated calls.
    TLocalString& operator= (TLocalString&&  move) {
        if( move.IsNull() ) {
            ALIB_DBG( base::dbgWarnWhenExternalBufferIsReplaced= move.dbgWarnWhenExternalBufferIsReplaced; )
            base::SetNull();
            return *this;
        }
 
        // copy if move has its local buffer or this has lost its local buffer
        if ( !move.HasInternalBuffer() || base::HasInternalBuffer() ) {
            base::Reset( move );
            return *this;
        }
 
        // copy other buffer from moved object
        sBase::buffer =  move.buffer;
        sBase::length =  move.length;
        base::capacity=  move.capacity;
 
        // clean moved object (buffer does not need to be nulled)
        move.capacity= 0;
 
        // in debug mode, more copying and more destructor prevention is needed
        #if ALIB_DEBUG
            base::dbgWarnWhenExternalBufferIsReplaced= move.dbgWarnWhenExternalBufferIsReplaced;
            #if ALIB_DEBUG_STRINGS
                base::debugLastAllocRequest  = move.debugLastAllocRequest;
                move.buffer                 = nullptr;
                move.length                 = 0;
            #endif
        #endif
        return *this;
    }
 
    /// Constructs this instance and invokes parent's method #"%Append(const TAppendable&)" to
    /// create a string representation of the given "appendable" object \p{src}.
    ///
    /// \see
    ///   Manual chapter #"alib_strings_assembly_ttostring" for more information
    ///   about which types are supported and how external, user-defined types can be made
    ///   compatible to this implicit constructor.
    ///
    /// @tparam TAppendable  The type of parameter \p{src} that has a specialization of
    ///                      functor #"AppendableTraits".
    /// @param src  The source to take the buffer and length from of template type T.
    template <typename TAppendable>
    TLocalString (const  TAppendable& src )
    : base( localBuffer, TCapacity )                                        { base::Append( src ); }
 
 
    /// Assign operator.
    /// Invokes inherited method #"Reset(const TAppendable&)".
    ///
    /// @tparam TAppendable The type of parameter \p{source}.
    /// @param  src         The source of type \p{TAppendable} to append.
    ///
    /// @return \c *this to allow concatenated calls.
    template <typename TAppendable>
    TLocalString& operator= (const TAppendable& src )          { base::Reset( src ); return *this; }
 
}; // class TLocalString
 
//##################################################################################################
// Specializations of ArrayTraits for this class String
//##################################################################################################
} namespace characters {
#if !DOXYGEN
template<typename TChar, integer TCapacity, typename TAllocator>
struct  ArrayTraits<strings::TLocalString<TChar,TCapacity,TAllocator>, TChar>
{
    using T= strings::TLocalString<TChar,TCapacity,TAllocator>;
    static constexpr Policy       Access                                    = Policy::Implicit;
    static constexpr Policy       Construction                              = Policy::NONE;
    static constexpr const TChar* Buffer(const T& src)                      { return src.Buffer(); }
    static constexpr integer      Length(const T& src)                      { return src.Length(); }
};
 
template<typename TChar, integer TCapacity, typename TAllocator>
struct  ZTArrayTraits<strings::TLocalString<TChar,TCapacity,TAllocator>, TChar>
{
    using T= strings::TLocalString<TChar,TCapacity,TAllocator>;
    static constexpr Policy       Access                                 = Policy::Implicit;
    static constexpr Policy       Construction                           = Policy::NONE;
    static constexpr const TChar* Buffer(const T& src)                   { return src.Terminate(); }
    static constexpr integer      Length(const T& src)                      { return src.Length(); }
};
#endif // !DOXYGEN
 
 
} namespace strings {
 
#if ALIB_DEBUG
//==================================================================================================
/// This simple specialization of #"str TLocalString" disables the warning about
/// replacements of the internal buffer in debug-compilations. This may be used in situations,
/// where it is not possible to disable this warning after construction, for example, if a local
/// string is <em>emplaced</em> in a container and extensions of it's local capacity are well
/// accepted (for a minority of the emplaced strings).
///
/// In release compilations, this type does not exist, but is replaced by a simple using
/// statement.
///
/// @tparam TChar      The character type.
/// @tparam TCapacity  The capacity of local, embedded string buffer.
/// @tparam TAllocator The allocator to use.
//==================================================================================================
template <typename TChar, integer TCapacity, typename TAllocator>
struct  TLocalStringNoWarning : public TLocalString<TChar,TCapacity,TAllocator> {
    /// Default constructor.
    constexpr
    TLocalStringNoWarning()
    : TLocalString<TChar,TCapacity>()
    { TAString<TChar,lang::HeapAllocator>::dbgWarnWhenExternalBufferIsReplaced= false; }
 
    /// Constructor taking a string to copy.
    /// @param src  The string to copy into this object.
    TLocalStringNoWarning( const String& src )
    : TLocalString<TChar,TCapacity>()
    {
        TAString<TChar,lang::HeapAllocator>::dbgWarnWhenExternalBufferIsReplaced= false;
        TAString<TChar,lang::HeapAllocator>::Append( src.Buffer(), src.Length() );
    }
}; // TLocalStringNoWarning
#else
    template <typename TChar, integer TCapacity, typename TAllocator>
    using   TLocalStringNoWarning = TLocalString<TChar, TCapacity, TAllocator>;
#endif
 
}
 
/// Type alias in namespace #"%alib".
template<integer TCapacity>
using LocalString       =     strings::TLocalString<character     , TCapacity, lang::HeapAllocator>;
 
/// Type alias in namespace #"%alib".
template<integer TCapacity>
using ComplementLocalString=  strings::TLocalString<complementChar, TCapacity, lang::HeapAllocator>;
 
/// Type alias in namespace #"%alib".
template<integer TCapacity>
using StrangeLocalString=     strings::TLocalString<strangeChar   , TCapacity, lang::HeapAllocator>;
 
/// Type alias in namespace #"%alib".
template<integer TCapacity>
using NLocalString      =     strings::TLocalString <nchar        , TCapacity, lang::HeapAllocator>;
 
/// Type alias in namespace #"%alib".
template<integer TCapacity>
using WLocalString      =     strings::TLocalString <wchar        , TCapacity, lang::HeapAllocator>;
 
/// Type alias in namespace #"%alib".
template<integer TCapacity>
using XLocalString      =     strings::TLocalString <xchar        , TCapacity, lang::HeapAllocator>;
 
/// Type alias name for #"TLocalString;TLocalString<character,8>".
using String8  =  LocalString<   8>;
 
/// Type alias name for #"TLocalString;TLocalString<character,16>".
using String16 =  LocalString<  16>;
 
/// Type alias name for #"TLocalString;TLocalString<character,32>".
using String32 =  LocalString<  32>;
 
/// Type alias name for #"TLocalString;TLocalString<character,64>".
using String64 =  LocalString<  64>;
 
/// Type alias name for #"TLocalString;TLocalString<character,128>".
using String128=  LocalString< 128>;
 
/// Type alias name for #"TLocalString;TLocalString<character,256>".
using String256=  LocalString< 256>;
 
/// Type alias name for #"TLocalString;TLocalString<character,512>".
using String512=  LocalString< 512>;
 
/// Type alias name for #"TLocalString;TLocalString<character,1024>".
using String1K =  LocalString<1024>;
 
/// Type alias name for #"TLocalString;TLocalString<character,2048>".
using String2K =  LocalString<2048>;
 
/// Type alias name for #"TLocalString;TLocalString<character,4096>".
using String4K =  LocalString<4096>;
 
/// Type alias name for #"TLocalString;TLocalString<character,8192>".
using String8K =  LocalString<8192>;
 
/// Type alias name for #"TLocalString;TLocalString<nchar,8>".
using NString8 =  NLocalString<  8>;
 
/// Type alias name for #"TLocalString;TLocalString<nchar,16>".
using NString16 =  NLocalString<  16>;
 
/// Type alias name for #"TLocalString;TLocalString<nchar,32>".
using NString32 =  NLocalString<  32>;
 
/// Type alias name for #"TLocalString;TLocalString<nchar,64>".
using NString64 =  NLocalString<  64>;
 
/// Type alias name for #"TLocalString;TLocalString<nchar,128>".
using NString128=  NLocalString< 128>;
 
/// Type alias name for #"TLocalString;TLocalString<nchar,256>".
using NString256=  NLocalString< 256>;
 
/// Type alias name for #"TLocalString;TLocalString<nchar,512>".
using NString512=  NLocalString< 512>;
 
/// Type alias name for #"TLocalString;TLocalString<nchar,1024>".
using NString1K =  NLocalString<1024>;
 
/// Type alias name for #"TLocalString;TLocalString<nchar,2048>".
using NString2K =  NLocalString<2048>;
 
/// Type alias name for #"TLocalString;TLocalString<nchar,8192>".
using NString4K =  NLocalString<4096>;
 
/// Type alias name for #"TLocalString;TLocalString<nchar,4096>".
using NString8K =  NLocalString<8192>;
 
/// Type alias name for #"TLocalString;TLocalString<wchar,8>".
using WString8  =  WLocalString<   8>;
 
/// Type alias name for #"TLocalString;TLocalString<wchar,16>".
using WString16 =  WLocalString<  16>;
 
/// Type alias name for #"TLocalString;TLocalString<wchar,32>".
using WString32 =  WLocalString<  32>;
 
/// Type alias name for #"TLocalString;TLocalString<wchar,64>".
using WString64 =  WLocalString<  64>;
 
/// Type alias name for #"TLocalString;TLocalString<wchar,128>".
using WString128=  WLocalString< 128>;
 
/// Type alias name for #"TLocalString;TLocalString<wchar,256>".
using WString256=  WLocalString< 256>;
 
/// Type alias name for #"TLocalString;TLocalString<wchar,512>".
using WString512=  WLocalString< 512>;
 
/// Type alias name for #"TLocalString;TLocalString<wchar,1024>".
using WString1K =  WLocalString<1024>;
 
/// Type alias name for #"TLocalString;TLocalString<wchar,2048>".
using WString2K =  WLocalString<2048>;
 
/// Type alias name for #"TLocalString;TLocalString<wchar,4096>".
using WString4K =  WLocalString<4096>;
 
/// Type alias name for #"TLocalString;TLocalString<wchar,8192>".
using WString8K =  WLocalString<8192>;
} // namespace [alib::strings]