PMDK C++ bindings  1.8.2
This is the C++ bindings documentation for PMDK's libpmemobj.
Public Member Functions | Private Member Functions | Private Attributes | List of all members
pmem::obj::basic_string< CharT, Traits > Class Template Reference

pmem::obj::string - persistent container with std::basic_string compatible interface. More...

#include <libpmemobj++/container/basic_string.hpp>

Public Member Functions

 basic_string ()
 Default constructor. More...
 
 basic_string (size_type count, CharT ch)
 Construct the container with count copies of elements with value ch. More...
 
 basic_string (const basic_string &other, size_type pos, size_type count=npos)
 Construct the string with a substring [pos, min(pos+count, other.size()) of other. More...
 
 basic_string (const std::basic_string< CharT > &other, size_type pos, size_type count=npos)
 Construct the string with a substring [pos, min(pos+count, other.size()) of std::basic_string<CharT> other. More...
 
 basic_string (const CharT *s, size_type count)
 Construct the string with the first count elements of C-style string s. More...
 
 basic_string (const CharT *s)
 Construct the string with the contents of s. More...
 
template<typename InputIt , typename Enable = typename std::enable_if< pmem::detail::is_input_iterator<InputIt>::value>::type>
 basic_string (InputIt first, InputIt last)
 Construct the string with the contents of the range [first, last). More...
 
 basic_string (const basic_string &other)
 Copy constructor. More...
 
 basic_string (const std::basic_string< CharT > &other)
 Copy constructor. More...
 
 basic_string (basic_string &&other)
 Move constructor. More...
 
 basic_string (std::initializer_list< CharT > ilist)
 Construct the container with the contents of the initializer list init. More...
 
 ~basic_string ()
 Destructor. More...
 
basic_stringoperator= (const basic_string &other)
 Copy assignment operator. More...
 
basic_stringoperator= (const std::basic_string< CharT > &other)
 Copy assignment operator. More...
 
basic_stringoperator= (basic_string &&other)
 Move assignment operator. More...
 
basic_stringoperator= (const CharT *s)
 Replace the contents with copy of C-style string s transactionally. More...
 
basic_stringoperator= (CharT ch)
 Replace the contents with character ch transactionally. More...
 
basic_stringoperator= (std::initializer_list< CharT > ilist)
 Replace the contents with those of the initializer list ilist transactionally. More...
 
basic_stringassign (size_type count, CharT ch)
 Replace the contents with count copies of character ch transactionally. More...
 
basic_stringassign (const basic_string &other)
 Replace the string with the copy of the contents of other transactionally. More...
 
basic_stringassign (const std::basic_string< CharT > &other)
 Replace the string with the copy of the contents of std::basic_string<CharT> other. More...
 
basic_stringassign (const basic_string &other, size_type pos, size_type count=npos)
 Replace the contents with a substring [pos, std::min(pos+count, other.size()) of other transactionally. More...
 
basic_stringassign (const std::basic_string< CharT > &other, size_type pos, size_type count=npos)
 Replace the contents with a substring [pos, std::min(pos+count, other.size()) of std::basic_string<CharT> other transactionally. More...
 
basic_stringassign (const CharT *s, size_type count)
 Replace the contents with the first count elements of C-style string s transactionally. More...
 
basic_stringassign (const CharT *s)
 Replace the contents with copy of C-style string s transactionally. More...
 
basic_stringassign (basic_string &&other)
 Replace the string with the contents of other using move semantics transactionally. More...
 
basic_stringassign (std::initializer_list< CharT > ilist)
 replace_content the contents with those of the initializer list ilist transactionally. More...
 
reference at (size_type n)
 Access element at specific index with bounds checking and snapshot it if there is an active transaction. More...
 
const_reference at (size_type n) const
 Access element at specific index with bounds checking. More...
 
const_reference const_at (size_type n) const
 Access element at specific index with bounds checking. More...
 
reference operator[] (size_type n)
 Access element at specific index and snapshot it if there is an active transaction. More...
 
const_reference operator[] (size_type n) const
 Access element at specific index. More...
 
CharT & front ()
 Access first element and snapshot it if there is an active transaction. More...
 
const CharT & front () const
 Access first element. More...
 
const CharT & cfront () const
 Access first element. More...
 
CharT & back ()
 Access last element and snapshot it if there is an active transaction. More...
 
const CharT & back () const
 Access last element. More...
 
const CharT & cback () const
 Access last element. More...
 
CharT * data ()
 
const CharT * data () const noexcept
 
const CharT * cdata () const noexcept
 
const CharT * c_str () const noexcept
 
iterator begin ()
 Return an iterator to the beginning. More...
 
const_iterator begin () const noexcept
 Return const iterator to the beginning. More...
 
const_iterator cbegin () const noexcept
 Return const iterator to the beginning. More...
 
iterator end ()
 Return an iterator to past the end. More...
 
const_iterator end () const noexcept
 Return const iterator to past the end. More...
 
const_iterator cend () const noexcept
 Return const iterator to past the end. More...
 
reverse_iterator rbegin ()
 Return a reverse iterator to the beginning. More...
 
const_reverse_iterator rbegin () const noexcept
 Return a const reverse iterator to the beginning. More...
 
const_reverse_iterator crbegin () const noexcept
 Return a const reverse iterator to the beginning. More...
 
reverse_iterator rend ()
 Return a reverse iterator to the end. More...
 
const_reverse_iterator rend () const noexcept
 Return a const reverse iterator to the end. More...
 
const_reverse_iterator crend () const noexcept
 Return a const reverse iterator to the end. More...
 
bool empty () const noexcept
 
size_type size () const noexcept
 
size_type length () const noexcept
 
size_type max_size () const noexcept
 
size_type capacity () const noexcept
 
void resize (size_type count, CharT ch)
 Resize the string to count characters transactionally. More...
 
void resize (size_type n)
 Resize the string to count characters transactionally. More...
 
void reserve (size_type new_cap=0)
 Increase the capacity of the string to new_cap transactionally. More...
 
void shrink_to_fit ()
 Remove unused capacity transactionally. More...
 
void clear ()
 Remove all characters from the string transactionally. More...
 
basic_stringerase (size_type index=0, size_type count=npos)
 Remove characters from string starting at index transactionally. More...
 
iterator erase (const_iterator pos)
 Remove character from string at pos position transactionally. More...
 
iterator erase (const_iterator first, const_iterator last)
 Remove characters from string at [first, last) range transactionally. More...
 
template<typename T , typename Enable = typename std::enable_if< !std::is_convertible<T, size_type>::value>::type>
iterator erase (T param)
 Participate in overload resolution only if T is not convertible to size_type. More...
 
void pop_back ()
 Remove the last character from the string transactionally. More...
 
basic_stringappend (size_type count, CharT ch)
 Append count copies of character ch to the string transactionally. More...
 
basic_stringappend (const basic_string &str)
 Append string str transactionally. More...
 
basic_stringappend (const basic_string &str, size_type pos, size_type count=npos)
 Append substring [pos, pos + count) of str string transactionally. More...
 
basic_stringappend (const CharT *s, size_type count)
 Append characters in the range [s, s + count) transactionally. More...
 
basic_stringappend (const CharT *s)
 Append C-style string transactionally. More...
 
basic_stringappend (std::initializer_list< CharT > ilist)
 Append characters from the ilist initializer list transactionally. More...
 
void push_back (CharT ch)
 Append character ch at the end of the string transactionally. More...
 
basic_stringoperator+= (const basic_string &str)
 Append string str transactionally. More...
 
basic_stringoperator+= (const CharT *s)
 Append C-style string transactionally. More...
 
basic_stringoperator+= (CharT c)
 Append character ch at the end of the string transactionally. More...
 
basic_stringoperator+= (std::initializer_list< CharT > ilist)
 Append characters from the ilist initializer list transactionally. More...
 
basic_stringinsert (size_type index, size_type count, CharT ch)
 Insert count copies of ch character at index transactionally. More...
 
basic_stringinsert (size_type index, const CharT *s)
 Insert null-terminated C-style string pointed by s of the length determined by the first null character at index transactionally. More...
 
basic_stringinsert (size_type index, const CharT *s, size_type count)
 Insert characters in the range [s, s+ count) at index transactionally. More...
 
basic_stringinsert (size_type index, const basic_string &str)
 Insert str string at index transactionally. More...
 
basic_stringinsert (size_type index1, const basic_string &str, size_type index2, size_type count=npos)
 Insert a str.substr(index2, count) string at index1 transactionally. More...
 
iterator insert (const_iterator pos, CharT ch)
 Insert character ch before the character pointed by pos transactionally. More...
 
iterator insert (const_iterator pos, size_type count, CharT ch)
 Insert count copies of character ch before the character pointed by pos transactionally. More...
 
template<typename InputIt , typename Enable = typename pmem::detail::is_input_iterator< InputIt>::type>
iterator insert (const_iterator pos, InputIt first, InputIt last)
 Insert characters from [first, last) range before the character pointed by pos transactionally. More...
 
iterator insert (const_iterator pos, std::initializer_list< CharT > ilist)
 Insert characters from initializer list ilist before the character pointed by pos transactionally. More...
 
template<typename T , typename Enable = typename std::enable_if< !std::is_convertible<T, size_type>::value>::type>
iterator insert (T param, size_type count, CharT ch)
 Participate in overload resolution only if T is not convertible to size_type. More...
 
basic_stringreplace (size_type index, size_type count, const basic_string &str)
 Replace range [index, index + count) with the content of str string transactionally. More...
 
basic_stringreplace (const_iterator first, const_iterator last, const basic_string &str)
 Replace range [first, last) with the content of str string transactionally. More...
 
basic_stringreplace (size_type index, size_type count, const basic_string &str, size_type index2, size_type count2=npos)
 Replace range [index, index + count) with the substring [index2, index2 + count2) of str string transactionally. More...
 
basic_stringreplace (const_iterator first, const_iterator last, const CharT *s, size_type count2)
 Replace range [first, last) with the characters in [s, s + count2) range transactionally. More...
 
basic_stringreplace (const_iterator first, const_iterator last, const CharT *s)
 Replace range [first, last) with the characters in [s, s + traits::length(s)) range transactionally. More...
 
basic_stringreplace (size_type index, size_type count, size_type count2, CharT ch)
 Replace range [index, index + count) with count2 copies of ch character transactionally. More...
 
basic_stringreplace (const_iterator first, const_iterator last, size_type count2, CharT ch)
 Replace range [first, last) with count2 copies of ch character transactionally. More...
 
basic_stringreplace (size_type index, size_type count, const CharT *s, size_type count2)
 Replace range [index, index + count) with the characters in [s, s + count2) range transactionally. More...
 
basic_stringreplace (size_type index, size_type count, const CharT *s)
 Replace range [index, index + count) with the characters in [s, s + traits::length(s)) range transactionally. More...
 
basic_stringreplace (const_iterator first, const_iterator last, std::initializer_list< CharT > ilist)
 Replace range [first, last) with characters in initializer list ilist transactionally. More...
 
size_type copy (CharT *s, size_type count, size_type index=0) const
 Copy [index, index + count) substring of *this to C-style string. More...
 
int compare (const basic_string &other) const
 Compares this string to other. More...
 
int compare (const std::basic_string< CharT > &other) const
 Compares this string to std::basic_string<CharT> other. More...
 
int compare (size_type pos, size_type count, const basic_string &other) const
 Compares [pos, pos + count) substring of this to other. More...
 
int compare (size_type pos, size_type count, const std::basic_string< CharT > &other) const
 Compares [pos, pos + count) substring of this to std::basic_string<CharT> other. More...
 
int compare (size_type pos1, size_type count1, const basic_string &other, size_type pos2, size_type count2=npos) const
 Compares [pos1, pos1 + count1) substring of this to [pos2, pos2 + count2) substring of other. More...
 
int compare (size_type pos1, size_type count1, const std::basic_string< CharT > &other, size_type pos2, size_type count2=npos) const
 Compares [pos1, pos1 + count1) substring of this to [pos2, pos2 + count2) substring of std::basic_string<CharT> other. More...
 
int compare (const CharT *s) const
 Compares this string to s. More...
 
int compare (size_type pos, size_type count, const CharT *s) const
 Compares [pos, pos + count) substring of this to s. More...
 
int compare (size_type pos, size_type count1, const CharT *s, size_type count2) const
 Compares [pos, pos + count1) substring of this to [s, s + count2) substring of s. More...
 
template<typename InputIt , typename Enable >
basic_string< CharT, Traits > & assign (InputIt first, InputIt last)
 Replace the contents with copies of elements in the range [first, last) transactionally. More...
 
template<typename InputIt , typename Enable >
basic_string< CharT, Traits > & append (InputIt first, InputIt last)
 Append characters in the range [first, last) transactionally. More...
 
template<typename InputIt , typename Enable >
basic_string< CharT, Traits > & replace (const_iterator first, const_iterator last, InputIt first2, InputIt last2)
 Replace range [first, last) with the characters in [first2, last2) range transactionally. More...
 
template<typename T , typename Enable >
basic_string< CharT, Traits > & erase (T param)
 Participate in overload resolution only if T is convertible to size_type. More...
 
template<typename T , typename Enable >
basic_string< CharT, Traits > & insert (T param, size_type count, CharT ch)
 Participate in overload resolution only if T is convertible to size_type. More...
 

Private Member Functions

template<typename InputIt , typename Enable = typename std::enable_if< pmem::detail::is_input_iterator<InputIt>::value>::type>
size_type get_size (InputIt first, InputIt last) const
 Overload of generic get_size method used to calculate size based on provided parameters. More...
 
size_type get_size (size_type count, value_type ch) const
 Overload of generic get_size method used to calculate size based on provided parameters. More...
 
size_type get_size (const basic_string &other) const
 Overload of generic get_size method used to calculate size based on provided parameters. More...
 
template<typename... Args>
pointer replace_content (Args &&... args)
 Generic function which replace_content current content based on provided parameters. More...
 
template<typename... Args>
pointer initialize (Args &&... args)
 Generic function which initializes memory based on provided parameters - forwards parameters to initialize function of either non_sso.data or sso.data. More...
 
void allocate (size_type capacity)
 Allocate storage for container of capacity bytes. More...
 
template<typename InputIt , typename Enable = typename std::enable_if< pmem::detail::is_input_iterator<InputIt>::value>::type>
pointer assign_sso_data (InputIt first, InputIt last)
 Initialize sso data. More...
 
pointer assign_sso_data (size_type count, value_type ch)
 Initialize sso data. More...
 
pointer assign_sso_data (basic_string &&other)
 Initialize sso data. More...
 
template<typename InputIt , typename Enable = typename std::enable_if< pmem::detail::is_input_iterator<InputIt>::value>::type>
pointer assign_large_data (InputIt first, InputIt last)
 Initialize non_sso.data - call constructor of non_sso.data. More...
 
pointer assign_large_data (size_type count, value_type ch)
 Initialize non_sso.data - call constructor of non_sso.data. More...
 
pointer assign_large_data (basic_string &&other)
 Initialize non_sso.data - call constructor of non_sso.data. More...
 
pool_base get_pool () const
 Return pool_base instance and assert that object is on pmem.
 
void check_pmem () const
 
void check_tx_stage_work () const
 
void check_pmem_tx () const
 
void add_sso_to_tx (size_type first, size_type num) const
 Snapshot sso data.
 
size_type get_sso_size () const
 Return size of sso string.
 
void enable_sso ()
 Enable sso string.
 
void disable_sso ()
 Disable sso string.
 
void set_sso_size (size_type new_size)
 Set size for sso.
 
void sso_to_large (size_t new_capacity)
 Resize sso string to large string. More...
 
void large_to_sso ()
 Resize large string to sso string of size() size. More...
 

Private Attributes

union {
}; 
 This union holds sso data inside of an array and non sso data inside a vector. More...
 

Detailed Description

template<typename CharT, typename Traits = std::char_traits<CharT>>
class pmem::obj::basic_string< CharT, Traits >

pmem::obj::string - persistent container with std::basic_string compatible interface.

The implementation is still missing some methods.

Constructor & Destructor Documentation

◆ basic_string() [1/11]

template<typename CharT , typename Traits >
pmem::obj::basic_string< CharT, Traits >::basic_string ( )

Default constructor.

Construct an empty container.

Precondition
must be called in transaction scope.
Exceptions
pmem::pool_errorif an object is not in persistent memory.
pmem::transaction_scope_errorif constructor wasn't called in transaction.

◆ basic_string() [2/11]

template<typename CharT, typename Traits >
pmem::obj::basic_string< CharT, Traits >::basic_string ( size_type  count,
CharT  ch 
)

Construct the container with count copies of elements with value ch.

Parameters
[in]countnumber of elements to construct.
[in]chvalue of all constructed elements.
Precondition
must be called in transaction scope.
Exceptions
pmem::pool_errorif an object is not in persistent memory.
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.
pmem::transaction_scope_errorif constructor wasn't called in transaction.

◆ basic_string() [3/11]

template<typename CharT, typename Traits >
pmem::obj::basic_string< CharT, Traits >::basic_string ( const basic_string< CharT, Traits > &  other,
size_type  pos,
size_type  count = npos 
)

Construct the string with a substring [pos, min(pos+count, other.size()) of other.

Parameters
[in]otherstring from which substring will be copied.
[in]posstart position of substring in other.
[in]countlength of substring.
Precondition
must be called in transaction scope.
Exceptions
std::out_of_rangeis pos > other.size()
pmem::pool_errorif an object is not in persistent memory.
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.
pmem::transaction_scope_errorif constructor wasn't called in transaction.

◆ basic_string() [4/11]

template<typename CharT, typename Traits >
pmem::obj::basic_string< CharT, Traits >::basic_string ( const std::basic_string< CharT > &  other,
size_type  pos,
size_type  count = npos 
)

Construct the string with a substring [pos, min(pos+count, other.size()) of std::basic_string<CharT> other.

Parameters
[in]otherstd::basic_string<CharT> from which substring will be copied.
[in]posstart position of substring in other.
[in]countlength of substring.
Precondition
must be called in transaction scope.
Exceptions
std::out_of_rangeis pos > other.size()
pmem::pool_errorif an object is not in persistent memory.
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.
pmem::transaction_scope_errorif constructor wasn't called in transaction.

◆ basic_string() [5/11]

template<typename CharT, typename Traits >
pmem::obj::basic_string< CharT, Traits >::basic_string ( const CharT *  s,
size_type  count 
)

Construct the string with the first count elements of C-style string s.

Parameters
[in]spointer to source string.
[in]countlength of the resulting string.
Precondition
must be called in transaction scope.
Exceptions
pmem::pool_errorif an object is not in persistent memory.
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.
pmem::transaction_scope_errorif constructor wasn't called in transaction.

◆ basic_string() [6/11]

template<typename CharT, typename Traits >
pmem::obj::basic_string< CharT, Traits >::basic_string ( const CharT *  s)

Construct the string with the contents of s.

Parameters
[in]spointer to source string.
Precondition
must be called in transaction scope.
Exceptions
pmem::pool_errorif an object is not in persistent memory.
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.
pmem::transaction_scope_errorif constructor wasn't called in transaction.

◆ basic_string() [7/11]

template<typename CharT , typename Traits >
template<typename InputIt , typename Enable >
pmem::obj::basic_string< CharT, Traits >::basic_string ( InputIt  first,
InputIt  last 
)

Construct the string with the contents of the range [first, last).

This constructor only participates in overload resolution if InputIt satisfies InputIterator.

Parameters
[in]firstiterator to beginning of the range.
[in]lastiterator to end of the range.
Precondition
must be called in transaction scope.
Exceptions
pmem::pool_errorif an object is not in persistent memory.
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.
pmem::transaction_scope_errorif constructor wasn't called in transaction.

◆ basic_string() [8/11]

template<typename CharT, typename Traits >
pmem::obj::basic_string< CharT, Traits >::basic_string ( const basic_string< CharT, Traits > &  other)

Copy constructor.

Construct the string with the copy of the contents of other.

Parameters
[in]otherreference to the string to be copied.
Precondition
must be called in transaction scope.
Exceptions
pmem::pool_errorif an object is not in persistent memory.
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.
pmem::transaction_scope_errorif constructor wasn't called in transaction.

◆ basic_string() [9/11]

template<typename CharT, typename Traits >
pmem::obj::basic_string< CharT, Traits >::basic_string ( const std::basic_string< CharT > &  other)

Copy constructor.

Construct the string with the copy of the contents of std::basic_string<CharT> other.

Parameters
[in]otherreference to the std::basic_string<CharT> to be copied.
Precondition
must be called in transaction scope.
Exceptions
pmem::pool_errorif an object is not in persistent memory.
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.
pmem::transaction_scope_errorif constructor wasn't called in transaction.

◆ basic_string() [10/11]

template<typename CharT, typename Traits >
pmem::obj::basic_string< CharT, Traits >::basic_string ( basic_string< CharT, Traits > &&  other)

Move constructor.

Construct the string with the contents of other using move semantics.

Parameters
[in]otherrvalue reference to the string to be moved from.
Precondition
must be called in transaction scope.
Exceptions
pmem::pool_errorif an object is not in persistent memory.
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.
pmem::transaction_scope_errorif constructor wasn't called in transaction.

◆ basic_string() [11/11]

template<typename CharT, typename Traits >
pmem::obj::basic_string< CharT, Traits >::basic_string ( std::initializer_list< CharT >  ilist)

Construct the container with the contents of the initializer list init.

Parameters
[in]ilistinitializer list with content to be constructed.
Precondition
must be called in transaction scope.
Exceptions
pmem::pool_errorif an object is not in persistent memory.
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.
pmem::transaction_scope_errorif constructor wasn't called in transaction.

◆ ~basic_string()

template<typename CharT , typename Traits >
pmem::obj::basic_string< CharT, Traits >::~basic_string ( )

Destructor.

XXX: implement free_data()

Member Function Documentation

◆ allocate()

template<typename CharT , typename Traits >
void pmem::obj::basic_string< CharT, Traits >::allocate ( size_type  capacity)
private

Allocate storage for container of capacity bytes.

Based on capacity determine if sso or large string is used.

Precondition
data must be uninitialized.
must be called in transaction scope.
Parameters
[in]capacitybytes to allocate.

◆ append() [1/7]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::append ( size_type  count,
CharT  ch 
)

Append count copies of character ch to the string transactionally.

Parameters
[in]countnumber of characters to append.
[in]chcharacter value to append.
Returns
*this
Postcondition
size() == size() + count
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ append() [2/7]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::append ( const basic_string< CharT, Traits > &  str)

Append string str transactionally.

Parameters
[in]strstring to append.
Returns
*this
Postcondition
size() == size() + str.size()
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ append() [3/7]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::append ( const basic_string< CharT, Traits > &  str,
size_type  pos,
size_type  count = npos 
)

Append substring [pos, pos + count) of str string transactionally.

Length of the string to append is determined as the smaller of count and str.size() - pos.

Parameters
[in]strstring to append.
[in]posindex of the first character to append.
[in]countcharacters to append.
Returns
*this
Precondition
pos <= str.size()
Postcondition
size() == size() + std::min(count, str.size() - pos).
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::out_of_rangeif pos > str.size().
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ append() [4/7]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::append ( const CharT *  s,
size_type  count 
)

Append characters in the range [s, s + count) transactionally.

Parameters
[in]spointer to C-style string to append.
[in]countcharacters to append.
Returns
*this
Postcondition
size() == size() + count.
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ append() [5/7]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::append ( const CharT *  s)

Append C-style string transactionally.

Length of the string is determined by the first null character.

Parameters
[in]spointer to C-style string to append.
Returns
*this
Postcondition
size() == size() + traits::length(s).
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ append() [6/7]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::append ( std::initializer_list< CharT >  ilist)

Append characters from the ilist initializer list transactionally.

Parameters
[in]ilistinitializer list with characters to append from
Returns
*this
Postcondition
size() == size() + std::distance(ilist.begin(), ilist.end())
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ append() [7/7]

template<typename CharT, typename Traits = std::char_traits<CharT>>
template<typename InputIt , typename Enable >
basic_string<CharT, Traits>& pmem::obj::basic_string< CharT, Traits >::append ( InputIt  first,
InputIt  last 
)

Append characters in the range [first, last) transactionally.

This overload participates in overload resolution only if InputIt qualifies as InputIterator.

Parameters
[in]firstbegin of the range of characters to append.
[in]lastend of the range of characters to append.
Returns
*this
Postcondition
size() == size() + std::distance(first, last)
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ assign() [1/10]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::assign ( size_type  count,
CharT  ch 
)

Replace the contents with count copies of character ch transactionally.

Parameters
[in]countnumber of characters.
[in]chcharacter.
Exceptions
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.

◆ assign() [2/10]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::assign ( const basic_string< CharT, Traits > &  other)

Replace the string with the copy of the contents of other transactionally.

Parameters
[in]otherreference to the string to be copied.
Exceptions
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.

◆ assign() [3/10]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::assign ( const std::basic_string< CharT > &  other)

Replace the string with the copy of the contents of std::basic_string<CharT> other.

Parameters
[in]otherreference to the std::basic_string<CharT> to be copied.
Exceptions
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.

◆ assign() [4/10]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::assign ( const basic_string< CharT, Traits > &  other,
size_type  pos,
size_type  count = npos 
)

Replace the contents with a substring [pos, std::min(pos+count, other.size()) of other transactionally.

Parameters
[in]otherstring from which substring will be copied.
[in]posstart position of substring in other.
[in]countlength of substring.
Exceptions
std::out_of_rangeis pos > other.size()
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.

◆ assign() [5/10]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::assign ( const std::basic_string< CharT > &  other,
size_type  pos,
size_type  count = npos 
)

Replace the contents with a substring [pos, std::min(pos+count, other.size()) of std::basic_string<CharT> other transactionally.

Parameters
[in]otherstd::basic_string<CharT> from which substring will be copied.
[in]posstart position of substring in other.
[in]countlength of substring.
Exceptions
std::out_of_rangeis pos > other.size()
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.

◆ assign() [6/10]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::assign ( const CharT *  s,
size_type  count 
)

Replace the contents with the first count elements of C-style string s transactionally.

Parameters
[in]spointer to source string.
[in]countlength of the string.
Exceptions
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.

◆ assign() [7/10]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::assign ( const CharT *  s)

Replace the contents with copy of C-style string s transactionally.

Parameters
[in]spointer to source string.
Exceptions
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.

◆ assign() [8/10]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::assign ( basic_string< CharT, Traits > &&  other)

Replace the string with the contents of other using move semantics transactionally.

Other is left in valid state with size equal to 0.

Parameters
[in]otherrvalue reference to the string to be moved from.
Exceptions
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.

◆ assign() [9/10]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::assign ( std::initializer_list< CharT >  ilist)

replace_content the contents with those of the initializer list ilist transactionally.

Parameters
[in]ilistinitializer_list of characters.
Exceptions
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.

◆ assign() [10/10]

template<typename CharT, typename Traits = std::char_traits<CharT>>
template<typename InputIt , typename Enable >
basic_string<CharT, Traits>& pmem::obj::basic_string< CharT, Traits >::assign ( InputIt  first,
InputIt  last 
)

Replace the contents with copies of elements in the range [first, last) transactionally.

This function participates in overload resolution only if InputIt satisfies InputIterator.

Parameters
[in]firstiterator to beginning of the range.
[in]lastiterator to end of the range.
Exceptions
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.

◆ assign_large_data() [1/3]

template<typename CharT , typename Traits >
template<typename InputIt , typename Enable >
basic_string< CharT, Traits >::pointer pmem::obj::basic_string< CharT, Traits >::assign_large_data ( InputIt  first,
InputIt  last 
)
private

Initialize non_sso.data - call constructor of non_sso.data.

Overload for pair of iterators.

◆ assign_large_data() [2/3]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::pointer pmem::obj::basic_string< CharT, Traits >::assign_large_data ( size_type  count,
value_type  ch 
)
private

Initialize non_sso.data - call constructor of non_sso.data.

Overload for (count, value).

◆ assign_large_data() [3/3]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::pointer pmem::obj::basic_string< CharT, Traits >::assign_large_data ( basic_string< CharT, Traits > &&  other)
private

Initialize non_sso.data - call constructor of non_sso.data.

Overload for rvalue reference of basic_string.

◆ assign_sso_data() [1/3]

template<typename CharT , typename Traits >
template<typename InputIt , typename Enable >
basic_string< CharT, Traits >::pointer pmem::obj::basic_string< CharT, Traits >::assign_sso_data ( InputIt  first,
InputIt  last 
)
private

Initialize sso data.

Overload for pair of iterators

◆ assign_sso_data() [2/3]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::pointer pmem::obj::basic_string< CharT, Traits >::assign_sso_data ( size_type  count,
value_type  ch 
)
private

Initialize sso data.

Overload for (count, value).

◆ assign_sso_data() [3/3]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::pointer pmem::obj::basic_string< CharT, Traits >::assign_sso_data ( basic_string< CharT, Traits > &&  other)
private

Initialize sso data.

Overload for rvalue reference of basic_string.

◆ at() [1/2]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::reference pmem::obj::basic_string< CharT, Traits >::at ( size_type  n)

Access element at specific index with bounds checking and snapshot it if there is an active transaction.

Parameters
[in]nindex number.
Returns
reference to element number n in underlying array.
Exceptions
std::out_of_rangeif n is not within the range of the container.
pmem::transaction_errorwhen adding the object to the transaction failed.

◆ at() [2/2]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::const_reference pmem::obj::basic_string< CharT, Traits >::at ( size_type  n) const

Access element at specific index with bounds checking.

Parameters
[in]nindex number.
Returns
const_reference to element number n in underlying array.
Exceptions
std::out_of_rangeif n is not within the range of the container.

◆ back() [1/2]

template<typename CharT , typename Traits >
CharT & pmem::obj::basic_string< CharT, Traits >::back ( )

Access last element and snapshot it if there is an active transaction.

Returns
reference to last element in string.
Exceptions
pmem::transaction_errorwhen adding the object to the transaction failed.

◆ back() [2/2]

template<typename CharT , typename Traits >
const CharT & pmem::obj::basic_string< CharT, Traits >::back ( ) const

Access last element.

Returns
const reference to last element in string.

◆ begin() [1/2]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::iterator pmem::obj::basic_string< CharT, Traits >::begin ( )

Return an iterator to the beginning.

Returns
an iterator pointing to the first element in the string.

◆ begin() [2/2]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::const_iterator pmem::obj::basic_string< CharT, Traits >::begin ( ) const
noexcept

Return const iterator to the beginning.

Returns
const iterator pointing to the first element in the string.

◆ c_str()

template<typename CharT , typename Traits >
const CharT * pmem::obj::basic_string< CharT, Traits >::c_str ( ) const
noexcept
Returns
pointer to underlying data.

◆ capacity()

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::size_type pmem::obj::basic_string< CharT, Traits >::capacity ( ) const
noexcept
Returns
number of characters that can be held in currently allocated storage.

◆ cback()

template<typename CharT , typename Traits >
const CharT & pmem::obj::basic_string< CharT, Traits >::cback ( ) const

Access last element.

In contradiction to back(), cback() will return const_reference not depending on the const-qualification of the object it is called on. std::basic_string doesn't provide cback() method.

Returns
const reference to last element in string.

◆ cbegin()

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::const_iterator pmem::obj::basic_string< CharT, Traits >::cbegin ( ) const
noexcept

Return const iterator to the beginning.

Returns
const iterator pointing to the first element in the string.

◆ cdata()

template<typename CharT , typename Traits >
const CharT * pmem::obj::basic_string< CharT, Traits >::cdata ( ) const
noexcept
Returns
const pointer to underlying data.

◆ cend()

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::const_iterator pmem::obj::basic_string< CharT, Traits >::cend ( ) const
noexcept

Return const iterator to past the end.

Returns
const_iterator referring to the past-the-end element in the string.

◆ cfront()

template<typename CharT , typename Traits >
const CharT & pmem::obj::basic_string< CharT, Traits >::cfront ( ) const

Access first element.

In contradiction to front(), cfront() will return const_reference not depending on the const-qualification of the object it is called on. std::basic_string doesn't provide cfront() method.

Returns
const reference to first element in string.

◆ check_pmem()

template<typename CharT , typename Traits >
void pmem::obj::basic_string< CharT, Traits >::check_pmem ( ) const
private
Exceptions
pmem::pool_errorif an object is not in persistent memory.

◆ check_pmem_tx()

template<typename CharT , typename Traits >
void pmem::obj::basic_string< CharT, Traits >::check_pmem_tx ( ) const
private
Exceptions
pmem::pool_errorif an object is not in persistent memory.
pmem::transaction_scope_errorif called outside of a transaction.

◆ check_tx_stage_work()

template<typename CharT , typename Traits >
void pmem::obj::basic_string< CharT, Traits >::check_tx_stage_work ( ) const
private
Exceptions
pmem::transaction_scope_errorif called outside of a transaction.

◆ clear()

template<typename CharT , typename Traits >
void pmem::obj::basic_string< CharT, Traits >::clear ( )

Remove all characters from the string transactionally.

All pointers, references, and iterators are invalidated.

Postcondition
size() == 0
Exceptions
pmem::transaction_errorwhen snapshotting failed.
rethrowsdestructor exception.

◆ compare() [1/9]

template<typename CharT , typename Traits >
int pmem::obj::basic_string< CharT, Traits >::compare ( const basic_string< CharT, Traits > &  other) const

Compares this string to other.

Parameters
[in]otherstring to compare to.
Returns
negative value if *this < other in lexicographical order, zero if *this == other and positive value if *this > other.

◆ compare() [2/9]

template<typename CharT, typename Traits >
int pmem::obj::basic_string< CharT, Traits >::compare ( const std::basic_string< CharT > &  other) const

Compares this string to std::basic_string<CharT> other.

Parameters
[in]otherstd::basic_string<CharT> to compare to.
Returns
negative value if *this < other in lexicographical order, zero if *this == other and positive value if *this > other.

◆ compare() [3/9]

template<typename CharT, typename Traits >
int pmem::obj::basic_string< CharT, Traits >::compare ( size_type  pos,
size_type  count,
const basic_string< CharT, Traits > &  other 
) const

Compares [pos, pos + count) substring of this to other.

If count > size() - pos, substring is equal to [pos, size()).

Parameters
[in]posbeginning of the substring.
[in]countlength of the substring.
[in]otherstring to compare to.
Returns
negative value if substring < other in lexicographical order, zero if substring == other and positive value if substring > other.
Exceptions
std::out_of_rangeis pos > size()

◆ compare() [4/9]

template<typename CharT, typename Traits >
int pmem::obj::basic_string< CharT, Traits >::compare ( size_type  pos,
size_type  count,
const std::basic_string< CharT > &  other 
) const

Compares [pos, pos + count) substring of this to std::basic_string<CharT> other.

If count > size() - pos, substring is equal to [pos, size()).

Parameters
[in]posbeginning of the substring.
[in]countlength of the substring.
[in]otherstd::basic_string<CharT> to compare to.
Returns
negative value if substring < other in lexicographical order, zero if substring == other and positive value if substring > other.
Exceptions
std::out_of_rangeis pos > size()

◆ compare() [5/9]

template<typename CharT, typename Traits >
int pmem::obj::basic_string< CharT, Traits >::compare ( size_type  pos1,
size_type  count1,
const basic_string< CharT, Traits > &  other,
size_type  pos2,
size_type  count2 = npos 
) const

Compares [pos1, pos1 + count1) substring of this to [pos2, pos2 + count2) substring of other.

If count1 > size() - pos, substring is equal to [pos1, size()).

Parameters
[in]pos1beginning of substring of this.
[in]count1length of substring of this.
[in]otherstring to compare to.
[in]pos2beginning of substring of other.
[in]count2length of substring of other.
Returns
negative value if substring of *this < substring of other in lexicographical order, zero if substring of *this == substring of other and positive value if substring of *this > substring of other.
Exceptions
std::out_of_rangeis pos1 > size() or pos2 > other.size()

◆ compare() [6/9]

template<typename CharT, typename Traits >
int pmem::obj::basic_string< CharT, Traits >::compare ( size_type  pos1,
size_type  count1,
const std::basic_string< CharT > &  other,
size_type  pos2,
size_type  count2 = npos 
) const

Compares [pos1, pos1 + count1) substring of this to [pos2, pos2 + count2) substring of std::basic_string<CharT> other.

If count1 > size() - pos, substring is equal to [pos1, size()).

Parameters
[in]pos1beginning of substring of this.
[in]count1length of substring of this.
[in]otherstd::basic_string<CharT> to compare to.
[in]pos2beginning of substring of other.
[in]count2length of substring of other.
Returns
negative value if substring of *this < substring of other in lexicographical order, zero if substring of *this == substring of other and positive value if substring of *this > substring of other.
Exceptions
std::out_of_rangeis pos1 > size() or pos2 > other.size()

◆ compare() [7/9]

template<typename CharT, typename Traits >
int pmem::obj::basic_string< CharT, Traits >::compare ( const CharT *  s) const

Compares this string to s.

Parameters
[in]sC-style string to compare to.
Returns
negative value if *this < s in lexicographical order, zero if *this == s and positive value if *this > s.

◆ compare() [8/9]

template<typename CharT, typename Traits >
int pmem::obj::basic_string< CharT, Traits >::compare ( size_type  pos,
size_type  count,
const CharT *  s 
) const

Compares [pos, pos + count) substring of this to s.

If count > size() - pos, substring is equal to [pos, size()).

Parameters
[in]posbeginning of the substring.
[in]countlength of the substring.
[in]sC-style string to compare to.
Returns
negative value if substring < s in lexicographical order, zero if substring == s and positive value if substring > s.
Exceptions
std::out_of_rangeis pos > size()

◆ compare() [9/9]

template<typename CharT, typename Traits >
int pmem::obj::basic_string< CharT, Traits >::compare ( size_type  pos,
size_type  count1,
const CharT *  s,
size_type  count2 
) const

Compares [pos, pos + count1) substring of this to [s, s + count2) substring of s.

If count > size() - pos, substring is equal to [pos, size()).

Parameters
[in]posbeginning of substring of this.
[in]count1length of substring of this.
[in]sC-style string to compare to.
[in]count2length of substring of s.
Returns
negative value if substring of *this < substring of s in lexicographical order, zero if substring of *this == substring of s and positive value if substring of *this > substring of s.
Exceptions
std::out_of_rangeis pos > size()

◆ const_at()

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::const_reference pmem::obj::basic_string< CharT, Traits >::const_at ( size_type  n) const

Access element at specific index with bounds checking.

In contradiction to at(), const_at() will return const_reference not depending on the const-qualification of the object it is called on. std::basic_string doesn't provide const_at() method.

Parameters
[in]nindex number.
Returns
const_reference to element number n in underlying array.
Exceptions
std::out_of_rangeif n is not within the range of the container.

◆ copy()

template<typename CharT, typename Traits >
basic_string< CharT, Traits >::size_type pmem::obj::basic_string< CharT, Traits >::copy ( CharT *  s,
size_type  count,
size_type  index = 0 
) const

Copy [index, index + count) substring of *this to C-style string.

If either count == npos or count exceeds size of *this string then substring [index, size()) is used. Resulting C-style string is not null-terminated.

Parameters
[in]spointer to destination C-style string.
[in]countlength of the substring.
[in]indexstart of the substring that will be copied.
Returns
number of copied characters.
Exceptions
std::out_of_rangeif index > size().

◆ crbegin()

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::const_reverse_iterator pmem::obj::basic_string< CharT, Traits >::crbegin ( ) const
noexcept

Return a const reverse iterator to the beginning.

Returns
a const reverse iterator pointing to the last element in non-reversed string.

◆ crend()

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::const_reverse_iterator pmem::obj::basic_string< CharT, Traits >::crend ( ) const
noexcept

Return a const reverse iterator to the end.

Returns
const reverse iterator referring to character preceding first character in the non-reversed string.

◆ data() [1/2]

template<typename CharT , typename Traits >
CharT * pmem::obj::basic_string< CharT, Traits >::data ( )
Returns
pointer to underlying data.
Exceptions
transaction_errorwhen adding data to the transaction failed.

◆ data() [2/2]

template<typename CharT , typename Traits >
const CharT * pmem::obj::basic_string< CharT, Traits >::data ( ) const
noexcept
Returns
pointer to underlying data.

◆ empty()

template<typename CharT , typename Traits >
bool pmem::obj::basic_string< CharT, Traits >::empty ( ) const
noexcept
Returns
true if string is empty, false otherwise.

◆ end() [1/2]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::iterator pmem::obj::basic_string< CharT, Traits >::end ( )

Return an iterator to past the end.

Returns
iterator referring to the past-the-end element in the string.

◆ end() [2/2]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::const_iterator pmem::obj::basic_string< CharT, Traits >::end ( ) const
noexcept

Return const iterator to past the end.

Returns
const_iterator referring to the past-the-end element in the string.

◆ erase() [1/5]

template<typename CharT , typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::erase ( size_type  index = 0,
size_type  count = npos 
)

Remove characters from string starting at index transactionally.

Length of the string to erase is determined as the smaller of count and size() - index.

Parameters
[in]indexfirst character to remove.
[in]countnumber of characters to remove.
Returns
*this
Precondition
index <= size()
Postcondition
size() = size() - std::min(count, size() - index)
Exceptions
std::out_of_rangeif index > size().
pmem::transaction_errorwhen snapshotting failed.
rethrowsdestructor exception.

◆ erase() [2/5]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::iterator pmem::obj::basic_string< CharT, Traits >::erase ( const_iterator  pos)

Remove character from string at pos position transactionally.

Parameters
[in]posposition of character to be removed.
Returns
Iterator following the removed element. If the iterator pos refers to the last element, the end() iterator is returned.
Precondition
pos <= size()
Postcondition
size() = size() - 1
Exceptions
std::out_of_rangeif pos > size().
pmem::transaction_errorwhen snapshotting failed.
rethrowsdestructor exception.

◆ erase() [3/5]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::iterator pmem::obj::basic_string< CharT, Traits >::erase ( const_iterator  first,
const_iterator  last 
)

Remove characters from string at [first, last) range transactionally.

Parameters
[in]firstbegin of the range of characters to be removed.
[in]lastend of the range of characters to be removed.
Returns
Iterator which points to the element pointed by the last iterator before the erase operation. If no such element exists then end() iterator is returned.
Precondition
first and last are valid iterators on *this.
Postcondition
size() = size() - std::distance(first, last)
Exceptions
std::out_of_rangeif [first, last) is not a valid range of *this.
pmem::transaction_errorwhen snapshotting failed.
rethrowsdestructor exception.

◆ erase() [4/5]

template<typename CharT , typename Traits >
template<typename T , typename Enable >
basic_string< CharT, Traits >::iterator pmem::obj::basic_string< CharT, Traits >::erase ( param)

Participate in overload resolution only if T is not convertible to size_type.

Call iterator erase(const_iterator pos) if enabled.

◆ erase() [5/5]

template<typename CharT, typename Traits = std::char_traits<CharT>>
template<typename T , typename Enable >
basic_string<CharT, Traits>& pmem::obj::basic_string< CharT, Traits >::erase ( param)

Participate in overload resolution only if T is convertible to size_type.

Call basic_string &erase(size_type index, size_type count = npos) if enabled.

◆ front() [1/2]

template<typename CharT , typename Traits >
CharT & pmem::obj::basic_string< CharT, Traits >::front ( )

Access first element and snapshot it if there is an active transaction.

Returns
reference to first element in string.
Exceptions
pmem::transaction_errorwhen adding the object to the transaction failed.

◆ front() [2/2]

template<typename CharT , typename Traits >
const CharT & pmem::obj::basic_string< CharT, Traits >::front ( ) const

Access first element.

Returns
const reference to first element in string.

◆ get_size() [1/3]

template<typename CharT , typename Traits >
template<typename InputIt , typename Enable >
basic_string< CharT, Traits >::size_type pmem::obj::basic_string< CharT, Traits >::get_size ( InputIt  first,
InputIt  last 
) const
private

Overload of generic get_size method used to calculate size based on provided parameters.

Return std::distance(first, last) for pair of iterators.

◆ get_size() [2/3]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::size_type pmem::obj::basic_string< CharT, Traits >::get_size ( size_type  count,
value_type  ch 
) const
private

Overload of generic get_size method used to calculate size based on provided parameters.

Return count for (count, value)

◆ get_size() [3/3]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::size_type pmem::obj::basic_string< CharT, Traits >::get_size ( const basic_string< CharT, Traits > &  other) const
private

Overload of generic get_size method used to calculate size based on provided parameters.

Return size of other basic_string

◆ initialize()

template<typename CharT , typename Traits >
template<typename... Args>
basic_string< CharT, Traits >::pointer pmem::obj::basic_string< CharT, Traits >::initialize ( Args &&...  args)
private

Generic function which initializes memory based on provided parameters - forwards parameters to initialize function of either non_sso.data or sso.data.

Allowed parameters are:

  • size_type count, CharT value
  • InputIt first, InputIt last
  • basic_string &&
Precondition
must be called in transaction scope.
memory must be allocated before initialization.

◆ insert() [1/11]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::insert ( size_type  index,
size_type  count,
CharT  ch 
)

Insert count copies of ch character at index transactionally.

Parameters
[in]indexposition at which the content will be inserted
[in]countnumber of characters to insert
[in]chcharacter to insert
Returns
*this
Postcondition
size() == size() + count
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::out_of_rangeif index > size().
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ insert() [2/11]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::insert ( size_type  index,
const CharT *  s 
)

Insert null-terminated C-style string pointed by s of the length determined by the first null character at index transactionally.

Parameters
[in]indexposition at which the content will be inserted.
[in]spointer to C-style string to insert.
Returns
*this
Postcondition
size() == size() + traits::length(s).
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::out_of_rangeif index > size().
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ insert() [3/11]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::insert ( size_type  index,
const CharT *  s,
size_type  count 
)

Insert characters in the range [s, s+ count) at index transactionally.

Parameters
[in]indexposition at which the content will be inserted.
[in]spointer to C-style string to insert.
[in]countnumber of characters to insert.
Returns
*this
Postcondition
size() == size() + count
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::out_of_rangeif index > size().
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ insert() [4/11]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::insert ( size_type  index,
const basic_string< CharT, Traits > &  str 
)

Insert str string at index transactionally.

Parameters
[in]indexposition at which the content will be inserted.
[in]strstring to insert.
Returns
*this
Postcondition
size() == size() + str.size()
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::out_of_rangeif index > size().
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ insert() [5/11]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::insert ( size_type  index1,
const basic_string< CharT, Traits > &  str,
size_type  index2,
size_type  count = npos 
)

Insert a str.substr(index2, count) string at index1 transactionally.

Parameters
[in]index1position at which the content will be inserted.
[in]strstring to insert.
[in]index2position of the first character in str to insert.
[in]countnumber of characters to insert.
Returns
*this
Postcondition
size() == size() + std::min(count, str.size() - index2)
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::out_of_rangeif index1 > size() or str.size() > index2.
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ insert() [6/11]

template<typename CharT, typename Traits >
basic_string< CharT, Traits >::iterator pmem::obj::basic_string< CharT, Traits >::insert ( const_iterator  pos,
CharT  ch 
)

Insert character ch before the character pointed by pos transactionally.

Parameters
[in]positerator before which the character will be inserted.
[in]chcharacter to insert.
Returns
iterator to the copy of the first inserted character or pos if no characters were inserted.
Precondition
pos is valid iterator on *this.
Postcondition
size() == size() + 1
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ insert() [7/11]

template<typename CharT, typename Traits >
basic_string< CharT, Traits >::iterator pmem::obj::basic_string< CharT, Traits >::insert ( const_iterator  pos,
size_type  count,
CharT  ch 
)

Insert count copies of character ch before the character pointed by pos transactionally.

Parameters
[in]positerator before which the character will be inserted.
[in]countnumber of characters to insert.
[in]chcharacter to insert.
Returns
iterator to the copy of the first inserted character or pos if no characters were inserted.
Precondition
pos is valid iterator on *this.
Postcondition
size() == size() + count
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ insert() [8/11]

template<typename CharT , typename Traits >
template<typename InputIt , typename Enable >
basic_string< CharT, Traits >::iterator pmem::obj::basic_string< CharT, Traits >::insert ( const_iterator  pos,
InputIt  first,
InputIt  last 
)

Insert characters from [first, last) range before the character pointed by pos transactionally.

Parameters
[in]positerator before which the character will be inserted.
[in]firstbegin of the range of characters to insert.
[in]lastend of the range of characters to insert.
Returns
iterator to the copy of the first inserted character or pos if no characters were inserted.
Precondition
pos is valid iterator on *this.
Postcondition
size() == size() + std::distance(first, last)
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ insert() [9/11]

template<typename CharT, typename Traits >
basic_string< CharT, Traits >::iterator pmem::obj::basic_string< CharT, Traits >::insert ( const_iterator  pos,
std::initializer_list< CharT >  ilist 
)

Insert characters from initializer list ilist before the character pointed by pos transactionally.

Parameters
[in]positerator before which the character will be inserted.
[in]ilistinitializer list of characters to insert.
Returns
iterator to the copy of the first inserted character or pos if no characters were inserted.
Precondition
pos is valid iterator on *this.
Postcondition
size() == size() + ilist.size()
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ insert() [10/11]

template<typename CharT, typename Traits >
template<typename T , typename Enable >
basic_string< CharT, Traits >::iterator pmem::obj::basic_string< CharT, Traits >::insert ( param,
size_type  count,
CharT  ch 
)

Participate in overload resolution only if T is not convertible to size_type.

Call iterator insert(const_iterator pos, size_type count, CharT ch) if enabled.

◆ insert() [11/11]

template<typename CharT, typename Traits = std::char_traits<CharT>>
template<typename T , typename Enable >
basic_string<CharT, Traits>& pmem::obj::basic_string< CharT, Traits >::insert ( param,
size_type  count,
CharT  ch 
)

Participate in overload resolution only if T is convertible to size_type.

Call basic_string &insert(size_type index, size_type count, CharT ch) if enabled.

◆ large_to_sso()

template<typename CharT , typename Traits >
void pmem::obj::basic_string< CharT, Traits >::large_to_sso ( )
private

Resize large string to sso string of size() size.

Content of large string is preserved and copied to the sso string.

Precondition
must be called in transaction scope.
size() of large string must be less than or equal sso_capacity
Postcondition
sso is used.

◆ length()

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::size_type pmem::obj::basic_string< CharT, Traits >::length ( ) const
noexcept
Returns
number of CharT elements in the string.

◆ max_size()

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::size_type pmem::obj::basic_string< CharT, Traits >::max_size ( ) const
noexcept
Returns
maximum number of elements the string is able to hold.

◆ operator+=() [1/4]

template<typename CharT , typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::operator+= ( const basic_string< CharT, Traits > &  str)

Append string str transactionally.

Parameters
[in]strstring to append.
Returns
*this
Postcondition
size() == size() + str.size()
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ operator+=() [2/4]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::operator+= ( const CharT *  s)

Append C-style string transactionally.

Length of the string is determined by the first null character.

Parameters
[in]spointer to C-style string to append.
Returns
*this
Postcondition
size() == size() + traits::length(s).
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ operator+=() [3/4]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::operator+= ( CharT  ch)

Append character ch at the end of the string transactionally.

Parameters
[in]chcharacter to append
Postcondition
size() == size() + 1
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::length_errorif new_size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ operator+=() [4/4]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::operator+= ( std::initializer_list< CharT >  ilist)

Append characters from the ilist initializer list transactionally.

Parameters
[in]ilistinitializer list with characters to append from
Returns
*this
Postcondition
size() == size() + ilist.size()
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ operator=() [1/6]

template<typename CharT , typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::operator= ( const basic_string< CharT, Traits > &  other)

Copy assignment operator.

Replace the string with contents of other transactionally.

Parameters
[in]otherreference to the string to be copied.
Exceptions
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.

◆ operator=() [2/6]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::operator= ( const std::basic_string< CharT > &  other)

Copy assignment operator.

Replace the string with contents of std::basic_string<CharT> other.

Parameters
[in]otherreference to the std::basic_string<CharT> to be copied.
Exceptions
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.

◆ operator=() [3/6]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::operator= ( basic_string< CharT, Traits > &&  other)

Move assignment operator.

Replace the string with the contents of other using move semantics transactionally.

Parameters
[in]otherrvalue reference to the string to be moved from.
Exceptions
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.

◆ operator=() [4/6]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::operator= ( const CharT *  s)

Replace the contents with copy of C-style string s transactionally.

Parameters
[in]spointer to source string.
Exceptions
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.

◆ operator=() [5/6]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::operator= ( CharT  ch)

Replace the contents with character ch transactionally.

Parameters
[in]chcharacter.
Exceptions
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.

◆ operator=() [6/6]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::operator= ( std::initializer_list< CharT >  ilist)

Replace the contents with those of the initializer list ilist transactionally.

Parameters
[in]ilistinitializer_list of characters.
Exceptions
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.

◆ operator[]() [1/2]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::reference pmem::obj::basic_string< CharT, Traits >::operator[] ( size_type  n)

Access element at specific index and snapshot it if there is an active transaction.

No bounds checking is performed.

Parameters
[in]nindex number.
Returns
reference to element number n in underlying array.
Exceptions
pmem::transaction_errorwhen adding the object to the transaction failed.

◆ operator[]() [2/2]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::const_reference pmem::obj::basic_string< CharT, Traits >::operator[] ( size_type  n) const

Access element at specific index.

No bounds checking is performed.

Parameters
[in]nindex number.
Returns
const_reference to element number n in underlying array.

◆ pop_back()

template<typename CharT , typename Traits >
void pmem::obj::basic_string< CharT, Traits >::pop_back ( )

Remove the last character from the string transactionally.

Precondition
!empty()
Postcondition
size() = size() - 1
Exceptions
pmem::transaction_errorwhen snapshotting failed.
rethrowsdestructor exception.

◆ push_back()

template<typename CharT, typename Traits >
void pmem::obj::basic_string< CharT, Traits >::push_back ( CharT  ch)

Append character ch at the end of the string transactionally.

Parameters
[in]chcharacter to append
Postcondition
size() == size() + 1
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ rbegin() [1/2]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::reverse_iterator pmem::obj::basic_string< CharT, Traits >::rbegin ( )

Return a reverse iterator to the beginning.

Returns
a reverse iterator pointing to the last element in non-reversed string.

◆ rbegin() [2/2]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::const_reverse_iterator pmem::obj::basic_string< CharT, Traits >::rbegin ( ) const
noexcept

Return a const reverse iterator to the beginning.

Returns
a const reverse iterator pointing to the last element in non-reversed string.

◆ rend() [1/2]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::reverse_iterator pmem::obj::basic_string< CharT, Traits >::rend ( )

Return a reverse iterator to the end.

Returns
reverse iterator referring to character preceding first character in the non-reversed string.

◆ rend() [2/2]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::const_reverse_iterator pmem::obj::basic_string< CharT, Traits >::rend ( ) const
noexcept

Return a const reverse iterator to the end.

Returns
const reverse iterator referring to character preceding first character in the non-reversed string.

◆ replace() [1/11]

template<typename CharT , typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::replace ( size_type  index,
size_type  count,
const basic_string< CharT, Traits > &  str 
)

Replace range [index, index + count) with the content of str string transactionally.

Parameters
[in]indexstart of the substring that will be replaced.
[in]countlength of the substring that will be replaced.
[in]strthat is used for the replacement.
Returns
*this
Postcondition
size() == size() - (std::min)(count, size() - index) + str.size()
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::out_of_rangeif index > size().
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ replace() [2/11]

template<typename CharT , typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::replace ( const_iterator  first,
const_iterator  last,
const basic_string< CharT, Traits > &  str 
)

Replace range [first, last) with the content of str string transactionally.

Parameters
[in]firstbegin of the range of characters that will be replaced.
[in]lastend of the range of characters that will be replaced.
[in]strthat that will be used for replacement.
Returns
*this
Postcondition
size() == size() - std::distance(first, last) + str.size()
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ replace() [3/11]

template<typename CharT , typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::replace ( size_type  index,
size_type  count,
const basic_string< CharT, Traits > &  str,
size_type  index2,
size_type  count2 = npos 
)

Replace range [index, index + count) with the substring [index2, index2 + count2) of str string transactionally.

If either count2 == npos or count2 exceeds size of str string then substring [index2, str.size()) is used.

Parameters
[in]indexstart of the substring that will be replaced.
[in]countlength of the substring that will be replaced.
[in]strthat is used for the replacement.
[in]index2start of the substring that will be used for replacement.
[in]count2length of the substring that will be used for replacement.
Returns
*this
Postcondition
size() == size() - (std::min)(count, size() - index) + (std::min)(count2, str.size() - index2)
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::out_of_rangeif index > size() or index2 > str.size().
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ replace() [4/11]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::replace ( const_iterator  first,
const_iterator  last,
const CharT *  s,
size_type  count2 
)

Replace range [first, last) with the characters in [s, s + count2) range transactionally.

Parameters
[in]firstbegin of the range of characters that will be replaced.
[in]lastend of the range of characters that will be replaced.
[in]spointer to C-style string that will be used for replacement.
[in]count2number of characters that will be used for replacement.
Returns
*this
Postcondition
size() == size() - std::distance(first, last) + count2.
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ replace() [5/11]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::replace ( const_iterator  first,
const_iterator  last,
const CharT *  s 
)

Replace range [first, last) with the characters in [s, s + traits::length(s)) range transactionally.

Parameters
[in]firstbegin of the range of characters that will be replaced.
[in]lastend of the range of characters that will be replaced.
[in]spointer to C-style string that will be used for replacement.
Returns
*this
Postcondition
size() == size() - std::distance(first, last) + traits::length(s).
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ replace() [6/11]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::replace ( size_type  index,
size_type  count,
size_type  count2,
CharT  ch 
)

Replace range [index, index + count) with count2 copies of ch character transactionally.

Parameters
[in]indexstart of the substring that will be replaced.
[in]countlength of the substring that will be replaced.
[in]count2number of characters that will be used for replacement.
[in]chcharacter that will be used for replacement.
Returns
*this
Postcondition
size() == size() - (std::min)(count, size() - index) + count2.
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::out_of_rangeif index > size().
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ replace() [7/11]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::replace ( const_iterator  first,
const_iterator  last,
size_type  count2,
CharT  ch 
)

Replace range [first, last) with count2 copies of ch character transactionally.

Parameters
[in]firstbegin of the range of characters that will be replaced.
[in]lastend of the range of characters that will be replaced.
[in]count2number of characters that will be used for replacement.
[in]chcharacter that will be used for replacement.
Returns
*this
Postcondition
size() == size() - std::distance(first, last) + count2.
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ replace() [8/11]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::replace ( size_type  index,
size_type  count,
const CharT *  s,
size_type  count2 
)

Replace range [index, index + count) with the characters in [s, s + count2) range transactionally.

Parameters
[in]indexstart of the substring that will be replaced.
[in]countlength of the substring that will be replaced.
[in]spointer to C-style string that will be used for replacement.
[in]count2number of characters that will be used for replacement.
Returns
*this
Postcondition
size() == size() - (std::min)(count, size() - index) + count2.
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::out_of_rangeif index > size().
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ replace() [9/11]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::replace ( size_type  index,
size_type  count,
const CharT *  s 
)

Replace range [index, index + count) with the characters in [s, s + traits::length(s)) range transactionally.

Parameters
[in]indexstart of the substring that will be replaced.
[in]countlength of the substring that will be replaced.
[in]spointer to C-style string that will be used for replacement.
Returns
*this
Postcondition
size() == size() - (std::min)(count, size() - index) + traits::length(s).
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::out_of_rangeif index > size().
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ replace() [10/11]

template<typename CharT, typename Traits >
basic_string< CharT, Traits > & pmem::obj::basic_string< CharT, Traits >::replace ( const_iterator  first,
const_iterator  last,
std::initializer_list< CharT >  ilist 
)

Replace range [first, last) with characters in initializer list ilist transactionally.

Parameters
[in]firstbegin of the range of characters that will be replaced.
[in]lastend of the range of characters that will be replaced.
[in]ilistinitializer list of characters that will be used for replacement.
Returns
*this
Postcondition
size() == size() - std::distance(first, last) + ilist.size().
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ replace() [11/11]

template<typename CharT, typename Traits = std::char_traits<CharT>>
template<typename InputIt , typename Enable >
basic_string<CharT, Traits>& pmem::obj::basic_string< CharT, Traits >::replace ( const_iterator  first,
const_iterator  last,
InputIt  first2,
InputIt  last2 
)

Replace range [first, last) with the characters in [first2, last2) range transactionally.

Parameters
[in]firstbegin of the range of characters that will be replaced.
[in]lastend of the range of characters that will be replaced.
[in]first2begin of the range of characters that will be used for replacement.
[in]last2end of the range of characters that will be used for replacement.
Returns
*this
Postcondition
size() == size() - std::distance(first, last) + std::distance(first2, last2).
capacity() == sso_capacity if new size is less than or equal to sso_capacity, or the smallest next power of 2, bigger than new size if it is greater than old capacity, or remains the same if there is enough space to store all new elements.
Exceptions
std::length_errorif new size > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.

◆ replace_content()

template<typename CharT , typename Traits >
template<typename... Args>
basic_string< CharT, Traits >::pointer pmem::obj::basic_string< CharT, Traits >::replace_content ( Args &&...  args)
private

Generic function which replace_content current content based on provided parameters.

Allowed parameters are:

  • size_type count, CharT value
  • InputIt first, InputIt last
  • basic_string &&

◆ reserve()

template<typename CharT , typename Traits >
void pmem::obj::basic_string< CharT, Traits >::reserve ( size_type  new_cap = 0)

Increase the capacity of the string to new_cap transactionally.

If new_cap is greater than the current capacity(), new storage is allocated, otherwise the method does nothing. If new_cap is greater than capacity(), all iterators, including the past-the-end iterator, and all references to the elements are invalidated. Otherwise, no iterators or references are invalidated.

Parameters
[in]new_capnew capacity.
Postcondition
capacity() == max(capacity(), capacity_new)
Exceptions
rethrowsdestructor exception.
std::length_errorif new_cap > max_size().
pmem::transaction_errorwhen snapshotting failed.
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.

◆ resize() [1/2]

template<typename CharT, typename Traits >
void pmem::obj::basic_string< CharT, Traits >::resize ( size_type  count,
CharT  ch 
)

Resize the string to count characters transactionally.

If the current size is greater than count, the string is reduced to its first count elements. If the current size is less than count, additional characters of ch value are appended.

Parameters
[in]countnew size of the container.
[in]chcharacter to initialize elements.
Postcondition
capacity() == std::max(count, capacity())
size() == count
Exceptions
std::length_errorif count > max_size()
rethrowsconstructor exception.
rethrowsdestructor exception.
pmem::transaction_errorwhen snapshotting failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.

◆ resize() [2/2]

template<typename CharT, typename Traits >
void pmem::obj::basic_string< CharT, Traits >::resize ( size_type  count)

Resize the string to count characters transactionally.

If the current size is greater than count, the string is reduced to its first count elements. If the current size is less than count, additional default-initialized characters are appended.

Parameters
[in]countnew size of the container.
Postcondition
capacity() == std::max(count, capacity())
size() == count
Exceptions
std::length_errorif count > max_size()
rethrowsconstructor exception.
rethrowsdestructor exception.
pmem::transaction_errorwhen snapshotting failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.

◆ shrink_to_fit()

template<typename CharT , typename Traits >
void pmem::obj::basic_string< CharT, Traits >::shrink_to_fit ( )

Remove unused capacity transactionally.

If large string is used capacity will be set to current size. If sso is used nothing happens.

Postcondition
capacity() == std::min(sso_capacity, capacity())
Exceptions
pmem::transaction_errorwhen snapshotting failed.
pmem::transaction_alloc_errorwhen reallocating failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor exception.
rethrowsdestructor exception.

◆ size()

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::size_type pmem::obj::basic_string< CharT, Traits >::size ( ) const
noexcept
Returns
number of CharT elements in the string.

◆ sso_to_large()

template<typename CharT , typename Traits >
void pmem::obj::basic_string< CharT, Traits >::sso_to_large ( size_t  new_capacity)
private

Resize sso string to large string.

Capacity is equal new_capacity plus sizeof(CharT) bytes for null character. Content of sso string is preserved and copied to the large string object.

Precondition
must be called in transaction scope.
Postcondition
sso is not used.
Parameters
[in]new_capacitycapacity of constructed large string.

Member Data Documentation

◆ @1

union { ... }

This union holds sso data inside of an array and non sso data inside a vector.

If vector is used, it must be manually created and destroyed.

_size is used to store length in case when SSO is used. It is the same type as first member of data field. This means that it can be safely accessed through both sso (_size variable) and non_sso (as size in a vector) no matter which one is used.

C++11 ยง9.2/18 says: If a standard-layout union contains two or more standard-layout structs that share a common initial sequence, and if the standard-layout union object currently contains one of these standard-layout structs, it is permitted to inspect the common initial part of any of them.


The documentation for this class was generated from the following file: