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 initializes 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 initializes the string with the subrange [pos, pos + n) of string view. More...
	~basic_string ()
	Destructor.
basic_string &	operator= (const basic_string &other)
	Copy assignment operator. More...
basic_string &	operator= (const std::basic_string< CharT > &other)
	Copy assignment operator. More...
basic_string &	operator= (basic_string &&other)
	Move assignment operator. More...
basic_string &	operator= (const CharT *s)
	Replace the contents with copy of C-style string s transactionally. More...
basic_string &	operator= (CharT ch)
	Replace the contents with character ch transactionally. More...
basic_string &	operator= (std::initializer_list< CharT > ilist)
	Replace the contents with those of the initializer list ilist transactionally. More...
basic_string &	assign (size_type count, CharT ch)
	Replace the contents with count copies of character ch transactionally. More...
basic_string &	assign (const basic_string &other)
	Replace the string with the copy of the contents of other transactionally. More...
basic_string &	assign (const std::basic_string< CharT > &other)
	Replace the string with the copy of the contents of std::basic_string<CharT> other. More...
basic_string &	assign (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_string &	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. More...
basic_string &	assign (const CharT *s, size_type count)
	Replace the contents with the first count elements of C-style string s transactionally. More...
basic_string &	assign (const CharT *s)
	Replace the contents with copy of C-style string s transactionally. More...
basic_string &	assign (basic_string &&other)
	Replace the string with the contents of other using move semantics transactionally. More...
basic_string &	assign (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_iterator >	range (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_string &	erase (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_string &	append (size_type count, CharT ch)
	Append count copies of character ch to the string transactionally. More...
basic_string &	append (const basic_string &str)
	Append string str transactionally. More...
basic_string &	append (const basic_string &str, size_type pos, size_type count=npos)
	Append substring [pos, pos + count) of str string transactionally. More...
basic_string &	append (const CharT *s, size_type count)
	Append characters in the range [s, s + count) transactionally. More...
basic_string &	append (const CharT *s)
	Append C-style string transactionally. More...
basic_string &	append (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_string &	operator+= (const basic_string &str)
	Append string str transactionally. More...
basic_string &	operator+= (const CharT *s)
	Append C-style string transactionally. More...
basic_string &	operator+= (CharT c)
	Append character ch at the end of the string transactionally. More...
basic_string &	operator+= (std::initializer_list< CharT > ilist)
	Append characters from the ilist initializer list transactionally. More...
basic_string &	insert (size_type index, size_type count, CharT ch)
	Insert count copies of ch character at index transactionally. More...
basic_string &	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. More...
basic_string &	insert (size_type index, const CharT *s, size_type count)
	Insert characters in the range [s, s+ count) at index transactionally. More...
basic_string &	insert (size_type index, const basic_string &str)
	Insert str string at index transactionally. More...
basic_string &	insert (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_string &	replace (size_type index, size_type count, const basic_string &str)
	Replace range [index, index + count) with the content of str string transactionally. More...
basic_string &	replace (const_iterator first, const_iterator last, const basic_string &str)
	Replace range [first, last) with the content of str string transactionally. More...
basic_string &	replace (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_string &	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. More...
basic_string &	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. More...
basic_string &	replace (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_string &	replace (const_iterator first, const_iterator last, size_type count2, CharT ch)
	Replace range [first, last) with count2 copies of ch character transactionally. More...
basic_string &	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. More...
basic_string &	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. More...
basic_string &	replace (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_error	if an object is not in persistent memory.
pmem::transaction_scope_error	if 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]	count	number of elements to construct.
[in]	ch	value of all constructed elements.

Precondition

must be called in transaction scope.

Exceptions

pmem::pool_error	if an object is not in persistent memory.
pmem::transaction_alloc_error	when allocating memory for underlying storage in transaction failed.
pmem::transaction_scope_error	if 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]	other	string from which substring will be copied.
[in]	pos	start position of substring in other.
[in]	count	length of substring.

Precondition

must be called in transaction scope.

Exceptions

std::out_of_range	is pos > other.size()
pmem::pool_error	if an object is not in persistent memory.
pmem::transaction_alloc_error	when allocating memory for underlying storage in transaction failed.
pmem::transaction_scope_error	if 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]	other	std::basic_string<CharT> from which substring will be copied.
[in]	pos	start position of substring in other.
[in]	count	length of substring.

Precondition

must be called in transaction scope.

Exceptions

std::out_of_range	is pos > other.size()
pmem::pool_error	if an object is not in persistent memory.
pmem::transaction_alloc_error	when allocating memory for underlying storage in transaction failed.
pmem::transaction_scope_error	if 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]	s	pointer to source string.
[in]	count	length of the resulting string.

Precondition

must be called in transaction scope.

Exceptions

pmem::pool_error	if an object is not in persistent memory.
pmem::transaction_alloc_error	when allocating memory for underlying storage in transaction failed.
pmem::transaction_scope_error	if 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]

s

pointer to source string.

Precondition

must be called in transaction scope.

Exceptions

pmem::pool_error	if an object is not in persistent memory.
pmem::transaction_alloc_error	when allocating memory for underlying storage in transaction failed.
pmem::transaction_scope_error	if 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]	first	iterator to beginning of the range.
[in]	last	iterator to end of the range.

Precondition

must be called in transaction scope.

Exceptions

pmem::pool_error	if an object is not in persistent memory.
pmem::transaction_alloc_error	when allocating memory for underlying storage in transaction failed.
pmem::transaction_scope_error	if 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]

other

reference to the string to be copied.

Precondition

must be called in transaction scope.

Exceptions

pmem::pool_error	if an object is not in persistent memory.
pmem::transaction_alloc_error	when allocating memory for underlying storage in transaction failed.
pmem::transaction_scope_error	if 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]

other

reference to the std::basic_string<CharT> to be copied.

Precondition

must be called in transaction scope.

Exceptions

pmem::pool_error	if an object is not in persistent memory.
pmem::transaction_alloc_error	when allocating memory for underlying storage in transaction failed.
pmem::transaction_scope_error	if 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]

