PMDK C++ bindings  1.10.1
This is the C++ bindings documentation for PMDK's libpmemobj.
Public Member Functions | Private Member Functions | List of all members
pmem::obj::vector< T > Class Template Reference

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

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

Public Member Functions

 vector ()
 Default constructor. More...
 
 vector (size_type count, const value_type &value)
 Constructs the container with count copies of elements with value value. More...
 
 vector (size_type count)
 Constructs the container with count copies of T default constructed values. More...
 
template<typename InputIt , typename std::enable_if< detail::is_input_iterator< InputIt >::value, InputIt >::type * = nullptr>
 vector (InputIt first, InputIt last)
 Constructs the container with the contents of the range [first, last). More...
 
 vector (const vector &other)
 Copy constructor. More...
 
 vector (vector &&other)
 Move constructor. More...
 
 vector (std::initializer_list< T > init)
 Constructs the container with the contents of the initializer list init. More...
 
 vector (const std::vector< T > &other)
 Copy constructor. More...
 
vectoroperator= (const vector &other)
 Copy assignment operator. More...
 
vectoroperator= (vector &&other)
 Move assignment operator. More...
 
vectoroperator= (std::initializer_list< T > ilist)
 Replaces the contents with those identified by initializer list ilist transactionally. More...
 
vectoroperator= (const std::vector< T > &other)
 Copy assignment operator. More...
 
template<typename InputIt , typename std::enable_if< detail::is_input_iterator< InputIt >::value, InputIt >::type * = nullptr>
void assign (InputIt first, InputIt last)
 Replaces the contents with copies of those in the range [first, last) transactionally. More...
 
void assign (std::initializer_list< T > ilist)
 Replaces the contents with the elements from the initializer list ilist transactionally. More...
 
void assign (const vector &other)
 Copy assignment method. More...
 
void assign (vector &&other)
 Move assignment method. More...
 
void assign (const std::vector< T > &other)
 Copy assignment method. More...
 
 ~vector ()
 Destructor. More...
 
reference at (size_type n)
 Access element at specific index with bounds checking and add it to a 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 add it to a transaction. More...
 
const_reference operator[] (size_type n) const
 Access element at specific index. More...
 
reference front ()
 Access the first element and add this element to a transaction. More...
 
const_reference front () const
 Access the first element. More...
 
const_reference cfront () const
 Access the first element. More...
 
reference back ()
 Access the last element and add this element to a transaction. More...
 
const_reference back () const
 Access the last element. More...
 
const_reference cback () const
 Access the last element. More...
 
value_type * data ()
 Returns raw pointer to the underlying data and adds entire array to a transaction. More...
 
const value_type * data () const noexcept
 Returns const raw pointer to the underlying data. More...
 
const value_type * cdata () const noexcept
 Returns const raw pointer to the underlying data. More...
 
iterator begin ()
 Returns an iterator to the beginning. More...
 
const_iterator begin () const noexcept
 Returns const iterator to the beginning. More...
 
const_iterator cbegin () const noexcept
 Returns const iterator to the beginning. More...
 
iterator end ()
 Returns an iterator to past the end. More...
 
const_iterator end () const noexcept
 Returns a const iterator to past the end. More...
 
const_iterator cend () const noexcept
 Returns a const iterator to the end. More...
 
reverse_iterator rbegin ()
 Returns a reverse iterator to the beginning. More...
 
const_reverse_iterator rbegin () const noexcept
 Returns a const reverse iterator to the beginning. More...
 
const_reverse_iterator crbegin () const noexcept
 Returns a const reverse iterator to the beginning. More...
 
reverse_iterator rend ()
 Returns a reverse iterator to the end. More...
 
const_reverse_iterator rend () const noexcept
 Returns a const reverse iterator to the end. More...
 
const_reverse_iterator crend () const noexcept
 Returns a const reverse iterator to the beginning. More...
 
slice< pointer > range (size_type start, size_type n)
 Returns slice and snapshots requested range. More...
 
slice< range_snapshotting_iteratorrange (size_type start, size_type n, size_type snapshot_size)
 Returns slice. More...
 
slice< const_iterator > range (size_type start, size_type n) const
 Returns const slice. More...
 
slice< const_iterator > crange (size_type start, size_type n) const
 Returns const slice. More...
 
void for_each_ptr (for_each_ptr_function func)
 Iterates over all internal pointers and executes a callback function on each of them. More...
 
constexpr bool empty () const noexcept
 Checks whether the container is empty. More...
 
size_type size () const noexcept
 
constexpr size_type max_size () const noexcept
 
void reserve (size_type capacity_new)
 Increases the capacity of the vector to capacity_new transactionally. More...
 
size_type capacity () const noexcept
 
void shrink_to_fit ()
 Requests transactional removal of unused capacity. More...
 
void clear ()
 Clears the content of a vector transactionally. More...
 
void free_data ()
 Clears the content of a vector and frees all allocated persistent memory for data transactionally. More...
 
iterator insert (const_iterator pos, const T &value)
 Inserts value before pos in the container transactionally. More...
 
iterator insert (const_iterator pos, T &&value)
 Moves value before pos in the container transactionally. More...
 
iterator insert (const_iterator pos, size_type count, const T &value)
 Inserts count copies of the value before pos in the container transactionally. More...
 
template<typename InputIt , typename std::enable_if< detail::is_input_iterator< InputIt >::value, InputIt >::type * = nullptr>
iterator insert (const_iterator pos, InputIt first, InputIt last)
 Inserts elements from range [first, last) before pos in the container transactionally. More...
 
iterator insert (const_iterator pos, std::initializer_list< T > ilist)
 Inserts elements from initializer list ilist before pos in the container transactionally. More...
 
