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

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

Public Member Functions
	basic_string ()
	Default constructor. More...

	basic_string (size_type count, CharT ch)
	Construct the container with count copies of elements with value ch. More...

	basic_string (const basic_string &other, size_type pos, size_type count=npos)
	Construct the string with a substring [pos, min(pos+count, other.size()) of other. More...

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

	basic_string (const CharT *s, size_type count)
	Construct the string with the first count elements of C-style string s. More...

	basic_string (const CharT *s)
	Construct the string with the contents of s. More...

template<typename InputIt , typename Enable = typename std::enable_if< pmem::detail::is_input_iterator<InputIt>::value>::type>
	basic_string (InputIt first, InputIt last)
	Construct the string with the contents of the range [first, last). More...

	basic_string (const basic_string &other)
	Copy constructor. More...

	basic_string (const std::basic_string< CharT > &other)
	Copy constructor. More...

	basic_string (basic_string &&other)
	Move constructor. More...

	basic_string (std::initializer_list< CharT > ilist)
	Construct the container with the contents of the initializer list init. More...

	~basic_string ()
	Destructor. More...

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

const CharT *	cdata () const noexcept

const CharT *	c_str () const noexcept

iterator	begin ()
	Return an iterator to the beginning. More...

const_iterator	begin () const noexcept
	Return const iterator to the beginning. More...

const_iterator	cbegin () const noexcept
	Return const iterator to the beginning. More...

iterator	end ()
	Return an iterator to past the end. More...

const_iterator	end () const noexcept
	Return const iterator to past the end. More...

const_iterator	cend () const noexcept
	Return const iterator to past the end. More...

reverse_iterator	rbegin ()
	Return a reverse iterator to the beginning. More...

const_reverse_iterator	rbegin () const noexcept
	Return a const reverse iterator to the beginning. More...

const_reverse_iterator	crbegin () const noexcept
	Return a const reverse iterator to the beginning. More...

reverse_iterator	rend ()
	Return a reverse iterator to the end. More...

const_reverse_iterator	rend () const noexcept
	Return a const reverse iterator to the end. More...

const_reverse_iterator	crend () const noexcept
	Return a const reverse iterator to the end. More...

bool	empty () const noexcept

size_type	size () const noexcept

size_type	length () const noexcept

size_type	max_size () const noexcept

size_type	capacity () const noexcept

void	resize (size_type count, CharT ch)
	Resize the string to count characters transactionally. More...

void	resize (size_type n)
	Resize the string to count characters transactionally. More...

void	reserve (size_type new_cap=0)
	Increase the capacity of the string to new_cap transactionally. More...

void	shrink_to_fit ()
	Remove unused capacity transactionally. More...

void	clear ()
	Remove all characters from the string transactionally. More...

basic_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 resulution only if T is not convertible to size_type. 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...

int	compare (const basic_string &other) const
	Compares this string to other. More...

int	compare (const std::basic_string< CharT > &other) const
	Compares this string to std::basic_string<CharT> other. More...

int	compare (size_type pos, size_type count, const basic_string &other) const
	Compares [pos, pos + count) substring of this to other. More...

int	compare (size_type pos, size_type count, const std::basic_string< CharT > &other) const
	Compares [pos, pos + count) substring of this to std::basic_string<CharT> other. More...

int	compare (size_type pos1, size_type count1, const basic_string &other, size_type pos2, size_type count2=npos) const
	Compares [pos1, pos1 + count1) substring of this to [pos2, pos2 + count2) substring of other. More...

int	compare (size_type pos1, size_type count1, const std::basic_string< CharT > &other, size_type pos2, size_type count2=npos) const
	Compares [pos1, pos1 + count1) substring of this to [pos2, pos2 + count2) substring of std::basic_string<CharT> other. More...

int	compare (const CharT *s) const
	Compares this string to s. More...

int	compare (size_type pos, size_type count, const CharT *s) const
	Compares [pos, pos + count) substring of this to s. More...

int	compare (size_type pos, size_type count1, const CharT *s, size_type count2) const
	Compares [pos, pos + count1) substring of this to [s, s + count2) substring of s. More...

template<typename InputIt , typename Enable >
basic_string< CharT, Traits > &	assign (InputIt first, InputIt last)
	Replace the contents with copies of elements in the range [first, last) transactionally. More...

template<typename InputIt , typename Enable >
basic_string< CharT, Traits > &	append (InputIt first, InputIt last)
	Append characters in the range [first, last) transactionally. More...

template<typename T , typename Enable >
basic_string< CharT, Traits > &	erase (T param)
	Participate in overload resulution 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 (Args &&... args)
	Generic function which replaces current content based on provided parameters. More...

template<typename... Args>
pointer	initialize (Args &&... args)
	Generic function which initializes memory based on provided parameters - forwards parameters to initialize function of either non_sso.data or sso.data. More...

void	allocate (size_type capacity)
	Allocate storage for container of capacity bytes. More...

template<typename InputIt , typename Enable = typename std::enable_if< pmem::detail::is_input_iterator<InputIt>::value>::type>
pointer	assign_sso_data (InputIt first, InputIt last)
	Initialize sso data. More...

pointer	assign_sso_data (size_type count, value_type ch)
	Initialize sso data. More...

pointer	assign_sso_data (basic_string &&other)
	Initialize sso data. More...

template<typename InputIt , typename Enable = typename std::enable_if< pmem::detail::is_input_iterator<InputIt>::value>::type>
pointer	assign_large_data (InputIt first, InputIt last)
	Initialize non_sso.data - call constructor of non_sso.data. More...

pointer	assign_large_data (size_type count, value_type ch)
	Initialize non_sso.data - call constructor of non_sso.data. More...

pointer	assign_large_data (basic_string &&other)
	Initialize non_sso.data - call constructor of non_sso.data. More...

pool_base	get_pool () const
	Return pool_base instance and assert that object is on pmem.

void	check_pmem () const

void	check_tx_stage_work () const

void	check_pmem_tx () const

void	snapshot_sso () 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::experimental::basic_string< CharT, Traits >

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

The implementation is NOT complete.

Constructor & Destructor Documentation

◆ basic_string() [1/11]

template<typename CharT , typename Traits >

pmem::obj::experimental::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_error	if constructor wasn't called in transaction.

◆ basic_string() [2/11]

template<typename CharT , typename Traits >

pmem::obj::experimental::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_error	if constructor wasn't called in transaction.

◆ basic_string() [3/11]

template<typename CharT , typename Traits >

pmem::obj::experimental::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_error	if constructor wasn't called in transaction.

◆ basic_string() [4/11]

template<typename CharT , typename Traits >

pmem::obj::experimental::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_error	if constructor wasn't called in transaction.

◆ basic_string() [5/11]

template<typename CharT , typename Traits >

pmem::obj::experimental::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_error	if constructor wasn't called in transaction.

◆ basic_string() [6/11]

template<typename CharT , typename Traits >

pmem::obj::experimental::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_error	if constructor wasn't called in transaction.

◆ basic_string() [7/11]

template<typename CharT , typename Traits >

template<typename InputIt , typename Enable >

pmem::obj::experimental::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_error	if constructor wasn't called in transaction.

◆ basic_string() [8/11]

template<typename CharT , typename Traits >

pmem::obj::experimental::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_error	if constructor wasn't called in transaction.

◆ basic_string() [9/11]

template<typename CharT , typename Traits >

pmem::obj::experimental::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_error	if constructor wasn't called in transaction.

◆ basic_string() [10/11]

template<typename CharT , typename Traits >

pmem::obj::experimental::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_error	if constructor wasn't called in transaction.

◆ basic_string() [11/11]

template<typename CharT , typename Traits >

pmem::obj::experimental::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_error	if constructor wasn't called in transaction.

◆ ~basic_string()

template<typename CharT , typename Traits >

pmem::obj::experimental::basic_string< CharT, Traits >::~basic_string

Destructor.

XXX: implement free_data()

Member Function Documentation

◆ allocate()

template<typename CharT , typename Traits >

void pmem::obj::experimental::basic_string< CharT, Traits >::allocate ( size_type capacity )

private

Allocate storage for container of capacity bytes.

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

Precondition: data must be uninitialized.; must be called in transaction scope.

Parameters

[in] capacity bytes to allocate.

◆ append() [1/7]

template<typename CharT , typename Traits >

basic_string< CharT, Traits > & pmem::obj::experimental::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 exception.

◆ append() [2/7]

template<typename CharT , typename Traits >

basic_string< CharT, Traits > & pmem::obj::experimental::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 exception.

◆ append() [3/7]

template<typename CharT , typename Traits >

basic_string< CharT, Traits > & pmem::obj::experimental::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 exception.

◆ append() [4/7]

template<typename CharT , typename Traits >

basic_string< CharT, Traits > & pmem::obj::experimental::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 exception.

◆ append() [5/7]

template<typename CharT , typename Traits = std::char_traits<CharT>>

template<typename InputIt , typename Enable >

basic_string<CharT, Traits>& pmem::obj::experimental::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 exception.

◆ append() [6/7]

template<typename CharT , typename Traits >

basic_string< CharT, Traits > & pmem::obj::experimental::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 exception.

◆ append() [7/7]

template<typename CharT , typename Traits >

basic_string< CharT, Traits > & pmem::obj::experimental::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 exception.

◆ assign() [1/10]

template<typename CharT , typename Traits >

basic_string< CharT, Traits > & pmem::obj::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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::experimental::basic_string< CharT, Traits >::assign ( std::initializer_list< CharT > ilist )

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

template<typename CharT , typename Traits >

basic_string< CharT, Traits >::pointer pmem::obj::experimental::basic_string< CharT, Traits >::assign_large_data ( basic_string< CharT, Traits > && other )

private

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

Overload for rvalue reference of basic_string.

◆ assign_large_data() [2/3]

template<typename CharT , typename Traits >

template<typename InputIt , typename Enable >

basic_string< CharT, Traits >::pointer pmem::obj::experimental::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() [3/3]

template<typename CharT , typename Traits >

basic_string< CharT, Traits >::pointer pmem::obj::experimental::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/3]

