PMDK C++ bindings  1.12-git53.g67ba2be4
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...
 
template<class T , typename Enable = typename std::enable_if< std::is_convertible<const T &, pmem::obj::basic_string_view< CharT, Traits>>::value && !std::is_convertible<const T &, const CharT *>::value>>
 basic_string (const T &t)
 Implicitly converts argument to a string view then initilizes the string with the content of string view. More...
 
template<class T , typename Enable = typename std::enable_if<std::is_convertible< const T &, pmem::obj::basic_string_view<CharT, Traits>>::value>>
 basic_string (const T &t, size_type pos, size_type n)
 Implicitly converts argument to a string view then initilizes the string with the subrange [pos, pos + n) of string view. More...
 
 ~basic_string ()
 Destructor.
 
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
 
void for_each_ptr (for_each_ptr_function func)
 Iterates over all internal pointers and executes a callback function on each of them. More...
 
slice< pointer > range (size_type p, size_type count)
 Returns slice and snapshots requested range. More...
 
slice< range_snapshotting_iteratorrange (size_type start, size_type n, size_type snapshot_size)
 Returns slice. More...
 
slice< const_iterator > range (size_type start, size_type n) const
 Returns const slice. More...
 
slice< const_iterator > crange (size_type start, size_type n) const
 Returns const slice. More...
 
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...
 
void free_data ()
 Clears the content of a string and frees all allocated persistent memory for data 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...
 
size_type find (const basic_string &str, size_type pos=0) const noexcept
 Finds the first substring equal str. More...
 
size_type find (const CharT *s, size_type pos, size_type count) const
 Finds the first substring equal to the range [s, s+count). More...
 
size_type find (const CharT *s, size_type pos=0) const
 Finds the first substring equal to the C-style string pointed to by s. More...
 
size_type find (CharT ch, size_type pos=0) const noexcept
 Finds the first character ch. More...
 
size_type rfind (const basic_string &str, size_type pos=npos) const noexcept
 Finds the last substring equal to str. More...
 
size_type rfind (const CharT *s, size_type pos, size_type count) const
 Finds the last substring equal to the range [s, s+count). More...
 
size_type rfind (const CharT *s, size_type pos=npos) const
 Finds the last substring equal to the C-style string pointed to by s. More...
 
size_type rfind (CharT ch, size_type pos=npos) const noexcept
 Finds the last character equal to ch. More...
 
size_type find_first_of (const basic_string &str, size_type pos=0) const noexcept
 Finds the first character equal to any of the characters in str. More...
 
size_type find_first_of (const CharT *s, size_type pos, size_type count) const
 Finds the first character equal to any of the characters in the range [s, s+count). More...
 
size_type find_first_of (const CharT *s, size_type pos=0) const
 Finds the first character equal to any of the characters in the C-style string pointed to by s. More...
 
size_type find_first_of (CharT ch, size_type pos=0) const noexcept
 Finds the first character equal to ch. More...
 
size_type find_first_not_of (const basic_string &str, size_type pos=0) const noexcept
 Finds the first character equal to none of the characters in str. More...
 
size_type find_first_not_of (const CharT *s, size_type pos, size_type count) const
 Finds the first character equal to none of the characters in the range [s, s+count). More...
 
size_type find_first_not_of (const CharT *s, size_type pos=0) const
 Finds the first character equal to none of the characters in the C-style string pointed to by s. More...
 
size_type find_first_not_of (CharT ch, size_type pos=0) const noexcept
 Finds the first character not equal to ch. More...
 
size_type find_last_of (const basic_string &str, size_type pos=npos) const noexcept
 Finds the last character equal to any of the characters in str. More...
 
size_type find_last_of (const CharT *s, size_type pos, size_type count) const
 Finds the last character equal to any of the characters in the range [s, s+count). More...
 
size_type find_last_of (const CharT *s, size_type pos=npos) const
 Finds the last character equal to any of the characters in the C-style string pointed to by s. More...
 