template<class... Args>
iterator emplace (const_iterator pos, Args &&... args)
 Inserts a new element into the container directly before pos. More...
 
template<class... Args>
reference emplace_back (Args &&... args)
 Appends a new element to the end of the container. More...
 
iterator erase (const_iterator pos)
 Removes the element at pos. More...
 
iterator erase (const_iterator first, const_iterator last)
 Removes the elements in the range [first, last). More...
 
void push_back (const T &value)
 Appends the given element value to the end of the container transactionally. More...
 
void push_back (T &&value)
 Appends the given element value to the end of the container transactionally. More...
 
void pop_back ()
 Removes the last element of the container transactionally. More...
 
void resize (size_type count)
 Resizes the container to count elements transactionally. More...
 
void resize (size_type count, const value_type &value)
 Resizes the container to contain count elements transactionally. More...
 
void swap (vector &other)
 Exchanges the contents of the container with other transactionally.
 
template<typename T >
void assign (size_type count, const_reference value)
 Replaces the contents with count copies of value value transactionally. More...
 

Private Member Functions

void alloc (size_type size)
 Private helper function. More...
 
void check_pmem ()
 Private helper function. More...
 
void check_tx_stage_work ()
 Private helper function. More...
 
template<typename... Args>
void construct_at_end (size_type count, Args &&... args)
 Private helper function. More...
 
template<typename InputIt , typename std::enable_if< detail::is_input_iterator< InputIt >::value, InputIt >::type * = nullptr>
void construct_at_end (InputIt first, InputIt last)
 Private helper function. More...
 
void dealloc ()
 Private helper function. More...
 
pool_base get_pool () const noexcept
 Private helper function. More...
 
template<typename InputIt >
void internal_insert (size_type idx, InputIt first, InputIt last)
 Private helper function. More...
 
void realloc (size_type size)
 Private helper function. More...
 
size_type get_recommended_capacity (size_type at_least) const
 Private helper function. More...
 
void shrink (size_type size_new)
 Private helper function. More...
 
void add_data_to_tx (size_type idx_first, size_type num)
 Private helper function. More...
 
template<typename InputIt >
void construct_or_assign (size_type idx, InputIt first, InputIt last)
 Private helper function. More...
 
void move_elements_backward (pointer first, pointer last, pointer d_last)
 Private helper function. More...
 

Detailed Description

template<typename T>
class pmem::obj::vector< T >

pmem::obj::vector - persistent container with std::vector compatible interface.

Constructor & Destructor Documentation

◆ vector() [1/8]

template<typename T >
pmem::obj::vector< T >::vector

Default constructor.

Constructs an empty container.

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

◆ vector() [2/8]

template<typename T >
pmem::obj::vector< T >::vector ( size_type  count,
const value_type &  value 
)

Constructs the container with count copies of elements with value value.

Parameters
[in]countnumber of elements to construct.
[in]valuevalue of all constructed elements.
Precondition
must be called in transaction scope.
Postcondition
size() == count
capacity() == size()
Exceptions
pmem::pool_errorif an object is not in persistent memory.
pmem::transaction_alloc_errorwhen allocating memory for underlying array in transaction failed.
pmem::transaction_scope_errorif constructor wasn't called in transaction.
rethrowselement constructor exception.

◆ vector() [3/8]

template<typename T >
pmem::obj::vector< T >::vector ( size_type  count)
explicit

Constructs the container with count copies of T default constructed values.

Parameters
[in]countnumber of elements to construct.
Precondition
must be called in transaction scope.
Postcondition
size() == count
capacity() == size()
Exceptions
pmem::pool_errorif an object is not in persistent memory.
pmem::transaction_alloc_errorwhen allocating memory for underlying array in transaction failed.
pmem::transaction_scope_errorif constructor wasn't called in transaction.
rethrowselement constructor exception.

◆ vector() [4/8]

template<typename T >
template<typename InputIt , typename std::enable_if< detail::is_input_iterator< InputIt >::value, InputIt >::type * >
pmem::obj::vector< T >::vector ( InputIt  first,
InputIt  last 
)

Constructs the container with the contents of the range [first, last).

The first and last arguments must satisfy InputIterator requirements. This overload only participates in overload resolution if InputIt satisfies InputIterator, to avoid ambiguity with the overload of count-value constructor.

Parameters
[in]firstfirst iterator.
[in]lastlast iterator.
Precondition
must be called in transaction scope.
Postcondition
size() == std::distance(first, last)
capacity() == size()
Exceptions
pmem::pool_errorif an object is not in persistent memory.
pmem::transaction_alloc_errorwhen allocating memory for underlying array in transaction failed.
pmem::transaction_scope_errorif constructor wasn't called in transaction.
rethrowselement constructor exception.

◆ vector() [5/8]

template<typename T >
pmem::obj::vector< T >::vector ( const vector< T > &  other)

Copy constructor.

Constructs the container with the copy of the contents of other.

Parameters
[in]otherreference to the vector to be copied.
Precondition
must be called in transaction scope.
Postcondition
size() == other.size()
capacity() == other.capacity()
Exceptions
pmem::pool_errorif an object is not in persistent memory.
pmem::transaction_alloc_errorwhen allocating memory for underlying array in transaction failed.
pmem::transaction_scope_errorif constructor wasn't called in transaction.
rethrowselement constructor exception.

◆ vector() [6/8]

template<typename T >
pmem::obj::vector< T >::vector ( vector< T > &&  other)

Move constructor.

Constructs the container with the contents of other using move semantics. After the move, other is guaranteed to be empty().

Parameters
[in]otherrvalue reference to the vector to be moved from.
Precondition
must be called in transaction scope.
Postcondition
size() == other.size()
capacity() == other.capacity()
data() == other.data()
other.data() == nullptr
other.capacity() == 0
other.size() == 0
Exceptions
pmem::pool_errorif an object is not in persistent memory.
pmem::transaction_scope_errorif constructor wasn't called in transaction.