other

rvalue reference to the string to be moved from.

Precondition

must be called in transaction scope.

Exceptions

pmem::pool_error	if an object is not in persistent memory.
pmem::transaction_alloc_error	when allocating memory for underlying storage in transaction failed.
pmem::transaction_scope_error	if 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]

ilist

initializer list with content to be constructed.

Precondition

must be called in transaction scope.

Exceptions

pmem::pool_error	if an object is not in persistent memory.
pmem::transaction_alloc_error	when allocating memory for underlying storage in transaction failed.
pmem::transaction_scope_error	if 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 initializes the string with the content of string view.

Parameters

[in]

t

object (convertible to std::basic_string_view) to initialize the string with.

Precondition

must be called in transaction scope.

Exceptions

pmem::pool_error	if an object is not in persistent memory.
pmem::transaction_alloc_error	when allocating memory for underlying storage in transaction failed.
pmem::transaction_scope_error	if 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 initializes the string with the subrange [pos, pos + n) of string view.

Parameters

[in]	t	object (convertible to std::basic_string_view) to initialize the string with.
[in]	pos	position of the first character to include.
[in]	n	characters to include

Precondition

must be called in transaction scope.

Exceptions

pmem::pool_error	if an object is not in persistent memory.
pmem::transaction_alloc_error	when allocating memory for underlying storage in transaction failed.
pmem::transaction_scope_error	if 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]

n

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

str

string 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_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]	str	string to append.
[in]	pos	index of the first character to append.
[in]	count	characters 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_range	if pos > str.size().
std::length_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]

s

pointer 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_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]	s	pointer to C-style string to append.
[in]	count	characters 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_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]	first	begin of the range of characters to append.
[in]	last	end 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_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]	count	number of characters to append.
[in]	ch	character 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_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]