size_type find_last_of (CharT ch, size_type pos=npos) const noexcept
 Finds the last character equal to ch. More...
 
size_type find_last_not_of (const basic_string &str, size_type pos=npos) const noexcept
 Finds the last character equal to none of the characters in str. More...
 
size_type find_last_not_of (const CharT *s, size_type pos, size_type count) const
 Finds the last character equal to none of the characters in the range [s, s+count). More...
 
size_type find_last_not_of (const CharT *s, size_type pos=npos) const
 Finds the last character equal to none of the characters in the C-style string pointed to by s. More...
 
size_type find_last_not_of (CharT ch, size_type pos=npos) const noexcept
 Finds the last character not equal to ch. More...
 
void swap (basic_string &other)
 Swap the content of persistent strings.
 
 operator basic_string_view< CharT, Traits > () const
 Return new view from this string object.
 
template<class T , typename Enable >
basic_string< CharT, Traits > & operator= (const T &t)
 Replace the contents with implicitly converted argument transactionally. 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 n elements. 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 move_data (basic_string &&other)
 Move initialize for basic_string. 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...
 
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.

Simple example of pmem::obj::string usage

using namespace pmem;
using namespace pmem::obj;
/* example object containing string */
struct example_object {
example_object(){};
example_object(const char *s) : string_inside(s){};
string string_inside;
};
/* pool root structure */
struct root {
persistent_ptr<string> test_string = nullptr;
persistent_ptr<example_object> test_object = nullptr;
};
/* example with persistent_ptr<string> */
void
example_with_ptr(pool<root> &pop)
{
auto r = pop.root();
if (r->test_string == nullptr) {
transaction::run(pop, [&] {
/* note that allocation in transaction is made by
* make_persistent */
r->test_string = make_persistent<string>("example1");
});
}
std::cout << r->test_string->c_str() << std::endl;
transaction::run(pop, [&] {
delete_persistent<string>(r->test_string);
r->test_string = nullptr;
});
}
/* example with object containing string */
void
example_with_object(pool<root> &pop)
{
auto r = pop.root();
if (r->test_object == nullptr) {
transaction::run(pop, [&] {
/* WRONG:
* r->test_object = make_persistent<example_object>();
* r->test_object->string_inside = string("example2");
*/
/* GOOD: */
r->test_object =
make_persistent<example_object>("example2");
/* OR:
* r->test_object = make_persistent<example_object>();
* r->test_object->string_inside.assign("example2");
*/
});
}
std::cout << r->test_object->string_inside.c_str() << std::endl;
transaction::run(pop, [&] {
delete_persistent<example_object>(r->test_object);
r->test_object = nullptr;
});
}

Constructor & Destructor Documentation

◆ basic_string() [1/13]

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/13]

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/13]

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/13]

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/13]

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/13]

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/13]

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/13]

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/13]

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/13]

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/13]

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() [12/13]

template<typename CharT , typename Traits >
template<class T , typename Enable >
pmem::obj::basic_string< CharT, Traits >::basic_string ( const T &  t)
explicit

Implicitly converts argument to a string view then initilizes the string with the content of string view.

Parameters
[in]tobject (convertible to std::basic_string_view) to initialize the string with.
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() [13/13]

template<typename CharT , typename Traits >
template<class T , typename Enable >
pmem::obj::basic_string< CharT, Traits >::basic_string ( const T &  t,
size_type  pos,
size_type  n 
)

Implicitly converts argument to a string view then initilizes the string with the subrange [pos, pos + n) of string view.

Parameters
[in]tobject (convertible to std::basic_string_view) to initialize the string with.
[in]posposition of the first character to include.
[in]ncharacters to include
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.

Member Function Documentation

◆ allocate()

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

Allocate storage for container of n elements.

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

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