◆ vector() [7/8]

template<typename T >
pmem::obj::vector< T >::vector ( std::initializer_list< T >  init)

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

Parameters
[in]initinitializer list with content to be constructed.
Precondition
must be called in transaction scope.
Postcondition
size() == init.size()
capacity() == size()
Exceptions
pmem::pool_errorif an object is not in persistent memory.
pmem::transaction_alloc_errorwhen allocating memory for underlying array in transaction failed.
pmem::transaction_scope_errorif constructor wasn't called in transaction.
rethrowselement constructor exception.

◆ vector() [8/8]

template<typename T >
pmem::obj::vector< T >::vector ( const std::vector< T > &  other)

Copy constructor.

Constructs the container with the copy of the contents of std::vector<T> other. This constructor is not specified by STL standards.

Parameters
[in]otherreference to the vector to be copied.
Precondition
must be called in transaction scope.
Postcondition
size() == other.size()
capacity() == other.capacity()
Exceptions
pmem::pool_errorif an object is not in persistent memory.
pmem::transaction_alloc_errorwhen allocating memory for underlying array in transaction failed.
pmem::transaction_scope_errorif constructor wasn't called in transaction.
rethrowselement constructor exception.

◆ ~vector()

template<typename T >
pmem::obj::vector< T >::~vector

Destructor.

Note that free_data may throw a transaction_free_error when freeing underlying array failed. It is recommended to call free_data manually before object destruction, otherwise application can be terminated on failure.

Member Function Documentation

◆ add_data_to_tx()

template<typename T >
void pmem::obj::vector< T >::add_data_to_tx ( size_type  idx_first,
size_type  num 
)
private

Private helper function.

Takes a “snapshot” of data in range [&_data[idx_first], &_data[idx_first + num])

Parameters
[in]idx_firstfirst index.
[in]numnumber of elements to snapshot.
Exceptions
pmem::transaction_errorwhen snapshotting failed.

◆ alloc()

template<typename T >
void pmem::obj::vector< T >::alloc ( size_type  capacity_new)
private

Private helper function.

Must be called during transaction. Allocates memory for given number of elements.

Parameters
[in]capacity_newcapacity of new underlying array.
Precondition
must be called in transaction scope.
data() == nullptr
size() == 0
Postcondition
capacity() == capacity_new
Exceptions
std::length_errorif new size exceeds biggest possible pmem allocation.
pmem::transaction_alloc_errorwhen allocating memory for underlying array in transaction failed.

◆ assign() [1/6]

template<typename T >
void pmem::obj::vector< T >::assign ( const std::vector< T > &  other)

Copy assignment method.

Replaces the contents with a copy of the contents of std::vector<T> other transactionally. This method is not specified by STL standards.

Postcondition
size() == other.size()
capacity() == max(size(), other.capacity())
Exceptions
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor's exception.

◆ assign() [2/6]

template<typename T >
void pmem::obj::vector< T >::assign ( const vector< T > &  other)

Copy assignment method.

Replaces the contents with a copy of the contents of other transactionally. This method is not specified by STL standards.

Postcondition
size() == other.size()
capacity() == max(size(), other.capacity())
Exceptions
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor's exception.

◆ assign() [3/6]

template<typename T >
template<typename InputIt , typename std::enable_if< detail::is_input_iterator< InputIt >::value, InputIt >::type * >
void pmem::obj::vector< T >::assign ( InputIt  first,
InputIt  last 
)

Replaces the contents with copies of those in the range [first, last) transactionally.

This overload participates in overload resolution only if InputIt satisfies InputIterator. All iterators, pointers and references to the elements of the container are invalidated. The past-the-end iterator is also invalidated.

Parameters
[in]firstfirst iterator.
[in]lastlast iterator.
Postcondition
size() == std::distance(first, last)
capacity() == max(size(), std::distance(first, last))
Exceptions
std::length_errorif std::distance(first, last) > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor's exception.

◆ assign() [4/6]

template<typename T >
template<typename T >
void pmem::obj::vector< T >::assign ( size_type  count,
const_reference  value 
)

Replaces the contents with count copies of value value transactionally.

All iterators, pointers and references to the elements of the container are invalidated. The past-the-end iterator is also invalidated.

Parameters
[in]countnumber of elements to construct.
[in]valuevalue of all constructed elements.
Postcondition
size() == count
capacity() == max(size(), count)
Exceptions
std::length_errorif count > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor's exception.

◆ assign() [5/6]

template<typename T >
void pmem::obj::vector< T >::assign ( std::initializer_list< T >  ilist)

Replaces the contents with the elements from the initializer list ilist transactionally.

All iterators, pointers and references to the elements of the container are invalidated. The past-the-end iterator is also invalidated.

Parameters
[in]ilistinitializer list with content to be constructed.
Postcondition
size() == std::distance(ilist.begin(), ilist.end())
capacity() == max(size(), capacity())
Exceptions
std::length_errorif std::distance(first, last) > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor's exception.

◆ assign() [6/6]

template<typename T >
void pmem::obj::vector< T >::assign ( vector< T > &&  other)

Move assignment method.

Replaces the contents with those of other using move semantics (i.e. the data in other is moved from other into this container) transactionally. Other is in a valid but empty state afterwards. This method is not specified by STL standards.

Postcondition
size() == other.size()
capacity() == other.capacity()
Exceptions
pmem::transaction_free_errorwhen freeing underlying array failed.

◆ at() [1/2]

template<typename T >
vector< T >::reference pmem::obj::vector< T >::at ( size_type  n)