template<typename CharT , typename Traits >

basic_string< CharT, Traits >::pointer pmem::obj::experimental::basic_string< CharT, Traits >::assign_sso_data ( basic_string< CharT, Traits > && other )

private

Initialize sso data.

Overload for rvalue reference of basic_string.

◆ assign_sso_data() [2/3]

template<typename CharT , typename Traits >

template<typename InputIt , typename Enable >

basic_string< CharT, Traits >::pointer pmem::obj::experimental::basic_string< CharT, Traits >::assign_sso_data	(	InputIt	first,
		InputIt	last
	)

private

Initialize sso data.

Overload for pair of iterators

◆ assign_sso_data() [3/3]

template<typename CharT , typename Traits >

basic_string< CharT, Traits >::pointer pmem::obj::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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::experimental::basic_string< CharT, Traits >::check_pmem_tx

private

Exceptions

pmem::pool_error	if an object is not in persistent memory.
pmem::transaction_error	if called outside of a transaction.

◆ check_tx_stage_work()

template<typename CharT , typename Traits >

void pmem::obj::experimental::basic_string< CharT, Traits >::check_tx_stage_work

private

Exceptions

pmem::transaction_error if called outside of a transaction.

◆ clear()

template<typename CharT , typename Traits >

void pmem::obj::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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.