ilist

initializer 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_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]

other

rvalue reference to the string to be moved from.

Exceptions

pmem::transaction_alloc_error

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

other

reference to the string to be copied.

Exceptions

pmem::transaction_alloc_error

when 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]	other	string from which substring will be copied.
[in]	pos	start position of substring in other.
[in]	count	length of substring.

Exceptions

std::out_of_range	is pos > other.size()
pmem::transaction_alloc_error	when 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]

s

pointer to source string.

Exceptions

pmem::transaction_alloc_error

when 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]	s	pointer to source string.
[in]	count	length of the string.

Exceptions

pmem::transaction_alloc_error

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

other

reference to the std::basic_string<CharT> to be copied.

Exceptions

pmem::transaction_alloc_error

when 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]	other	std::basic_string<CharT> from which substring will be copied.
[in]	pos	start position of substring in other.
[in]	count	length of substring.

Exceptions

std::out_of_range	is pos > other.size()
pmem::transaction_alloc_error	when 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]	first	iterator to beginning of the range.
[in]	last	iterator to end of the range.

Exceptions

pmem::transaction_alloc_error

when 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]	count	number of characters.
[in]	ch	character.

Exceptions

pmem::transaction_alloc_error

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

ilist

initializer_list of characters.

Exceptions

pmem::transaction_alloc_error

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

n

index number.

Returns

reference to element number n in underlying array.

Exceptions

std::out_of_range	if n is not within the range of the container.
pmem::transaction_error	when 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]

n

index number.

Returns

const_reference to element number n in underlying array.

Exceptions

std::out_of_range

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

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

if 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_error	if an object is not in persistent memory.
pmem::transaction_scope_error	if 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_error

if 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_error	when snapshotting failed.
rethrows	destructor 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]

other

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

s

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

other

std::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]	pos	beginning of the substring.
[in]	count	length of the substring.
[in]	other	string 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_range

is 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]	pos	beginning of the substring.
[in]	count	length of the substring.
[in]	s	C-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_range

is 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]	pos	beginning of the substring.
[in]	count	length of the substring.
[in]	other	std::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_range

is 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]	pos	beginning of substring of this.
[in]	count1	length of substring of this.
[in]	s	C-style string to compare to.
[in]	count2	length 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_range

is 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]	pos1	beginning of substring of this.
[in]	count1	length of substring of this.
[in]	other	string to compare to.
[in]	pos2	beginning of substring of other.
[in]	count2	length 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_range

is 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]	pos1	beginning of substring of this.
[in]	count1	length of substring of this.
[in]	other	std::basic_string<CharT> to compare to.
[in]	pos2	beginning of substring of other.
[in]	count2	length 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_range

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

n

index number.

Returns

const_reference to element number n in underlying array.

Exceptions

std::out_of_range

if 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]	s	pointer to destination C-style string.
[in]	count	length of the substring.
[in]	index	start of the substring that will be copied.

Returns

number of copied characters.

Exceptions

std::out_of_range

if 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]	start	start index of requested range.
[in]	n	number of elements in range.

Returns

slice containing elements from <start, start + n).

Exceptions

std::out_of_range

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

when 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]	first	begin of the range of characters to be removed.
[in]	last	end 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_range	if [first, last) is not a valid range of *this.
pmem::transaction_error	when snapshotting failed.
rethrows	destructor 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]

pos

position 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_range	if pos > size().
pmem::transaction_error	when snapshotting failed.
rethrows	destructor 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]	index	first character to remove.
[in]	count	number of characters to remove.

Returns

*this

Precondition

index <= size()

Postcondition

size() = size() - std::min(count, size() - index)

Exceptions

std::out_of_range	if index > size().
pmem::transaction_error	when snapshotting failed.
rethrows	destructor 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