Access element at specific index with bounds checking and add it to a transaction.

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

◆ at() [2/2]

template<typename T >
vector< T >::const_reference pmem::obj::vector< T >::at ( size_type  n) const

Access element at specific index with bounds checking.

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

◆ back() [1/2]

template<typename T >
vector< T >::reference pmem::obj::vector< T >::back

Access the last element and add this element to a transaction.

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

◆ back() [2/2]

template<typename T >
vector< T >::const_reference pmem::obj::vector< T >::back

Access the last element.

Returns
const_reference to the last element in underlying array.

◆ begin() [1/2]

template<typename T >
vector< T >::iterator pmem::obj::vector< T >::begin

Returns an iterator to the beginning.

Returns
iterator pointing to the first element in the vector.

◆ begin() [2/2]

template<typename T >
vector< T >::const_iterator pmem::obj::vector< T >::begin
noexcept

Returns const iterator to the beginning.

Returns
const_iterator pointing to the first element in the vector.

◆ capacity()

template<typename T >
vector< T >::size_type pmem::obj::vector< T >::capacity
noexcept
Returns
number of elements that can be held in currently allocated storage

◆ cback()

template<typename T >
vector< T >::const_reference pmem::obj::vector< T >::cback

Access the 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::vector doesn't provide cback() method.

Returns
const_reference to the last element in underlying array.

◆ cbegin()

template<typename T >
vector< T >::const_iterator pmem::obj::vector< T >::cbegin
noexcept

Returns const iterator to the beginning.

In contradiction to begin(), cbegin() will return const_iterator not depending on the const-qualification of the object it is called on.

Returns
const_iterator pointing to the first element in the vector.

◆ cdata()

template<typename T >
const vector< T >::value_type * pmem::obj::vector< T >::cdata
noexcept

Returns const raw pointer to the underlying data.

In contradiction to data(), cdata() will return const_pointer not depending on the const-qualification of the object it is called on. std::vector doesn't provide cdata() method.

Returns
const_pointer to the underlying data.

◆ cend()

template<typename T >
vector< T >::const_iterator pmem::obj::vector< T >::cend
noexcept

Returns a const iterator to the end.

In contradiction to end(), cend() will return const_iterator not depending on the const-qualification of the object it is called on.

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

◆ cfront()

template<typename T >
vector< T >::const_reference pmem::obj::vector< T >::cfront

Access the 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::vector doesn't provide cfront() method.

Returns
reference to first element in underlying array.

◆ check_pmem()

template<typename T >
void pmem::obj::vector< T >::check_pmem
private

Private helper function.

Checks if vector resides on pmem and throws an exception if not.

Exceptions
pool_errorif vector doesn't reside on pmem.

◆ check_tx_stage_work()

template<typename T >
void pmem::obj::vector< T >::check_tx_stage_work
private

Private helper function.

Checks if current transaction stage is equal to TX_STAGE_WORK and throws an exception otherwise.

Exceptions
pmem::transaction_scope_errorif current transaction stage is not equal to TX_STAGE_WORK.

◆ clear()

template<typename T >
void pmem::obj::vector< T >::clear

Clears the content of a vector transactionally.

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

◆ const_at()

template<typename T >
vector< T >::const_reference pmem::obj::vector< T >::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::vector doesn't provide const_at() method.

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

◆ construct_at_end() [1/2]

template<typename T >
template<typename InputIt , typename std::enable_if< detail::is_input_iterator< InputIt >::value, InputIt >::type * >
void pmem::obj::vector< T >::construct_at_end ( InputIt  first,
InputIt  last 
)
private

Private helper function.

Must be called during transaction. Assumes that there is free space for additional elements and input arguments satisfy InputIterator requirements. Copies elements at index size() in underlying array with the contents of the range [first, last). This overload participates in overload resolution only if InputIt satisfies InputIterator.

Parameters
[in]firstfirst iterator.
[in]lastlast iterator.
Precondition
must be called in transaction scope.
if initialized, range [end(), end() + std::distance(first, last)) must be snapshotted in current transaction.
capacity() >= std::distance(first, last) + size()
InputIt is InputIterator.
InputIt::reference is valid argument for value_type constructor.
Postcondition
size() == size() + std::distance(first, last)
Exceptions
rethrowsconstructor's exception.

◆ construct_at_end() [2/2]

template<typename T >
template<typename... Args>
void pmem::obj::vector< T >::construct_at_end ( size_type  count,
Args &&...  args 
)
private

Private helper function.

Must be called during transaction. Assumes that there is free space for additional elements. Constructs elements at index size() in underlying array based on given parameters.

Parameters
[in]countnumber of elements to be constructed.
[in]argsvariadic template arguments for value_type constructor.
Precondition
must be called in transaction scope.
if initialized, range [end(), end() + count) must be snapshotted in current transaction.
capacity() >= count + size()
args is valid argument for value_type constructor.
Postcondition
size() == size() + count
Exceptions
rethrowsconstructor's exception.

◆ construct_or_assign()

template<typename T >
template<typename InputIt >
void pmem::obj::vector< T >::construct_or_assign ( size_type  idx,
InputIt  first,
InputIt  last 
)
private

Private helper function.

It behaves similarly to std::move_backward but uses either copy constructor in case destination memory is not initialized or copy assignment operator otherwise.

◆ crange()

template<typename T >
slice< typename vector< T >::const_iterator > pmem::obj::vector< T >::crange ( size_type  start,
size_type  n 
) const

Returns const slice.

This method is not specified by STL standards.

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

◆ crbegin()

template<typename T >
vector< T >::const_reverse_iterator pmem::obj::vector< T >::crbegin
noexcept

Returns a const reverse iterator to the beginning.