◆ crbegin()

template<typename CharT , typename Traits >

basic_string< CharT, Traits >::const_reverse_iterator pmem::obj::experimental::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::experimental::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.

◆ empty()

template<typename CharT , typename Traits >

bool pmem::obj::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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::experimental::basic_string< CharT, Traits >::erase ( T param )

Participate in overload resulution 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::experimental::basic_string< CharT, Traits >::erase ( T param )

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

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

◆ front() [1/2]

template<typename CharT , typename Traits >

CharT & pmem::obj::experimental::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::experimental::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::experimental::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::experimental::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::experimental::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::experimental::basic_string< CharT, Traits >::initialize ( Args &&... args )

private

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

Allowed parameters are:

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

Precondition: must be called in transaction scope.; memory must be allocated before initialization.

◆ large_to_sso()

template<typename CharT , typename Traits >

void pmem::obj::experimental::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::experimental::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::experimental::basic_string< CharT, Traits >::max_size

noexcept

Returns: maximum number of elements the string is able to hold.

◆ operator=() [1/6]

template<typename CharT , typename Traits >

basic_string< CharT, Traits > & pmem::obj::experimental::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/6]

template<typename CharT , typename Traits >

basic_string< CharT, Traits > & pmem::obj::experimental::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/6]

template<typename CharT , typename Traits >

