ALib.Strings.Vector.H

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of the \aliblong.
///
/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
/// Published under \ref mainpage_license "Boost Software License".
//==================================================================================================
#ifndef H_ALIB_STRINGS_VECTOR
#define H_ALIB_STRINGS_VECTOR
#pragma once
#ifndef INL_ALIB
#   include "alib/alib.inl"
#endif
 
#if ALIB_STRINGS
#include <vector>
#include "ALib.Lang.H"
#include "ALib.Strings.H"
#include "ALib.Monomem.H"
 
namespace alib { namespace strings::util {
 
//==================================================================================================
/// This is a simple type that publicly inherits container type <c>std::vector</c> to store a
/// list of \alib strings, using an \alib {lang;Allocator}.
///
/// The (current) design of this class could be named "open" or "weak". This is due to the fact
/// that
/// a) The interface of the \c std::vector is public by inheritance, and
/// b) Only a few additional interface methods have been added.
///
/// As a consequence, it is up to the user of the type to care about proper allocation and
/// deallocation of string data: If a string is added using method #Add, its content is copied
/// to memory allocated with the allocator provided with construction. However, any other string may
/// be added by using the interface of the \c std::vector.
///
/// The typical use case is with class \alib{monomem;TMonoAllocator} or
/// \alib{monomem;TLocalAllocator} provided with module \alib_monomem:
/// - Create a Mono- or LocalAllocator
/// - Create a \alib{StringVectorMA}, passing the allocator.
/// - Gather some string data (copied or otherwise referenced).
/// - Pass it over to a function or otherwise use the vector.
/// - Destruct the objects.
///
/// \attention
///   With other use cases, especially when using type \alib{StringVectorPA} in combination with
///   class \alib{monomem;TPoolAllocator;PoolAllocator}, it has to be well thought how this type
///   is used in respect to the need of freeing memory, especially when strings got allocated with
///   method #Add.
///
/// @tparam TAllocator The allocator type, as prototyped with \alib{lang;Allocator}.
//==================================================================================================
template<typename TChar, typename TAllocator>
class TStringVector  : public std::vector<TString<TChar>,
                                          lang::StdContainerAllocator<TString<TChar>, TAllocator>>
{
  public:
    /// The allocator type that \p{TAllocator} specifies.
    using AllocatorType = TAllocator;
 
  protected:
    /// The vector type that \p{TAllocator} specifies.
    using vectorBase    = std::vector<TString<TChar>,
                                      lang::StdContainerAllocator<TString<TChar>, TAllocator>>;
 
  public:
 
    /// Constructor.
    /// @param pAllocator The allocator to use.
    TStringVector(AllocatorType& pAllocator)
    : vectorBase(pAllocator)                                                                      {}
 
    /// Destructor.
    ~TStringVector()                                                                      = default;
 
    /// Returns the allocator provided with construction. If this was \e nulled, then this method
    /// can be used to set an external (or new) allocator using the assignment operator.
    /// Has to be set before the first insertion of data.
    ///
    /// @return  A reference to the internal allocator.
    AllocatorType&    GetAllocator()                                                        noexcept
    { return vectorBase::get_allocator().GetAllocator(); }
 
    /// Returns the size of this vector as \alib{integer}.
    /// @return The number of strings stored.
     integer Size()                                                                   const noexcept
     { return integer(vectorBase::size()); }
 
    /// Adds a string to the end of the list of strings.
    /// @param src Source string to be copied.
    /// @return The index of the created string in this vector.
    integer Add(const strings::TString<TChar>& src )
    {
        vectorBase::emplace_back( String( GetAllocator(), src ) );
        return integer(vectorBase::size()) - 1;
    }
 
    /// Receives the string at a valid \p{idx}. If the index is out of bounds, a nulled string
    /// is returned.
    /// @param idx The index to try.
    /// @return The string stored at \p{idx}, if available.
    String TryGet(integer idx )
    {
        if (idx >= 0 && idx < Size())
            return vectorBase::at(size_t(idx));
 
        return NULL_STRING;
    }
 
}; // class TStringVector
 
} // namespace alib[::strings::util]
 
using  StringVector= strings::util::TStringVector<character, lang::HeapAllocator>; ///< Type alias in namespace \b alib.
using NStringVector= strings::util::TStringVector<nchar    , lang::HeapAllocator>; ///< Type alias in namespace \b alib.
using WStringVector= strings::util::TStringVector<wchar    , lang::HeapAllocator>; ///< Type alias in namespace \b alib.
 
#if ALIB_MONOMEM
  using   StringVectorMA= strings::util::TStringVector<character,  MonoAllocator>; ///< Type alias in namespace \b alib.
  using  NStringVectorMA= strings::util::TStringVector<nchar    ,  MonoAllocator>; ///< Type alias in namespace \b alib.
  using  WStringVectorMA= strings::util::TStringVector<wchar    ,  MonoAllocator>; ///< Type alias in namespace \b alib.
  using   StringVectorPA= strings::util::TStringVector<character,  PoolAllocator>; ///< Type alias in namespace \b alib.
  using  NStringVectorPA= strings::util::TStringVector<nchar    ,  PoolAllocator>; ///< Type alias in namespace \b alib.
  using  WStringVectorPA= strings::util::TStringVector<wchar    ,  PoolAllocator>; ///< Type alias in namespace \b alib.
#endif
 
} // namespace [alib]
 
#endif // ALIB_STRINGS
#endif // H_ALIB_STRINGS_VECTOR