In contradiction to rbegin(), crbegin() will return const_reverse_iterator not depending on the const-qualification of the object it is called on.

Returns
const_reverse_iterator pointing to the last element in the vector.

◆ crend()

template<typename T >
vector< T >::const_reverse_iterator pmem::obj::vector< T >::crend
noexcept

Returns a const reverse iterator to the beginning.

In contradiction to rend(), crend() will return const_reverse_iterator not depending on the const-qualification of the object it is called on.

Returns
const_reverse_iterator pointing to the theoretical element preceding the first element in the vector.

◆ data() [1/2]

template<typename T >
vector< T >::value_type * pmem::obj::vector< T >::data

Returns raw pointer to the underlying data and adds entire array to a transaction.

Returns
pointer to the underlying data.
Exceptions
pmem::transaction_errorwhen adding the object to the transaction failed.

◆ data() [2/2]

template<typename T >
const vector< T >::value_type * pmem::obj::vector< T >::data
noexcept

Returns const raw pointer to the underlying data.

Returns
const_pointer to the underlying data.

◆ dealloc()

template<typename T >
void pmem::obj::vector< T >::dealloc
private

Private helper function.

Must be called during transaction. Deallocates underlying array.

Precondition
must be called in transaction scope.
Postcondition
size() == 0
capacity() == 0
data() == nullptr
Exceptions
pmem::transaction_errorwhen snapshotting failed.
rethrowsdestructor exception.
pmem::transaction_free_errorwhen freeing old underlying array failed.

◆ emplace()

template<typename T >
template<class... Args>
vector< T >::iterator pmem::obj::vector< T >::emplace ( const_iterator  pos,
Args &&...  args 
)

Inserts a new element into the container directly before pos.

The element is constructed in-place. The arguments args... are forwarded to the constructor as std::forward<Args>(args).... If the new size() is greater than capacity(), all iterators and references are invalidated. Otherwise, only the iterators and references before the insertion point remain valid. The past-the-end iterator is also invalidated. Note that standard allows args to be a self reference and internal emplace implementation handles this case by creating temporary element_type object. This object is being stored either on stack or on pmem, see pmem::detail::temp_value for details.

Parameters
[in]positerator before which the new element will be constructed.
[in]argsarguments to forward to the constructor of the element.
Returns
Iterator pointing to the emplaced element.
Precondition
value_type must meet the requirements of MoveAssignable, MoveInsertable and EmplaceConstructible.
Postcondition
capacity() is equal to the smallest next power of 2, bigger than old capacity, or remains the same if there is enough space to add single element.
Exceptions
pmem::transaction_errorwhen snapshotting failed.
rethrowsconstructor's exception.
rethrowsdestructor exception.
pmem::transaction_free_errorwhen freeing old underlying array failed.

◆ emplace_back()

template<typename T >
template<class... Args>
vector< T >::reference pmem::obj::vector< T >::emplace_back ( Args &&...  args)

Appends a new element to the end of the container.

The element is constructed in-place. The arguments args... are forwarded to the constructor as std::forward<Args>(args).... If the new size() is greater than capacity() then all iterators and references (including the past-the-end iterator) are invalidated. Otherwise only the past-the-end iterator is invalidated.

Parameters
[in]argsarguments to forward to the constructor of the element.
Returns
Iterator pointing to the emplaced element.
Precondition
value_type must meet the requirements of MoveInsertable and EmplaceConstructible.
Postcondition
capacity() is equal to the smallest next power of 2, bigger than old capacity, or remains the same if there is enough space to add single element.
Exceptions
pmem::transaction_errorwhen snapshotting failed.
rethrowsconstructor's exception.
rethrowsdestructor exception.
pmem::transaction_free_errorwhen freeing old underlying array failed.

◆ empty()

template<typename T >
constexpr bool pmem::obj::vector< T >::empty
constexprnoexcept

Checks whether the container is empty.

Returns
true if container is empty, false otherwise.

◆ end() [1/2]

template<typename T >
vector< T >::iterator pmem::obj::vector< T >::end

Returns an iterator to past the end.

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

◆ end() [2/2]

template<typename T >
vector< T >::const_iterator pmem::obj::vector< T >::end
noexcept

Returns a const iterator to past the end.

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

◆ erase() [1/2]

template<typename T >
vector< T >::iterator pmem::obj::vector< T >::erase ( const_iterator  first,
const_iterator  last 
)

Removes the elements in the range [first, last).

Invalidates iterators and references at or after the point of the erase, including the end() iterator. The iterator pos must be valid and dereferenceable. Thus the end() iterator (which is valid, but is not dereferenceable) cannot be used as a value for pos.

Parameters
[in]firstbeginning of the range of elements to be removed.
[in]lastend of range of elements to be removed.
Returns
Iterator following the last removed element. If the iterator pos refers to the last element, the end() iterator is returned. If first and last refer to the same element, iterator to this element is returned.
Precondition
value_type must meet the requirements of MoveAssignable.
Postcondition
size() = size() - std::distance(first, last).
Exceptions
pmem::transaction_errorwhen snapshotting failed.
rethrowsconstructor's exception.
rethrowsdestructor exception.

◆ erase() [2/2]

template<typename T >
vector< T >::iterator pmem::obj::vector< T >::erase ( const_iterator  pos)

Removes the element at pos.

Invalidates iterators and references at or after the point of the erase, including the end() iterator. The iterator pos must be valid and dereferenceable. Thus the end() iterator (which is valid, but is not dereferenceable) cannot be used as a value for pos.

Parameters
[in]positerator to the element to be removed.
Returns
Iterator following the last removed element. If the iterator pos refers to the last element, the end() iterator is returned.
Precondition
value_type must meet the requirements of MoveAssignable.
Postcondition
size() = size() - 1.
Exceptions
pmem::transaction_errorwhen snapshotting failed.
rethrowsconstructor's exception.
rethrowsdestructor exception.

◆ for_each_ptr()

template<typename T >
void pmem::obj::vector< T >::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 is just a single pointer.

Parameters
funccallback function to call on internal pointer.

◆ free_data()

template<typename T >
void pmem::obj::vector< T >::free_data

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

Postcondition
size() == 0
capacity() == 0
data() == nullptr
Exceptions
pmem::transaction_errorwhen snapshotting failed.
rethrowsdestructor exception.
pmem::transaction_free_errorwhen freeing underlying array failed.

◆ front() [1/2]

template<typename T >
vector< T >::reference pmem::obj::vector< T >::front

Access the first element and add this element to a transaction.

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

◆ front() [2/2]

template<typename T >
vector< T >::const_reference pmem::obj::vector< T >::front

Access the first element.

Returns
const_reference to first element in underlying array.

◆ get_pool()

template<typename T >
pool_base pmem::obj::vector< T >::get_pool
privatenoexcept

Private helper function.

Returns
reference to pool_base object where vector resides.
Precondition
underlying array must reside in persistent memory pool.

◆ get_recommended_capacity()

template<typename T >
vector< T >::size_type pmem::obj::vector< T >::get_recommended_capacity ( size_type  at_least) const
private

Private helper function.

Returns recommended capacity for at least at_least elements.

Returns
recommended new capacity.

◆ insert() [1/5]

template<typename T >
vector< T >::iterator pmem::obj::vector< T >::insert ( const_iterator  pos,
const T &  value 
)

Inserts value before pos in the container transactionally.

Causes reallocation if the new size() is greater than the old capacity(). If the new size() is greater than capacity(), all iterators and references are invalidated. Otherwise, only the iterators and references before the insertion point remain valid. The past-the-end iterator is also invalidated.

Parameters
[in]positerator before which the content will be inserted. pos may be the end() iterator.
[in]valueelement value to be inserted.
Returns
Iterator pointing to the inserted value.
Precondition
value_type must meet the requirements of CopyAssignable and CopyInsertable.
Postcondition
capacity() is equal to the smallest next power of 2, bigger than old capacity, or remains the same if there is enough space to add single element.
Exceptions
pmem::transaction_errorwhen snapshotting failed.
rethrowsconstructor's exception.
rethrowsdestructor exception.
pmem::transaction_free_errorwhen freeing old underlying array failed.

◆ insert() [2/5]

template<typename T >
template<typename InputIt , typename std::enable_if< detail::is_input_iterator< InputIt >::value, InputIt >::type * >
vector< T >::iterator pmem::obj::vector< T >::insert ( const_iterator  pos,
InputIt  first,
InputIt  last 
)

Inserts elements from range [first, last) before pos in the container transactionally.

Causes reallocation if the new size() is greater than the old capacity(). If the new size() is greater than capacity(), all iterators and references are invalidated. Otherwise, only the iterators and references before the insertion point remain valid. The past-the-end iterator is also invalidated. This overload participates in overload resolution only if InputIt qualifies as InputIterator, to avoid ambiguity with the pos-count-value overload. The behavior is undefined if first and last are iterators into *this.

Parameters
[in]positerator before which the content will be inserted. pos may be the end() iterator.
[in]firstbegin of the range of elements to insert, can't be iterator into container for which insert is called.
[in]lastend of the range of elements to insert, can't be iterator into container for which insert is called.
Returns
Iterator pointing to the first element inserted or pos if first == last.
Precondition
value_type must meet the requirements of EmplaceConstructible, Swappable, CopyAssignable, CopyConstructible and CopyInsertable.
InputIt must satisfies requirements of InputIterator.
Postcondition
capacity() is equal to the smallest next power of 2, bigger than old capacity + std::distance(first, last), or remains the same if there is enough space to add std::distance(first, last) elements.
Exceptions
pmem::transaction_errorwhen snapshotting failed.
rethrowsconstructor's exception.
rethrowsdestructor exception.
pmem::transaction_free_errorwhen freeing old underlying array failed.

◆ insert() [3/5]

template<typename T >
vector< T >::iterator pmem::obj::vector< T >::insert ( const_iterator  pos,
size_type  count,
const T &  value 
)

Inserts count copies of the value before pos in the container transactionally.

Causes reallocation if the new size() is greater than the old capacity(). If the new size() is greater than capacity(), all iterators and references are invalidated. Otherwise, only the iterators and references before the insertion point remain valid. The past-the-end iterator is also invalidated.

Parameters
[in]positerator before which the content will be inserted. pos may be the end() iterator.
[in]countnumber of copies to be inserted.
[in]valueelement value to be inserted.
Returns
Iterator pointing to the first element inserted, or pos if count == 0.
Precondition
value_type must meet the requirements of CopyAssignable and CopyInsertable.
Postcondition
capacity() is equal to the smallest next power of 2, bigger than old capacity + count, or remains the same if there is enough space to add count elements.
Exceptions
pmem::transaction_errorwhen snapshotting failed.
rethrowsconstructor's exception.
rethrowsdestructor exception.
pmem::transaction_free_errorwhen freeing old underlying array failed.

◆ insert() [4/5]

template<typename T >
vector< T >::iterator pmem::obj::vector< T >::insert ( const_iterator  pos,
std::initializer_list< T >  ilist 
)

Inserts elements from initializer list ilist before pos in the container transactionally.

Causes reallocation if the new size() is greater than the old capacity(). If the new size() is greater than capacity(), all iterators and references are invalidated. Otherwise, only the iterators and references before the insertion point remain valid. The past-the-end iterator is also invalidated.

Parameters
[in]positerator before which the content will be inserted. pos may be the end() iterator.
[in]ilistinitializer list to insert the values from.
Returns
Iterator pointing to the first element inserted, or pos if ilist is empty.
Precondition
value_type must meet the requirements of EmplaceConstructible, Swappable, CopyAssignable, CopyConstructible and CopyInsertable.
Postcondition
capacity() is equal to the smallest next power of 2, bigger than old capacity + std::distance(ilist.begin(), ilist.end()), or remains the same if there is enough space to add std::distance(ilist.begin(), ilist.end()) elements.
Exceptions
pmem::transaction_errorwhen snapshotting failed.
rethrowsconstructor's exception.
rethrowsdestructor exception.
pmem::transaction_free_errorwhen freeing old underlying array failed.

◆ insert() [5/5]

template<typename T >
vector< T >::iterator pmem::obj::vector< T >::insert ( const_iterator  pos,
T &&  value 
)

Moves value before pos in the container transactionally.

Causes reallocation if the new size() is greater than the old capacity(). If the new size() is greater than capacity(), all iterators and references are invalidated. Otherwise, only the iterators and references before the insertion point remain valid. The past-the-end iterator is also invalidated.

Parameters
[in]positerator before which the content will be inserted. pos may be the end() iterator.
[in]valueelement value to be inserted.
Returns
Iterator pointing to the inserted value.
Precondition
value_type must meet the requirements of MoveAssignable and MoveInsertable.
Postcondition
capacity() is equal to the smallest next power of 2, bigger than old capacity, or remains the same if there is enough space to add single element.
Exceptions
pmem::transaction_errorwhen snapshotting failed.
rethrowsconstructor's exception.
rethrowsdestructor exception.
pmem::transaction_free_errorwhen freeing old underlying array failed.

◆ internal_insert()

template<typename T >
template<typename InputIt >
void pmem::obj::vector< T >::internal_insert ( size_type  idx,
InputIt  first,
InputIt  last 
)
private

Private helper function.

Must be called during transaction. Inserts a gap for count elements starting at index idx. If there is not enough space available, reallocation occurs with new recommended size. Range specified by first, last is then inserted into the gap.

param[in] idx index number where insert should be made param[in] first iterator to beginning of the range to insert param[in] last iterator to end of the range to insert

Precondition
must be called in transaction scope.
Postcondition
if there is not enough space for additional gap, capacity changes to get_recommended_capacity().
Exceptions
pmem::transaction_errorwhen snapshotting failed.
rethrowsconstructor's exception.
rethrowsdestructor exception.
pmem::transaction_free_errorwhen freeing old underlying array failed.

◆ max_size()

template<typename T >
constexpr vector< T >::size_type pmem::obj::vector< T >::max_size
constexprnoexcept
Returns
maximum number of elements the container is able to hold due to PMDK limitations.

◆ move_elements_backward()

template<typename T >
void pmem::obj::vector< T >::move_elements_backward ( pointer  first,
pointer  last,
pointer  d_last 
)
private

Private helper function.

It behaves similarly to std::move_backward but uses either copy constructor in case destination memory is not initialized or copy assignment operator otherwise.

◆ operator=() [1/4]

template<typename T >
vector< T > & pmem::obj::vector< T >::operator= ( const std::vector< T > &  other)

Copy assignment operator.

Replaces the contents with a copy of the contents of std::vector<T> other transactionally. This method is not specified by STL standards.

Postcondition
size() == other.size()
capacity() == max(size(), other.capacity())
Exceptions
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor's exception.

◆ operator=() [2/4]

template<typename T >
vector< T > & pmem::obj::vector< T >::operator= ( const vector< T > &  other)

Copy assignment operator.

Replaces the contents with a copy of the contents of other transactionally.

Postcondition
size() == other.size()
capacity() == max(size(), other.capacity())
Exceptions
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor's exception.

◆ operator=() [3/4]

template<typename T >
vector< T > & pmem::obj::vector< T >::operator= ( std::initializer_list< T >  ilist)

Replaces the contents with those identified by initializer list ilist transactionally.

Exceptions
std::length_errorif ilist.size() > max_size().
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor's exception.

◆ operator=() [4/4]

template<typename T >
vector< T > & pmem::obj::vector< T >::operator= ( vector< T > &&  other)

Move assignment operator.

Replaces the contents with those of other using move semantics (i.e. the data in other is moved from other into this container) transactionally. Other is in a valid but empty state afterwards.

Postcondition
size() == other.size()
capacity() == other.capacity()
Exceptions
pmem::transaction_free_errorwhen freeing underlying array failed.

◆ operator[]() [1/2]

template<typename T >
vector< T >::reference pmem::obj::vector< T >::operator[] ( size_type  n)

Access element at specific index and add it to a transaction.

No bounds checking is performed.

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

◆ operator[]() [2/2]

template<typename T >
vector< T >::const_reference pmem::obj::vector< T >::operator[] ( size_type  n) const

Access element at specific index.

No bounds checking is performed.

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

◆ pop_back()

template<typename T >
void pmem::obj::vector< T >::pop_back

Removes the last element of the container transactionally.

Calling pop_back on an empty container does nothing. No iterators or references except for back() and end() are invalidated.

Postcondition
size() == std::max(0, size() - 1)
Exceptions
transaction_errorwhen snapshotting failed.
rethrowsdestructor exception.

◆ push_back() [1/2]

template<typename T >
void pmem::obj::vector< T >::push_back ( const T &  value)

Appends the given element value to the end of the container transactionally.

The new element is initialized as a copy of value.

Parameters
[in]valuethe value of the element to be appended.
Precondition
value_type must meet the requirements of CopyInsertable.
Postcondition
capacity() is equal to the smallest next power of 2, bigger than old capacity, or remains the same if there is enough space to add single element.
Exceptions
transaction_errorwhen snapshotting failed.
rethrowsconstructor's exception.
pmem::transaction_free_errorwhen freeing old underlying array failed.