(

T

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

(

T

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]	ch	character to search for
[in]	pos	position 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]	str	string to search for
[in]	pos	position 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]	s	pointer to the C-style string to search for
[in]	pos	position where the search starts from
[in]	count	length 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]	s	pointer to the C-style string to search for
[in]	pos	position 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]	ch	character to search for
[in]	pos	position 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]	str	string identifying characters to search for
[in]	pos	position 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]	s	pointer to the C-style string identifying characters to search for
[in]	pos	position at which to start the search
[in]	count	length 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]	s	pointer to the C-style string identifying characters to search for
[in]	pos	position 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]	ch	character to search for
[in]	pos	position 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]	str	string identifying characters to search for
[in]	pos	position 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]	s	pointer to the C-style string identifying characters to search for
[in]	pos	position at which to start the search
[in]	count	length 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]	s	pointer to the C-style string identifying characters to search for
[in]	pos	position 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]	ch	character to search for
[in]	pos	position 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]	str	string identifying characters to search for
[in]	pos	position 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]	s	pointer to the C-style string identifying characters to search for
[in]	pos	position at which to start the search
[in]	count	length 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]	s	pointer to the C-style string identifying characters to search for
[in]	pos	position 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]	ch	character to search for
[in]	pos	position 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]	str	string identifying characters to search for
[in]	pos	position 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]	s	pointer to the C-style string identifying characters to search for
[in]	pos	position at which to start the search
[in]	count	length 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]	s	pointer to the C-style string identifying characters to search for
[in]	pos	position 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

func	callback 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_error	when snapshotting failed.
pmem::transaction_free_error	when 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_error

when 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]	pos	iterator before which the character will be inserted.
[in]	ch	character 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_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]	pos	iterator before which the character will be inserted.
[in]	first	begin of the range of characters to insert.
[in]	last	end 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_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]	pos	iterator before which the character will be inserted.
[in]	count	number of characters to insert.
[in]	ch	character 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_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]	pos	iterator before which the character will be inserted.
[in]	ilist	initializer 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_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]	index	position at which the content will be inserted.
[in]	str	string 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_range	if index > size().
std::length_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]	index	position at which the content will be inserted.
[in]	s	pointer 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_range	if index > size().
std::length_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]	index	position at which the content will be inserted.
[in]	s	pointer to C-style string to insert.
[in]	count	number 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_range	if index > size().
std::length_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]	index	position at which the content will be inserted
[in]	count	number of characters to insert
[in]	ch	character 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_range	if index > size().
std::length_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]	index1	position at which the content will be inserted.
[in]	str	string to insert.
[in]	index2	position of the first character in str to insert.
[in]	count	number 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_range	if index1 > size() or str.size() > index2.
std::length_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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	(	T	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	(	T	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]

ch

character 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_error	if new_size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]

str

string 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_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]

s

pointer 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_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]

ilist

initializer 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_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]

other

rvalue reference to the string to be moved from.

Exceptions

pmem::transaction_alloc_error

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

ch

character.

Exceptions

pmem::transaction_alloc_error

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

other

reference to the string to be copied.

Exceptions

pmem::transaction_alloc_error

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

s

pointer to source string.

Exceptions

pmem::transaction_alloc_error

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

other

reference to the std::basic_string<CharT> to be copied.

Exceptions

pmem::transaction_alloc_error

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

t

object (convertible to basic_string_view).

Exceptions

pmem::transaction_alloc_error

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

ilist

initializer_list of characters.

Exceptions

pmem::transaction_alloc_error

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

n

index number.

Returns

reference to element number n in underlying array.

Exceptions

pmem::transaction_error

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

n

index 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_error	when snapshotting failed.
rethrows	destructor 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]

ch

character 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_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]	start	start index of requested range.
[in]	n	number of elements in range.

Returns

slice containing elements from <start, start + n).

Exceptions

std::out_of_range	if any element of the range would be outside of the string.
pmem::transaction_error	when 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]	start	start index of requested range.
[in]	n	number of elements in range.