◆ append() [1/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's 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,
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's exception.

◆ append() [3/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's 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's exception.

◆ append() [5/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's exception.

◆ append() [6/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's exception.

◆ append() [7/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's exception.

◆ assign() [1/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() [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 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() [4/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() [5/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() [6/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() [7/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() [8/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() [9/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() [10/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_large_data() [1/2]

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/2]

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_sso_data() [1/2]

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/2]

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).

◆ 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

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
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
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
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

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
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
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
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

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
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
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
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 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() [3/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() [4/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() [5/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() [6/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() [7/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()

◆ compare() [8/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() [9/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()

◆ 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().

◆ crange()

template<typename CharT , typename Traits >
slice< typename basic_string< CharT, Traits >::const_iterator > pmem::obj::basic_string< CharT, Traits >::crange ( size_type  start,
size_type  n 
) const

Returns const slice.

This method is not specified by STL standards.

Parameters
[in]startstart index of requested range.
[in]nnumber of elements in range.
Returns
slice containing elements from <start, start + n).
Exceptions
std::out_of_rangeif any element of the range would be outside of the string.

◆ crbegin()

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::const_reverse_iterator pmem::obj::basic_string< CharT, Traits >::crbegin
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
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
noexcept
Returns
pointer to underlying data.

◆ empty()

template<typename CharT , typename Traits >
bool pmem::obj::basic_string< CharT, Traits >::empty
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
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 >::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() [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 > & 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() [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.

◆ find() [1/4]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::size_type pmem::obj::basic_string< CharT, Traits >::find ( CharT  ch,
size_type  pos = 0 
) const
noexcept

Finds the first character ch.

Parameters
[in]chcharacter to search for
[in]posposition where the search starts from
Returns
Position of the first character equal to ch, or npos if no such character is found.

◆ find() [2/4]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::size_type pmem::obj::basic_string< CharT, Traits >::find ( const basic_string< CharT, Traits > &  str,
size_type  pos = 0 
) const
noexcept

Finds the first substring equal str.

Parameters
[in]strstring to search for
[in]posposition where the search starts from
Returns
Position of the first character of the found substring or npos if no such substring is found.

◆ find() [3/4]

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

Finds the first substring equal to the range [s, s+count).

This range may contain null characters.

Parameters
[in]spointer to the C-style string to search for
[in]posposition where the search starts from
[in]countlength of the substring to search for
Returns
Position of the first character of the found substring or npos if no such substring is found.

◆ find() [4/4]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::size_type pmem::obj::basic_string< CharT, Traits >::find ( const CharT *  s,
size_type  pos = 0 
) const

Finds the first substring equal to the C-style string pointed to by s.

The length of the string is determined by the first null character.

Parameters
[in]spointer to the C-style string to search for
[in]posposition where the search starts from
Returns
Position of the first character of the found substring or npos if no such substring is found.

◆ find_first_not_of() [1/4]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::size_type pmem::obj::basic_string< CharT, Traits >::find_first_not_of ( CharT  ch,
size_type  pos = 0 
) const
noexcept

Finds the first character not equal to ch.

Parameters
[in]chcharacter to search for
[in]posposition at which to start the search
Returns
The position of the first character that does not match. If no such characters are found, the function returns npos.

◆ find_first_not_of() [2/4]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::size_type pmem::obj::basic_string< CharT, Traits >::find_first_not_of ( const basic_string< CharT, Traits > &  str,
size_type  pos = 0 
) const
noexcept

Finds the first character equal to none of the characters in str.

Parameters
[in]strstring identifying characters to search for
[in]posposition at which to start the search
Returns
The position of the first character that does not match. If no such characters are found, the function returns npos.

◆ find_first_not_of() [3/4]

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

Finds the first character equal to none of the characters in the range [s, s+count).

This range can include null characters.

Parameters
[in]spointer to the C-style string identifying characters to search for
[in]posposition at which to start the search
[in]countlength of the C-style string identifying characters to search for
Returns
The position of the first character that does not match. If no such characters are found, the function returns npos.

◆ find_first_not_of() [4/4]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::size_type pmem::obj::basic_string< CharT, Traits >::find_first_not_of ( const CharT *  s,
size_type  pos = 0 
) const

Finds the first character equal to none of the characters in the C-style string pointed to by s.

The length of the string is determined by the first null character

Parameters
[in]spointer to the C-style string identifying characters to search for
[in]posposition at which to start the search
Returns
The position of the first character that does not match. If no such characters are found, the function returns npos.

◆ find_first_of() [1/4]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::size_type pmem::obj::basic_string< CharT, Traits >::find_first_of ( CharT  ch,
size_type  pos = 0 
) const
noexcept

Finds the first character equal to ch.

Parameters
[in]chcharacter to search for
[in]posposition at which to start the search
Returns
The position of the first character that matches. If no matches are found, the function returns npos.

◆ find_first_of() [2/4]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::size_type pmem::obj::basic_string< CharT, Traits >::find_first_of ( const basic_string< CharT, Traits > &  str,
size_type  pos = 0 
) const
noexcept

Finds the first character equal to any of the characters in str.

Parameters
[in]strstring identifying characters to search for
[in]posposition at which to start the search
Returns
The position of the first character that matches. If no matches are found, the function returns npos.

◆ find_first_of() [3/4]

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

Finds the first character equal to any of the characters in the range [s, s+count).

This range can include null characters.

Parameters
[in]spointer to the C-style string identifying characters to search for
[in]posposition at which to start the search
[in]countlength of the C-style string identifying characters to search for
Returns
The position of the first character that matches. If no matches are found, the function returns npos.

◆ find_first_of() [4/4]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::size_type pmem::obj::basic_string< CharT, Traits >::find_first_of ( const CharT *  s,
size_type  pos = 0 
) const

Finds the first character equal to any of the characters in the C-style string pointed to by s.

The length of the string is determined by the first null character

Parameters
[in]spointer to the C-style string identifying characters to search for
[in]posposition at which to start the search
Returns
The position of the first character that matches. If no matches are found, the function returns npos.

◆ find_last_not_of() [1/4]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::size_type pmem::obj::basic_string< CharT, Traits >::find_last_not_of ( CharT  ch,
size_type  pos = npos 
) const
noexcept

Finds the last character not equal to ch.

Parameters
[in]chcharacter to search for
[in]posposition at which to start the search
Returns
The position of the first character that does not match. If no such characters are found, the function returns npos.

◆ find_last_not_of() [2/4]

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

Finds the last character equal to none of the characters in str.

Parameters
[in]strstring identifying characters to search for
[in]posposition at which to start the search
Returns
The position of the first character that does not match. If no such characters are found, the function returns npos.

◆ find_last_not_of() [3/4]

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

Finds the last character equal to none of the characters in the range [s, s+count).

This range can include null characters.

Parameters
[in]spointer to the C-style string identifying characters to search for
[in]posposition at which to start the search
[in]countlength of the C-style string identifying characters to search for
Returns
The position of the first character that does not match. If no such characters are found, the function returns npos.

◆ find_last_not_of() [4/4]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::size_type pmem::obj::basic_string< CharT, Traits >::find_last_not_of ( const CharT *  s,
size_type  pos = npos 
) const

Finds the last character equal to none of the characters in the C-style string pointed to by s.

The length of the string is determined by the first null character

Parameters
[in]spointer to the C-style string identifying characters to search for
[in]posposition at which to start the search
Returns
Position of the first character not equal to any of the characters in the given string, or npos if no such character is found.

◆ find_last_of() [1/4]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::size_type pmem::obj::basic_string< CharT, Traits >::find_last_of ( CharT  ch,
size_type  pos = npos 
) const
noexcept

Finds the last character equal to ch.

Parameters
[in]chcharacter to search for
[in]posposition at which to start the search
Returns
The position of the last character that matches. If no matches are found, the function returns npos.

◆ find_last_of() [2/4]

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

Finds the last character equal to any of the characters in str.

Parameters
[in]strstring identifying characters to search for
[in]posposition at which to start the search
Returns
The position of the last character that matches. If no matches are found, the function returns npos.

◆ find_last_of() [3/4]

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

Finds the last character equal to any of the characters in the range [s, s+count).

This range can include null characters.

Parameters
[in]spointer to the C-style string identifying characters to search for
[in]posposition at which to start the search
[in]countlength of the C-style string identifying characters to search for
Returns
The position of the last character that matches. If no matches are found, the function returns npos.

◆ find_last_of() [4/4]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::size_type pmem::obj::basic_string< CharT, Traits >::find_last_of ( const CharT *  s,
size_type  pos = npos 
) const

Finds the last character equal to any of the characters in the C-style string pointed to by s.

The length of the string is determined by the first null character

Parameters
[in]spointer to the C-style string identifying characters to search for
[in]posposition at which to start the search
Returns
The position of the last character that matches. If no matches are found, the function returns npos.

◆ for_each_ptr()

template<typename CharT , typename Traits >
void pmem::obj::basic_string< CharT, Traits >::for_each_ptr ( for_each_ptr_function  func)

Iterates over all internal pointers and executes a callback function on each of them.

In this implementation, it just calls for_each_ptr() of the vector stored in SSO.

Parameters
funccallback function to call on internal pointer.

◆ free_data()

template<typename CharT , typename Traits >
void pmem::obj::basic_string< CharT, Traits >::free_data

Clears the content of a string and frees all allocated persistent memory for data transactionally.

Postcondition
size() == 0
capacity() == 0
data() == nullptr
Exceptions
pmem::transaction_errorwhen snapshotting failed.
pmem::transaction_free_errorwhen freeing of underlying structure failed.

◆ 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

Access first element.

Returns
const reference to first element in string.

◆ get_size() [1/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

◆ get_size() [2/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() [3/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)

◆ 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
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 >::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's exception.

◆ insert() [2/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's exception.

◆ insert() [3/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's exception.

◆ insert() [4/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's exception.

◆ insert() [5/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's exception.

◆ insert() [6/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's exception.

◆ insert() [7/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's exception.

◆ insert() [8/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's exception.

◆ insert() [9/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's 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
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
noexcept
Returns
maximum number of elements the string is able to hold.

◆ move_data()

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

Move initialize for basic_string.

Expects data is not initialized.

◆ operator+=() [1/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's exception.

◆ operator+=() [2/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's exception.

◆ operator+=() [3/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's 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's exception.

◆ operator=() [1/7]

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=() [2/7]

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=() [3/7]

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=() [4/7]

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/7]

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=() [6/7]

template<typename CharT , typename Traits = std::char_traits<CharT>>
template<class T , typename Enable >
basic_string<CharT, Traits>& pmem::obj::basic_string< CharT, Traits >::operator= ( const T &  t)

Replace the contents with implicitly converted argument transactionally.

Parameters
[in]tobject (convertible to basic_string_view).
Exceptions
pmem::transaction_alloc_errorwhen allocating memory for underlying storage in transaction failed.

◆ operator=() [7/7]

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's exception.

◆ range() [1/3]

template<typename CharT , typename Traits >
slice< typename basic_string< CharT, Traits >::pointer > pmem::obj::basic_string< CharT, Traits >::range ( size_type  start,
size_type  n 
)

Returns slice and snapshots requested range.

This method is not specified by STL standards.

Parameters
[in]startstart index of requested range.
[in]nnumber of elements in range.
Returns
slice containing elements from <start, start + n).
Exceptions
std::out_of_rangeif any element of the range would be outside of the string.
pmem::transaction_errorwhen snapshotting failed.

◆ range() [2/3]

template<typename CharT , typename Traits >
slice< typename basic_string< CharT, Traits >::const_iterator > pmem::obj::basic_string< CharT, Traits >::range ( size_type  start,
size_type  n 
) const

Returns const slice.

This method is not specified by STL standards.

Parameters
[in]startstart index of requested range.
[in]nnumber of elements in range.
Returns
slice containing elements from <start, start + n).
Exceptions
std::out_of_rangeif any element of the range would be outside of the string.

◆ range() [3/3]

template<typename CharT , typename Traits >
slice< typename basic_string< CharT, Traits >::range_snapshotting_iterator > pmem::obj::basic_string< CharT, Traits >::range ( size_type  start,
size_type  n,
size_type  snapshot_size 
)

Returns slice.

This method is not specified by STL standards.

Parameters
[in]startstart index of requested range.
[in]nnumber of elements in range.
[in]snapshot_sizenumber of elements which should be snapshotted in a bulk while traversing this slice. If provided value is larger or equal to n, entire range is added to a transaction. If value is equal to 0 no snapshotting happens.
Returns
slice containing elements from <start, start + n).
Exceptions
std::out_of_rangeif any element of the range would be outside of the string.
pmem::transaction_errorwhen snapshotting failed.

◆ 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
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
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 ( 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's 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 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's exception.

◆ replace() [3/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's exception.

◆ replace() [4/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's 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,
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's exception.

◆ replace() [6/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's exception.

◆ replace() [7/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's 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 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's 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's exception.

◆ replace() [10/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's exception.

◆ replace() [11/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's 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

◆ 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's 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's exception.
rethrowsdestructor exception.
pmem::transaction_errorwhen snapshotting failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.

◆ rfind() [1/4]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::size_type pmem::obj::basic_string< CharT, Traits >::rfind ( CharT  ch,
size_type  pos = npos 
) const
noexcept

Finds the last character equal to ch.

If npos or any value not smaller than size()-1 is passed as pos, whole string will be searched.

Parameters
[in]chcharacter to search for
[in]posposition at which to start the search
Returns
Position (as an offset from the start of the string) of the first character equal to ch or npos if no such character is found

◆ rfind() [2/4]

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

Finds the last substring equal to str.

If npos or any value not smaller than size()-1 is passed as pos, whole string will be searched.

Parameters
[in]strstring to search for
[in]posposition at which to start the search
Returns
Position (as an offset from the start of the string) of the first character of the found substring or npos if no such substring is found

◆ rfind() [3/4]

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

Finds the last substring equal to the range [s, s+count).

This range can include null characters. When pos is specified, the search only includes sequences of characters that begin at or before position pos, ignoring any possible match beginning after pos. If npos or any value not smaller than size()-1 is passed as pos, whole string will be searched.

Parameters
[in]spointer to the C-style string to search for
[in]posposition at which to start the search
[in]countlength of the substring to search for
Returns
Position (as an offset from the start of the string) of the first character of the found substring or npos if no such substring is found. If searching for an empty string returns pos unless pos > size(), in which case returns size().

◆ rfind() [4/4]

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::size_type pmem::obj::basic_string< CharT, Traits >::rfind ( const CharT *  s,
size_type  pos = npos 
) const

Finds the last substring equal to the C-style string pointed to by s.

The length of the string is determined by the first null character. If npos or any value not smaller than size()-1 is passed as pos, whole string will be searched.

Parameters
[in]spointer to the C-style string to search for
[in]posposition at which to start the search
Returns
Position (as an offset from the start of the string) of the first character of the found substring or npos if no such substring is found

◆ 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's exception.
rethrowsdestructor exception.

◆ size()

template<typename CharT , typename Traits >
basic_string< CharT, Traits >::size_type pmem::obj::basic_string< CharT, Traits >::size
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:
pmem
Persistent memory namespace.
Definition: allocation_flag.hpp:15
pmem::obj::basic_transaction::run
static void run(obj::pool_base &pool, std::function< void()> tx, Locks &... locks)
Execute a closure-like transaction and lock locks.
Definition: transaction.hpp:688
pmem::obj::pool::root
persistent_ptr< T > root()
Retrieves pool's root object.
Definition: pool.hpp:627
pmem::obj
Main libpmemobj namespace.
Definition: allocation_flag.hpp:18
pmem::obj::persistent_ptr
Persistent pointer class.
Definition: persistent_ptr.hpp:152
pmem::obj::pool
PMEMobj pool class.
Definition: pool.hpp:465