◆ push_back() [2/2]

template<typename T >
void pmem::obj::vector< T >::push_back ( T &&  value)

Appends the given element value to the end of the container transactionally.

value is moved into the new element.

Parameters
[in]valuethe value of the element to be appended.
Precondition
value_type must meet the requirements of MoveInsertable.
Postcondition
size() == size() + 1
capacity() is equal to the smallest next power of 2, bigger than old capacity, or remains the same if there is enough space to add single element.
Exceptions
transaction_errorwhen snapshotting failed.
rethrowsconstructor's exception.
pmem::transaction_free_errorwhen freeing old underlying array failed.

◆ range() [1/3]

template<typename T >
slice< typename vector< T >::pointer > pmem::obj::vector< T >::range ( size_type  start,
size_type  n 
)

Returns slice and snapshots requested range.

This method is not specified by STL standards.

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

◆ range() [2/3]

template<typename T >
slice< typename vector< T >::const_iterator > pmem::obj::vector< T >::range ( size_type  start,
size_type  n 
) const

Returns const slice.

This method is not specified by STL standards.

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

◆ range() [3/3]

template<typename T >
slice< typename vector< T >::range_snapshotting_iterator > pmem::obj::vector< T >::range ( size_type  start,
size_type  n,
size_type  snapshot_size 
)

Returns slice.

This method is not specified by STL standards.

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

◆ rbegin() [1/2]

template<typename T >
vector< T >::reverse_iterator pmem::obj::vector< T >::rbegin

Returns a reverse iterator to the beginning.

Returns
reverse_iterator pointing to the last element in the vector.

◆ rbegin() [2/2]

template<typename T >
vector< T >::const_reverse_iterator pmem::obj::vector< T >::rbegin
noexcept

Returns a const reverse iterator to the beginning.

Returns
const_reverse_iterator pointing to the last element in the vector.

◆ realloc()

template<typename T >
void pmem::obj::vector< T >::realloc ( size_type  capacity_new)
private

Private helper function.

Must be called during transaction. Allocates new memory for capacity_new number of elements and copies or moves old elements to new memory area. If the current size is greater than capacity_new, the container is reduced to its first capacity_new elements. If was never allocated behaves as an alloc call.

param[in] capacity_new new capacity.

Precondition
must be called in transaction scope.
Postcondition
capacity() == capacity_new
Exceptions
pmem::transaction_errorwhen snapshotting failed.
rethrowsconstructor's exception.
rethrowsdestructor exception.
pmem::transaction_free_errorwhen freeing old underlying array failed.

◆ rend() [1/2]

template<typename T >
vector< T >::reverse_iterator pmem::obj::vector< T >::rend

Returns a reverse iterator to the end.

Returns
reverse_iterator pointing to the theoretical element preceding the first element in the vector.

◆ rend() [2/2]

template<typename T >
vector< T >::const_reverse_iterator pmem::obj::vector< T >::rend
noexcept

Returns a const reverse iterator to the end.

Returns
const_reverse_iterator pointing to the theoretical element preceding the first element in the vector.

◆ reserve()

template<typename T >
void pmem::obj::vector< T >::reserve ( size_type  capacity_new)

Increases the capacity of the vector to capacity_new transactionally.

If capacity_new is greater than the current capacity(), new storage is allocated, otherwise the method does nothing. If capacity_new 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]capacity_newnew capacity.
Postcondition
capacity() == max(capacity(), capacity_new)
Exceptions
rethrowsdestructor exception.
std::length_errorif new_cap > max_size().
pmem::transaction_errorwhen snapshotting failed.
pmem::transaction_alloc_errorwhen allocating new memory failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.

◆ resize() [1/2]

template<typename T >
void pmem::obj::vector< T >::resize ( size_type  count)

Resizes the container to count elements transactionally.

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

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

◆ resize() [2/2]

template<typename T >
void pmem::obj::vector< T >::resize ( size_type  count,
const value_type &  value 
)

Resizes the container to contain count elements transactionally.

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

Parameters
[in]countnew size of the container.
[in]valuethe value to initialize the new elements with.
Postcondition
capacity() == count
size() == std::min(_size, count)
Exceptions
rethrowsconstructor's exception.
rethrowsdestructor exception.
pmem::transaction_errorwhen snapshotting failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.

◆ shrink()

template<typename T >
void pmem::obj::vector< T >::shrink ( size_type  size_new)
private

Private helper function.

Must be called during transaction. Destroys elements in underlying array beginning from position size_new.

Parameters
[in]size_newnew size
Precondition
must be called in transaction scope.
if initialized, range [begin(), end()) must be snapshotted in current transaction.
size_new <= size()
Postcondition
size() == size_new
Exceptions
pmem::transaction_errorwhen snapshotting failed.
rethrowsdestructor exception.

◆ shrink_to_fit()

template<typename T >
void pmem::obj::vector< T >::shrink_to_fit

Requests transactional removal of unused capacity.

New capacity will be set to current vector size. If reallocation occurs, all iterators, including the past the end iterator, and all references to the elements are invalidated. If no reallocation takes place, no iterators or references are invalidated.

Postcondition
capacity() == size()
Exceptions
pmem::transaction_errorwhen snapshotting failed
pmem::transaction_alloc_errorwhen reallocating failed.
pmem::transaction_free_errorwhen freeing old underlying array failed.
rethrowsconstructor's exception.
rethrowsdestructor exception.

◆ size()

template<typename T >
vector< T >::size_type pmem::obj::vector< T >::size
noexcept
Returns
number of elements.

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