Returns

slice containing elements from <start, start + n).

Exceptions

std::out_of_range

if 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]	start	start index of requested range.
[in]	n	number of elements in range.
[in]	snapshot_size	number 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_range	if any element of the range would be outside of the string.
pmem::transaction_error	when 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]	first	begin of the range of characters that will be replaced.
[in]	last	end of the range of characters that will be replaced.
[in]	str	that 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_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]	first	begin of the range of characters that will be replaced.
[in]	last	end of the range of characters that will be replaced.
[in]	s	pointer 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_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]	first	begin of the range of characters that will be replaced.
[in]	last	end of the range of characters that will be replaced.
[in]	s	pointer to C-style string that will be used for replacement.
[in]	count2	number 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_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]	first	begin of the range of characters that will be replaced.
[in]	last	end of the range of characters that will be replaced.
[in]	first2	begin of the range of characters that will be used for replacement.
[in]	last2	end 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_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]	first	begin of the range of characters that will be replaced.
[in]	last	end of the range of characters that will be replaced.
[in]	count2	number of characters that will be used for replacement.
[in]	ch	character 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_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]	first	begin of the range of characters that will be replaced.
[in]	last	end of the range of characters that will be replaced.
[in]	ilist	initializer 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_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]	index	start of the substring that will be replaced.
[in]	count	length of the substring that will be replaced.
[in]	str	that 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_range	if index > size().
std::length_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]	index	start of the substring that will be replaced.
[in]	count	length of the substring that will be replaced.
[in]	str	that is used for the replacement.
[in]	index2	start of the substring that will be used for replacement.
[in]	count2	length 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_range	if index > size() or index2 > str.size().
std::length_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]	index	start of the substring that will be replaced.
[in]	count	length of the substring that will be replaced.
[in]	s	pointer 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_range	if index > size().
std::length_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]	index	start of the substring that will be replaced.
[in]	count	length of the substring that will be replaced.
[in]	s	pointer to C-style string that will be used for replacement.
[in]	count2	number 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_range	if index > size().
std::length_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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]	index	start of the substring that will be replaced.
[in]	count	length of the substring that will be replaced.
[in]	count2	number of characters that will be used for replacement.
[in]	ch	character 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_range	if index > size().
std::length_error	if new size > max_size().
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor'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_cap

new capacity.

Postcondition

capacity() == max(capacity(), capacity_new)

Exceptions

rethrows	destructor exception.
std::length_error	if new_cap > max_size().
pmem::transaction_error	when snapshotting failed.
pmem::transaction_alloc_error	when allocating new memory failed.
pmem::transaction_free_error	when 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]	count	new size of the container.
[in]	ch	character to initialize elements.

Postcondition

capacity() == std::max(count, capacity())

size() == count

Exceptions

std::length_error	if count > max_size()
rethrows	constructor's exception.
rethrows	destructor exception.
pmem::transaction_error	when snapshotting failed.
pmem::transaction_free_error	when 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]

count

new size of the container.

Postcondition

capacity() == std::max(count, capacity())

size() == count

Exceptions

std::length_error	if count > max_size()
rethrows	constructor's exception.
rethrows	destructor exception.
pmem::transaction_error	when snapshotting failed.
pmem::transaction_free_error	when 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]	ch	character to search for
[in]	pos	position 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]	str	string to search for
[in]	pos	position 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]	s	pointer to the C-style string to search for
[in]	pos	position at which to start the search
[in]	count	length 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]	s	pointer to the C-style string to search for
[in]	pos	position 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_error	when snapshotting failed.
pmem::transaction_alloc_error	when reallocating failed.
pmem::transaction_free_error	when freeing old underlying array failed.
rethrows	constructor's exception.
rethrows	destructor 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_capacity

capacity of constructed large string.

Member Data Documentation

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:

• libpmemobj++/container/basic_string.hpp