basic_string< CharT, Traits > & pmem::obj::experimental::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/6]

template<typename CharT , typename Traits >

basic_string< CharT, Traits > & pmem::obj::experimental::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/6]

template<typename CharT , typename Traits >

basic_string< CharT, Traits > & pmem::obj::experimental::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/6]

template<typename CharT , typename Traits >

basic_string< CharT, Traits > & pmem::obj::experimental::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::experimental::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::experimental::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.

◆ rbegin() [1/2]

template<typename CharT , typename Traits >

basic_string< CharT, Traits >::reverse_iterator pmem::obj::experimental::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::experimental::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::experimental::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::experimental::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()

template<typename CharT , typename Traits >

template<typename... Args>

basic_string< CharT, Traits >::pointer pmem::obj::experimental::basic_string< CharT, Traits >::replace ( Args &&... args )

private

Generic function which replaces current content based on provided parameters.

Allowed parameters are:

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

◆ reserve()

template<typename CharT , typename Traits >

void pmem::obj::experimental::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::experimental::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 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::experimental::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 exception.
rethrows	destructor exception.
pmem::transaction_error	when snapshotting failed.
pmem::transaction_free_error	when freeing old underlying array failed.

◆ shrink_to_fit()

template<typename CharT , typename Traits >

void pmem::obj::experimental::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 exception.
rethrows	destructor exception.

◆ size()

template<typename CharT , typename Traits >

basic_string< CharT, Traits >::size_type pmem::obj::experimental::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::experimental::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

◆ @3

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.

◆ data

template<typename CharT , typename Traits >

const CharT * pmem::obj::experimental::basic_string< CharT, Traits >::data

noexcept

Returns: pointer to underlying data.

Exceptions

transaction_error when adding data to the transaction failed.

Returns: pointer to underlying data.

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

libpmemobj++/experimental/basic_string.hpp

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

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

Constructor & Destructor Documentation

◆ basic_string() [1/11]

◆ basic_string() [2/11]

◆ basic_string() [3/11]

◆ basic_string() [4/11]

◆ basic_string() [5/11]

◆ basic_string() [6/11]

◆ basic_string() [7/11]

◆ basic_string() [8/11]

◆ basic_string() [9/11]

◆ basic_string() [10/11]

◆ basic_string() [11/11]

◆ ~basic_string()

Member Function Documentation

◆ allocate()

◆ append() [1/7]

◆ append() [2/7]

◆ append() [3/7]

◆ append() [4/7]

◆ append() [5/7]

◆ append() [6/7]

◆ append() [7/7]

◆ assign() [1/10]

◆ assign() [2/10]

◆ assign() [3/10]

◆ assign() [4/10]

◆ assign() [5/10]

◆ assign() [6/10]

◆ assign() [7/10]

◆ assign() [8/10]

◆ assign() [9/10]

◆ assign() [10/10]

◆ assign_large_data() [1/3]

◆ assign_large_data() [2/3]

◆ assign_large_data() [3/3]

◆ assign_sso_data() [1/3]

◆ assign_sso_data() [2/3]

◆ assign_sso_data() [3/3]

◆ at() [1/2]

◆ at() [2/2]

◆ back() [1/2]

◆ back() [2/2]

◆ begin() [1/2]

◆ begin() [2/2]

◆ c_str()

◆ capacity()

◆ cback()

◆ cbegin()

◆ cdata()

◆ cend()

◆ cfront()

◆ check_pmem()

◆ check_pmem_tx()

◆ check_tx_stage_work()

◆ clear()

◆ compare() [1/9]

◆ compare() [2/9]

◆ compare() [3/9]

◆ compare() [4/9]

◆ compare() [5/9]

◆ compare() [6/9]

◆ compare() [7/9]

◆ compare() [8/9]

◆ compare() [9/9]

◆ const_at()

◆ crbegin()

◆ crend()

◆ empty()

◆ end() [1/2]

◆ end() [2/2]

◆ erase() [1/5]

◆ erase() [2/5]

◆ erase() [3/5]

◆ erase() [4/5]

◆ erase() [5/5]

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