#include "cetl/variable_length_array.hpp"

Public Types
using	value_type = typename Base::value_type

using	pointer = typename std::add_pointer_t<value_type>

using	iterator = typename std::add_pointer_t<value_type>

using	const_iterator = typename std::add_pointer_t<typename std::add_const_t<value_type>>

using	difference_type = typename Base::difference_type

using	size_type = typename Base::size_type

using	allocator_type = typename Base::allocator_type

using	reference = typename std::add_lvalue_reference_t<value_type>

using	const_reference = typename std::add_lvalue_reference_t<std::add_const_t<value_type>>

Public Member Functions
	VariableLengthArray (const allocator_type &alloc) noexcept

	VariableLengthArray (size_type max_size_max, const allocator_type &alloc) noexcept

	VariableLengthArray (std::initializer_list< value_type > l, size_type max_size_max, const allocator_type &alloc)

	VariableLengthArray (std::initializer_list< value_type > l, const allocator_type &alloc)

template<class InputIt>
	VariableLengthArray (InputIt first, InputIt last, size_type max_size_max, const allocator_type &alloc)

template<class InputIt>
	VariableLengthArray (InputIt first, InputIt last, const allocator_type &alloc)

	VariableLengthArray (const VariableLengthArray &rhs, const allocator_type &alloc)

	VariableLengthArray (const VariableLengthArray &rhs)

VariableLengthArray &	operator= (const VariableLengthArray &rhs)

	VariableLengthArray (VariableLengthArray &&rhs, const allocator_type &alloc) noexcept

	VariableLengthArray (VariableLengthArray &&rhs) noexcept

VariableLengthArray &	operator= (VariableLengthArray &&rhs) noexcept(std::allocator_traits< allocator_type >::propagate_on_container_move_assignment::value\|\|std::allocator_traits< allocator_type >::is_always_equal::value)

constexpr bool	operator== (const VariableLengthArray &rhs) const noexcept

constexpr bool	operator!= (const VariableLengthArray &rhs) const noexcept

constexpr const_iterator	cbegin () const noexcept

constexpr const_iterator	cend () const noexcept

constexpr iterator	begin () noexcept

constexpr const_iterator	begin () const noexcept

constexpr iterator	end () noexcept

constexpr const_iterator	end () const noexcept

constexpr value_type *	data () noexcept

constexpr const value_type *	data () const noexcept

constexpr const value_type &	operator[] (size_type pos) const noexcept

constexpr value_type &	operator[] (size_type pos) noexcept

constexpr allocator_type	get_allocator () const noexcept

constexpr reference	at (size_type pos)

constexpr const_reference	at (size_type pos) const

constexpr reference	front ()

constexpr const_reference	front () const

constexpr reference	back ()

constexpr const_reference	back () const

constexpr bool	empty () const noexcept

void	shrink_to_fit ()

constexpr size_type	capacity () const noexcept

constexpr size_type	size () const noexcept

void	reserve (const size_type desired_capacity)

constexpr size_type	max_size () const noexcept

constexpr void	clear () noexcept(std::is_nothrow_destructible< value_type >::value)

constexpr void	push_back (const value_type &value)

constexpr void	push_back (value_type &&value)

constexpr void	pop_back () noexcept(std::is_nothrow_destructible< value_type >::value)

template<class... Args>
void	emplace_back (Args &&... args)

constexpr void	resize (size_type count)

constexpr void	resize (size_type count, const value_type &value)

constexpr void	assign (size_type count, const value_type &value)

Protected Types
using	Base = VariableLengthArrayBase<T, Allocator>

Protected Types inherited from cetl::VariableLengthArrayBase< T, Allocator >
using	reallocate_operation

using	value_type

using	allocator_type

using	difference_type

using	size_type

Protected Attributes
value_type *	data_

size_type	size_

size_type	capacity_

size_type	max_size_max_

allocator_type	alloc_

Protected Attributes inherited from cetl::VariableLengthArrayBase< T, Allocator >
allocator_type	alloc_

value_type *	data_

size_type	capacity_

size_type	size_

size_type	max_size_max_

allocator_type	alloc_

value_type *	data_

size_type	capacity_

size_type	size_

size_type	max_size_max_

Additional Inherited Members
Protected Member Functions inherited from cetl::VariableLengthArrayBase< T, Allocator >
constexpr bool	move_assign_alloc (UAlloc &&rhs, typename std::enable_if_t< std::allocator_traits< std::remove_reference_t< UAlloc > >::propagate_on_container_move_assignment::value > *=nullptr) noexcept(is_pocma_or_is_always_equal< UAlloc >::value)

constexpr bool	move_assign_alloc (UAlloc &&rhs, typename std::enable_if_t< !std::allocator_traits< std::remove_reference_t< UAlloc > >::propagate_on_container_move_assignment::value > *=nullptr) noexcept(is_pocma_or_is_always_equal< UAlloc >::value)

constexpr bool	copy_assign_alloc (const UAlloc &rhs, typename std::enable_if_t< std::allocator_traits< UAlloc >::propagate_on_container_copy_assignment::value > *=nullptr) noexcept

constexpr bool	copy_assign_alloc (const UAlloc &rhs, typename std::enable_if_t<!std::allocator_traits< UAlloc >::propagate_on_container_copy_assignment::value > *=nullptr) noexcept

constexpr void	copy_assign_from (const VariableLengthArrayBase &rhs, const size_type rhs_max_size)

constexpr void	move_assign_from (VariableLengthArrayBase &&rhs, const size_type rhs_max_size, typename std::enable_if_t< is_pocma_or_is_always_equal< UAlloc >::value > *=nullptr) noexcept

constexpr void	move_assign_from (VariableLengthArrayBase &&rhs, const size_type rhs_max_size, typename std::enable_if_t<!is_pocma_or_is_always_equal< UAlloc >::value > *=nullptr)

constexpr void	reserve (const size_type desired_capacity, const size_type max_size)

constexpr void	resize (size_type new_size, const size_type max_size, Args &&... args)

constexpr void	shrink_to_fit ()

constexpr bool	grow (const size_type max_size)

constexpr	VariableLengthArrayBase (const allocator_type &alloc, value_type *data, size_type initial_capacity, size_type size, size_type max_size_max) noexcept(std::is_nothrow_copy_constructible< allocator_type >::value)

constexpr	VariableLengthArrayBase (const VariableLengthArrayBase &rhs, const allocator_type &rhs_alloc) noexcept(std::is_nothrow_copy_constructible< allocator_type >::value)

constexpr	VariableLengthArrayBase (VariableLengthArrayBase &&rhs) noexcept

constexpr	VariableLengthArrayBase (VariableLengthArrayBase &&rhs, const UAlloc &rhs_alloc, typename std::enable_if_t< is_pocma_or_is_always_equal< UAlloc >::value > *=nullptr) noexcept

constexpr	VariableLengthArrayBase (VariableLengthArrayBase &&rhs, const UAlloc &rhs_alloc, typename std::enable_if_t<!is_pocma_or_is_always_equal< UAlloc >::value > *=nullptr) noexcept

constexpr bool	move_assign_alloc (UAlloc &&rhs, typename std::enable_if_t< std::allocator_traits< std::remove_reference_t< UAlloc > >::propagate_on_container_move_assignment::value > *=nullptr) noexcept(is_pocma_or_is_always_equal< UAlloc >::value)

constexpr bool	move_assign_alloc (UAlloc &&rhs, typename std::enable_if_t< !std::allocator_traits< std::remove_reference_t< UAlloc > >::propagate_on_container_move_assignment::value > *=nullptr) noexcept(is_pocma_or_is_always_equal< UAlloc >::value)

constexpr bool	copy_assign_alloc (const UAlloc &rhs, typename std::enable_if_t< std::allocator_traits< UAlloc >::propagate_on_container_copy_assignment::value > *=nullptr) noexcept

constexpr bool	copy_assign_alloc (const UAlloc &rhs, typename std::enable_if_t<!std::allocator_traits< UAlloc >::propagate_on_container_copy_assignment::value > *=nullptr) noexcept

constexpr void	copy_assign_from (const VariableLengthArrayBase &rhs, const size_type rhs_max_size)

constexpr void	move_assign_from (VariableLengthArrayBase &&rhs, const size_type rhs_max_size, typename std::enable_if_t< is_pocma_or_is_always_equal< UAlloc >::value > *=nullptr) noexcept

constexpr void	move_assign_from (VariableLengthArrayBase &&rhs, const size_type rhs_max_size, typename std::enable_if_t<!is_pocma_or_is_always_equal< UAlloc >::value > *=nullptr)

constexpr void	reserve (const size_type desired_capacity, const size_type max_size)

constexpr void	resize (size_type new_size, const size_type max_size, Args &&... args)

constexpr void	shrink_to_fit ()

constexpr bool	grow (const size_type max_size)

constexpr	VariableLengthArrayBase (const allocator_type &alloc, value_type *data, size_type initial_capacity, size_type size, size_type max_size_max) noexcept(std::is_nothrow_copy_constructible< allocator_type >::value)

constexpr	VariableLengthArrayBase (const VariableLengthArrayBase &rhs, const allocator_type &rhs_alloc) noexcept(std::is_nothrow_copy_constructible< allocator_type >::value)

constexpr	VariableLengthArrayBase (VariableLengthArrayBase &&rhs) noexcept

constexpr	VariableLengthArrayBase (VariableLengthArrayBase &&rhs, const UAlloc &rhs_alloc, typename std::enable_if_t< is_pocma_or_is_always_equal< UAlloc >::value > *=nullptr) noexcept

constexpr	VariableLengthArrayBase (VariableLengthArrayBase &&rhs, const UAlloc &rhs_alloc, typename std::enable_if_t<!is_pocma_or_is_always_equal< UAlloc >::value > *=nullptr) noexcept

Static Protected Member Functions inherited from cetl::VariableLengthArrayBase< T, Allocator >
static constexpr std::enable_if_t< is_detected< reallocate_operation, UAllocator >::value, value_type > *	reallocate (value_type *data, UAllocator &alloc, std::size_t old_object_count, std::size_t new_object_count)

static constexpr std::enable_if_t<!is_detected< reallocate_operation, UAllocator >::value, value_type > *	reallocate (value_type *data, UAllocator &alloc, std::size_t old_object_count, std::size_t new_object_count)

static constexpr void	fast_destroy (U const src, const size_type src_size_count, typename std::enable_if_t< std::is_trivially_destructible< U >::value > =nullptr) noexcept

static constexpr void	fast_destroy (U const src, const size_type src_size_count, typename std::enable_if_t<!std::is_trivially_destructible< U >::value > =nullptr) noexcept(std::is_nothrow_destructible< U >::value)

static constexpr void	fast_deallocate (U const src, const size_type src_size_count, const size_type src_capacity_count, allocator_type &alloc, typename std::enable_if_t< std::is_trivially_destructible< U >::value > =nullptr)

static constexpr void	fast_deallocate (U const src, const size_type src_size_count, const size_type src_capacity_count, allocator_type &alloc, typename std::enable_if_t<!std::is_trivially_destructible< U >::value > =nullptr)

static constexpr size_type	fast_copy_assign (value_type *dst, size_type dst_capacity_count, InputIt src) noexcept(noexcept(std::is_nothrow_assignable< value_type, std::remove_pointer_t< InputIt > >::value))

static constexpr size_type	fast_copy_assign (value_type *dst, size_type dst_capacity_count, InputIt src, size_type src_len_count) noexcept(noexcept(std::is_nothrow_assignable< value_type, std::remove_pointer_t< InputIt > >::value))

static constexpr size_type	fast_copy_construct (value_type const dst, size_type dst_capacity_count, const InputIt src, size_type src_len_count, allocator_type &alloc, typename std::enable_if_t< is_array_of_type_trivially_copyable< std::add_pointer_t< value_type >, InputIt >::value > =nullptr) noexcept

static constexpr size_type	fast_copy_construct (value_type const dst, size_type dst_capacity_count, const InputIt src, size_type src_len_count, allocator_type &alloc, typename std::enable_if_t< !is_array_of_type_trivially_copyable< std::add_pointer_t< value_type >, InputIt >::value > =nullptr) noexcept(noexcept(std::allocator_traits< allocator_type >::construct(std::declval< std::add_lvalue_reference_t< allocator_type > >(), std::declval< std::add_pointer_t< value_type > >(), std::declval< std::add_lvalue_reference_t< decltype(std::declval< const InputIt >()[0])> >())))

static constexpr size_type	fast_forward_construct (value_type const dst, size_type dst_capacity_count, InputIt src, size_type src_len_count, allocator_type &alloc, typename std::enable_if_t< is_array_of_type_trivially_copyable< std::add_pointer_t< value_type >, InputIt >::value > =nullptr)

static constexpr size_type	fast_forward_construct (value_type const dst, size_type dst_capacity_count, InputIt src, size_type src_len_count, allocator_type &alloc, typename std::enable_if_t< !is_array_of_type_trivially_copyable< std::add_pointer_t< value_type >, InputIt >::value > =nullptr)

static constexpr size_type	fast_forward_assign (value_type const dst, size_type dst_capacity_count, InputIt src, size_type src_len_count, typename std::enable_if_t< is_array_of_type_trivially_copyable< std::add_pointer_t< value_type >, InputIt >::value > =nullptr)

static constexpr size_type	fast_forward_assign (value_type const dst, size_type dst_capacity_count, InputIt src, size_type src_len_count, typename std::enable_if_t< !is_array_of_type_trivially_copyable< std::add_pointer_t< value_type >, InputIt >::value > =nullptr)

static constexpr std::enable_if_t< is_detected< reallocate_operation, UAllocator >::value, value_type > *	reallocate (value_type *data, UAllocator &alloc, std::size_t old_object_count, std::size_t new_object_count)

static constexpr std::enable_if_t<!is_detected< reallocate_operation, UAllocator >::value, value_type > *	reallocate (value_type *data, UAllocator &alloc, std::size_t old_object_count, std::size_t new_object_count)

static constexpr void	fast_destroy (U const src, const size_type src_size_count, typename std::enable_if_t< std::is_trivially_destructible< U >::value > =nullptr) noexcept

static constexpr void	fast_destroy (U const src, const size_type src_size_count, typename std::enable_if_t<!std::is_trivially_destructible< U >::value > =nullptr) noexcept(std::is_nothrow_destructible< U >::value)

static constexpr void	fast_deallocate (U const src, const size_type src_size_count, const size_type src_capacity_count, allocator_type &alloc, typename std::enable_if_t< std::is_trivially_destructible< U >::value > =nullptr)

static constexpr void	fast_deallocate (U const src, const size_type src_size_count, const size_type src_capacity_count, allocator_type &alloc, typename std::enable_if_t<!std::is_trivially_destructible< U >::value > =nullptr)

static constexpr size_type	fast_copy_assign (value_type *dst, size_type dst_capacity_count, InputIt src) noexcept(noexcept(std::is_nothrow_assignable< value_type, std::remove_pointer_t< InputIt > >::value))

static constexpr size_type	fast_copy_assign (value_type *dst, size_type dst_capacity_count, InputIt src, size_type src_len_count) noexcept(noexcept(std::is_nothrow_assignable< value_type, std::remove_pointer_t< InputIt > >::value))

static constexpr size_type	fast_copy_construct (value_type const dst, size_type dst_capacity_count, const InputIt src, size_type src_len_count, allocator_type &alloc, typename std::enable_if_t< is_array_of_type_trivially_copyable< std::add_pointer_t< value_type >, InputIt >::value > =nullptr) noexcept

static constexpr size_type	fast_copy_construct (value_type const dst, size_type dst_capacity_count, const InputIt src, size_type src_len_count, allocator_type &alloc, typename std::enable_if_t< !is_array_of_type_trivially_copyable< std::add_pointer_t< value_type >, InputIt >::value > =nullptr) noexcept(noexcept(std::allocator_traits< allocator_type >::construct(std::declval< std::add_lvalue_reference_t< allocator_type > >(), std::declval< std::add_pointer_t< value_type > >(), std::declval< std::add_lvalue_reference_t< decltype(std::declval< const InputIt >()[0])> >())))

static constexpr size_type	fast_forward_construct (value_type const dst, size_type dst_capacity_count, InputIt src, size_type src_len_count, allocator_type &alloc, typename std::enable_if_t< is_array_of_type_trivially_copyable< std::add_pointer_t< value_type >, InputIt >::value > =nullptr)

static constexpr size_type	fast_forward_construct (value_type const dst, size_type dst_capacity_count, InputIt src, size_type src_len_count, allocator_type &alloc, typename std::enable_if_t< !is_array_of_type_trivially_copyable< std::add_pointer_t< value_type >, InputIt >::value > =nullptr)

static constexpr size_type	fast_forward_assign (value_type const dst, size_type dst_capacity_count, InputIt src, size_type src_len_count, typename std::enable_if_t< is_array_of_type_trivially_copyable< std::add_pointer_t< value_type >, InputIt >::value > =nullptr)

static constexpr size_type	fast_forward_assign (value_type const dst, size_type dst_capacity_count, InputIt src, size_type src_len_count, typename std::enable_if_t< !is_array_of_type_trivially_copyable< std::add_pointer_t< value_type >, InputIt >::value > =nullptr)

Detailed Description

template<typename T, typename Allocator>
class cetl::VariableLengthArray< T, Allocator >

Minimal, generic container for storing Cyphal variable-length arrays.

While this type shares similarities with std::vector it has several important properties that are different. First, the max_size_max maximum bound allows the array to enforce a maximum size whether or not the allocator properly implements the std::allocator_traits::max_size protocol (std::pmr::polymorphic_allocator, for example). This allows use of an allocator that is backed by statically allocated memory:

 
cetl::pf17::pmr::UnsynchronizedArrayMemoryResource<56>                        array_storage_0{};
cetl::VariableLengthArray<char, cetl::pf17::pmr::polymorphic_allocator<char>> exact_fit{
    array_storage_0.size(),
    {&array_storage_0},
};
exact_fit.reserve(56);
for (std::size_t i = 0; i < 56; ++i)
{
    std::cout << i << ", ";
    exact_fit.push_back(static_cast<char>(i + 46));
}
 
std::cout << "<- The VLA only used the 56 chars we gave it and no more." << std::endl;

Even if cetl::VariableLengthArray::reserve() is not used the implementation will still use less memory then its STL counterpart:

 
cetl::pf17::pmr::UnsynchronizedArrayMemoryResource<56>          array_storage_1{};
cetl::pf17::pmr::UnsynchronizedArrayMemoryResource<56>          array_storage_0{&array_storage_1,
                                                                       array_storage_1.max_size()};
std::vector<char, cetl::pf17::pmr::polymorphic_allocator<char>> space_waster{{&array_storage_0}};
 
try
{
    for (std::size_t i = 0; i < 56; ++i)
    {
        std::cout << i << ", ";
        space_waster.push_back(static_cast<char>(i + 46));
    }
} catch (const std::bad_alloc&)
{
    std::cout << "<- vector claimed to have run out of memory but we know better." << std::endl;
}

// The problem with the C++17 standard is the lack of support for max_size in pmr types.
// VariableLengthArray provides the "max_size_max" argument that lets the user limit the amount of memory
// the container will use.
cetl::pf17::pmr::UnsynchronizedArrayMemoryResource<56>                        array_storage_1{};
cetl::pf17::pmr::UnsynchronizedArrayMemoryResource<56>                        array_storage_0{&array_storage_1,
                                                                       array_storage_1.max_size()};
cetl::VariableLengthArray<char, cetl::pf17::pmr::polymorphic_allocator<char>> tight_fit{
    array_storage_0.size(),
    {&array_storage_0},
};
for (std::size_t i = 0; i < 56; ++i)
{
    std::cout << i << ", ";
    tight_fit.push_back(static_cast<char>(i + 46));
}
 
std::cout << "<- The VLA was able to fit tightly inside of the maximum size it was given." << std::endl;

Finally, when exceptions are disabled the cetl::VariableLengthArray will not exhibit undefined behaviour like std::vector does:

 
// Using the cetlpf.hpp header we can create a polymorphic allocator that is aliased to
// std::pmr::polymorphic_allocator when compiling with C++17 or newer and cetl::pf17::pmr::polymorphic_allocator
// when compiling with C++14.
cetl::pf17::pmr::polymorphic_allocator<char> alloc{cetl::pf17::pmr::new_delete_resource()};
 
// This allows us to demonstrate that the cetl::variable_length_array behaves like a std::vector...
std::vector<char, cetl::pf17::pmr::polymorphic_allocator<char>>               a{alloc};
cetl::VariableLengthArray<char, cetl::pf17::pmr::polymorphic_allocator<char>> b{alloc};
 
add_hello_world(a);
add_hello_world(b);
 
print_container(a);
print_container(b);
 
// So why not just use vector?
// The primary reason is std::vector has some edge cases where it cannot be used when exceptions are disabled.
// Here we are giving a vector and a VariableLengthArray the same allocator CETL pf17 allocator. This allocator
// returns nullptr when out of memory and exceptions are disabled.
 
cetl::pf17::pmr::polymorphic_allocator<char> bad_alloc{cetl::pf17::pmr::null_memory_resource()};
 
std::vector<char, cetl::pf17::pmr::polymorphic_allocator<char>>               bad_a{bad_alloc};
cetl::VariableLengthArray<char, cetl::pf17::pmr::polymorphic_allocator<char>> bad_b{bad_alloc};
 
//  In this case, the VariableLengthArray will fail gracefully when it failed to allocate.
bad_b.push_back('H');
 
// But this would cause undefined behavior in the vector. Some implementations might cause an abort() whereas
// others may cause a segfault (or worse).
 
// of course, we commented out the following line but feel free to uncomment and try yourself.
// bad_a.push_back('H');
 
// You can detect that VariableLengthArray was not able to allocate memory for push_back using the following
// technique:
const std::size_t size_before = bad_b.size();
bad_b.push_back('H');
if (bad_b.size() == size_before)
{
    if (size_before == bad_b.max_size())
    {
        std::cout << "bad_b was not able to allocate memory because it reached its max_size. You probably should "
                     "have checked this first? Just sayin'."
                  << std::endl;
    }
    else
    {
        std::cout << "bad_b allocator is out of memory." << std::endl;
    }
}

(See full example here...)

Template Parameters

T	The type of elements in the array.
Allocator	The allocator type to use for all allocations.

Member Typedef Documentation

◆ allocator_type

template<typename T, typename Allocator>

using cetl::VariableLengthArray< T, Allocator >::allocator_type = typename Base::allocator_type

Per the std::uses_allocator protocol.

◆ const_iterator

template<typename T, typename Allocator>

using cetl::VariableLengthArray< T, Allocator >::const_iterator = typename std::add_pointer_t<typename std::add_const_t<value_type>>

STL-like declaration of the const iterator type.

◆ const_reference

template<typename T, typename Allocator>

using cetl::VariableLengthArray< T, Allocator >::const_reference = typename std::add_lvalue_reference_t<std::add_const_t<value_type>>

STL-like declaration of constant-reference type.

◆ difference_type

template<typename T, typename Allocator>

using cetl::VariableLengthArray< T, Allocator >::difference_type = typename Base::difference_type

STL-like declaration of the container's difference type.

◆ iterator

template<typename T, typename Allocator>

using cetl::VariableLengthArray< T, Allocator >::iterator = typename std::add_pointer_t<value_type>

STL-like declaration of the iterator type.

◆ pointer

template<typename T, typename Allocator>

using cetl::VariableLengthArray< T, Allocator >::pointer = typename std::add_pointer_t<value_type>

STL-like declaration of pointer type.

◆ reference

template<typename T, typename Allocator>

using cetl::VariableLengthArray< T, Allocator >::reference = typename std::add_lvalue_reference_t<value_type>

STL-like declaration of reference type.

◆ size_type

template<typename T, typename Allocator>

using cetl::VariableLengthArray< T, Allocator >::size_type = typename Base::size_type

STL-like declaration of the container's size type.

◆ value_type

template<typename T, typename Allocator>

using cetl::VariableLengthArray< T, Allocator >::value_type = typename Base::value_type

STL-like declaration of the container's storage type.

Constructor & Destructor Documentation

◆ VariableLengthArray() [1/6]

template<typename T, typename Allocator>

cetl::VariableLengthArray< T, Allocator >::VariableLengthArray ( const allocator_type & alloc )

inlineexplicitnoexcept

Required constructor for std::uses_allocator protocol.

Parameters

alloc Allocator to use for all allocations.

References std::numeric_limits::max().

Referenced by VariableLengthArray(), and VariableLengthArray().

Here is the caller graph for this function:

◆ VariableLengthArray() [2/6]

template<typename T, typename Allocator>

cetl::VariableLengthArray< T, Allocator >::VariableLengthArray	(	size_type	max_size_max,
		const allocator_type &	alloc )

inlineexplicitnoexcept

Required constructor for std::uses_allocator protocol.

Parameters

max_size_max	Clamping value for the maximum size of this array. That is, cetl::VariableLengthArray::max_size() will return `std::min(max_size_max, std::allocator_traits<allocator_type>::max_size(alloc))`
alloc	Allocator to use for all allocations.

◆ VariableLengthArray() [3/6]

template<typename T, typename Allocator>

cetl::VariableLengthArray< T, Allocator >::VariableLengthArray	(	std::initializer_list< value_type >	l,
		size_type	max_size_max,
		const allocator_type &	alloc )

inline

Initializer syntax constructor with maximum max size.

Parameters

l	Initializer list of elements to copy into the array.
max_size_max	Clamping value for the maximum size of this array. That is, cetl::VariableLengthArray::max_size() will return `std::min(max_size_max, std::allocator_traits<allocator_type>::max_size(alloc))`
alloc	Allocator to use for all allocations.

References std::initializer_list::begin(), cetl::VariableLengthArrayBase< T, Allocator >::fast_copy_construct(), reserve(), and std::initializer_list::size().

◆ VariableLengthArray() [4/6]

template<typename T, typename Allocator>

cetl::VariableLengthArray< T, Allocator >::VariableLengthArray	(	std::initializer_list< value_type >	l,
		const allocator_type &	alloc )

inline

Initializer syntax constructor.

Parameters

l	Initializer list of elements to copy into the array.
alloc	Allocator to use for all allocations.

References VariableLengthArray().

◆ VariableLengthArray() [5/6]

template<typename T, typename Allocator>

template<class InputIt>

cetl::VariableLengthArray< T, Allocator >::VariableLengthArray	(	InputIt	first,
		InputIt	last,
		size_type	max_size_max,
		const allocator_type &	alloc )

inline

Range constructor with maximum max size.

Template Parameters

InputIt The type of the range's iterators.

Parameters

first	The beginning of the range.
last	The end of the range.
max_size_max	Clamping value for the maximum size of this array. That is, cetl::VariableLengthArray::max_size() will return `std::min(max_size_max, / std::allocator_traits<allocator_type>::max_size(alloc))`
alloc	Allocator to use for all allocations.

References cetl::VariableLengthArrayBase< T, Allocator >::fast_copy_construct(), and reserve().

◆ VariableLengthArray() [6/6]

template<typename T, typename Allocator>

template<class InputIt>

cetl::VariableLengthArray< T, Allocator >::VariableLengthArray	(	InputIt	first,
		InputIt	last,
		const allocator_type &	alloc )

inline

Range constructor.

Template Parameters

InputIt The type of the range's iterators.

Parameters

first	The beginning of the range.
last	The end of the range.
alloc	Allocator to use for all allocations.

References VariableLengthArray().

Member Function Documentation

◆ assign()

template<typename T, typename Allocator>

void cetl::VariableLengthArray< T, Allocator >::assign	(	size_type	count,
		const value_type &	value )

inlineconstexpr

Set count elements to the given value.

Grow the array if needed else set the size to count without reducing capacity.

Parameters

count	Number of elements, starting from 0, to set.
value	The value to set.

Exceptions

std::length_error	if the size requested is greater than `max_size()`.
std::bad_alloc	if the container cannot obtain enough memory to size up to `count`.

References cetl::VariableLengthArrayBase< T, Allocator >::fast_copy_assign(), and resize().

◆ at() [1/2]

template<typename T, typename Allocator>

reference cetl::VariableLengthArray< T, Allocator >::at ( size_type pos )

inlineconstexpr

Returns a reference to the element at specified location pos, with bounds checking.

Note: This function is only available if exceptions are enabled since there is no valid way to implement it without exceptions.

Parameters

pos	Position of the element to return.

Returns: Reference to the requested element.

References operator[](), and size().

◆ at() [2/2]

template<typename T, typename Allocator>

const_reference cetl::VariableLengthArray< T, Allocator >::at ( size_type pos ) const

inlineconstexpr

Returns a const reference to the element at specified location pos, with bounds checking.

Note: This function is only available if exceptions are enabled since there is no valid way to implement it without exceptions.

Parameters

pos	Position of the element to return.

Returns: Const reference to the requested element.

References operator[](), and size().

◆ back() [1/2]

template<typename T, typename Allocator>

reference cetl::VariableLengthArray< T, Allocator >::back ( )

inlineconstexpr

Returns a reference to the last element in the array.

Calling this method on an empty array is undefined.

Returns: Reference to the last element in the array.

References front(), and size().

◆ back() [2/2]

template<typename T, typename Allocator>

const_reference cetl::VariableLengthArray< T, Allocator >::back ( ) const

inlineconstexpr

Returns a const reference to the last element in the array.

Calling this method on an empty array is undefined.

Returns: Constant reference to the last element in the array.

References front(), and size().

◆ begin()

template<typename T, typename Allocator>

iterator cetl::VariableLengthArray< T, Allocator >::begin ( )

inlineconstexprnoexcept

Provides direct, unsafe access to the internal data buffer.

This pointer is invalidated by calls to shrink_to_fit and reserve.

Returns: An iterator to the first element in the array.

◆ capacity()

template<typename T, typename Allocator>

size_type cetl::VariableLengthArray< T, Allocator >::capacity ( ) const

inlineconstexprnoexcept

The number of elements that can be stored in the array without further allocations.

This number will only grow through calls to reserve and can shrink through calls to shrink_to_fit. This value shall never exceed max_size.

Returns: The current capacity of this object.

◆ cbegin()

template<typename T, typename Allocator>

const_iterator cetl::VariableLengthArray< T, Allocator >::cbegin ( ) const

inlineconstexprnoexcept

Provides direct, unsafe access to the internal data buffer.

This pointer is invalidated by calls to shrink_to_fit and reserve.

◆ cend()

template<typename T, typename Allocator>

const_iterator cetl::VariableLengthArray< T, Allocator >::cend ( ) const

inlineconstexprnoexcept

Pointer to memory location after the last, valid element.

This pointer is invalidated by calls to shrink_to_fit and reserve.

◆ clear()

template<typename T, typename Allocator>

void cetl::VariableLengthArray< T, Allocator >::clear ( )

inlineconstexprnoexcept

Destroys all elements in the list but does not release any capacity.

References cetl::VariableLengthArrayBase< T, Allocator >::fast_destroy().

◆ data() [1/2]

template<typename T, typename Allocator>

const value_type * cetl::VariableLengthArray< T, Allocator >::data ( ) const

inlineconstexprnoexcept

Provides direct, unsafe access to the internal data buffer.

This pointer is invalidated by calls to shrink_to_fit and reserve.

◆ data() [2/2]

template<typename T, typename Allocator>

value_type * cetl::VariableLengthArray< T, Allocator >::data ( )

inlineconstexprnoexcept

Provides direct, unsafe access to the internal data buffer.

This pointer is invalidated by calls to shrink_to_fit and reserve.

◆ emplace_back()

template<typename T, typename Allocator>

template<class... Args>

void cetl::VariableLengthArray< T, Allocator >::emplace_back ( Args &&... args )

inline

Like push_back but constructs the object directly in uninitialized memory.

Exceptions

throw std::length_error if there was not enough storage for an additional element. If exceptions are disabled then the caller must check the array size before and after calling the method to determine if it succeeded.

References std::allocator_traits::construct(), and std::forward().

Referenced by cetl::VariableLengthArray< bool, Allocator >::VariableLengthArray(), and cetl::VariableLengthArray< bool, Allocator >::VariableLengthArray().

Here is the caller graph for this function:

◆ empty()

template<typename T, typename Allocator>

bool cetl::VariableLengthArray< T, Allocator >::empty ( ) const

inlineconstexprnoexcept

Query if the container has any elements in it at all.

Returns: true if the container is empty, false otherwise.

◆ end()

template<typename T, typename Allocator>

iterator cetl::VariableLengthArray< T, Allocator >::end ( )

inlineconstexprnoexcept

Pointer to memory location after the last, valid element.

This pointer is invalidated by calls to shrink_to_fit and reserve.

◆ front() [1/2]

template<typename T, typename Allocator>

reference cetl::VariableLengthArray< T, Allocator >::front ( )

inlineconstexpr

Returns a reference to the first element in the array.

Calling this method on an empty array is undefined.

Returns: Reference to the first element in the array.

References CETL_DEBUG_ASSERT, and size().

Referenced by back(), back(), cetl::VariableLengthArray< bool, Allocator >::back(), and cetl::VariableLengthArray< bool, Allocator >::back().

Here is the caller graph for this function:

◆ front() [2/2]

template<typename T, typename Allocator>

const_reference cetl::VariableLengthArray< T, Allocator >::front ( ) const

inlineconstexpr

Returns a const reference to the first element in the array.

Calling this method on an empty array is undefined.

Returns: Constant reference to the first element in the array.

References CETL_DEBUG_ASSERT, and size().

◆ get_allocator()

template<typename T, typename Allocator>

allocator_type cetl::VariableLengthArray< T, Allocator >::get_allocator ( ) const

inlineconstexprnoexcept

STL-like access to a copy of the internal allocator.

◆ max_size()

template<typename T, typename Allocator>

size_type cetl::VariableLengthArray< T, Allocator >::max_size ( ) const

inlineconstexprnoexcept

Returns the, theoretical, maximum number of elements that can be stored in this container.

It does not take into account the current state of the allocator. That is, if the allocator is out of memory this method will still return the maximum number of elements that could be stored if the allocator had enough memory, however, it will always return the maximum size passed into the constructor if that value is less than the allocator's max_size.

Returns: The maximum number of elements that could be stored in this container.

References std::numeric_limits::max(), std::allocator_traits::max_size(), and std::min().

Referenced by reserve(), cetl::VariableLengthArray< bool, Allocator >::reserve(), resize(), resize(), cetl::VariableLengthArray< bool, Allocator >::resize(), and cetl::VariableLengthArray< bool, Allocator >::VariableLengthArray().

Here is the caller graph for this function:

◆ operator[]() [1/2]

template<typename T, typename Allocator>

const value_type & cetl::VariableLengthArray< T, Allocator >::operator[] ( size_type pos ) const

inlineconstexprnoexcept

Direct, const access to an element.

If pos is > size the behavior is undefined.

The returned reference is valid while this object is unless reserve or shrink_to_fit is called.

Referenced by at(), at(), cetl::VariableLengthArray< bool, Allocator >::at(), cetl::VariableLengthArray< bool, Allocator >::at(), cetl::VariableLengthArray< bool, Allocator >::back(), cetl::VariableLengthArray< bool, Allocator >::back(), cetl::VariableLengthArray< bool, Allocator >::front(), and cetl::VariableLengthArray< bool, Allocator >::front().

Here is the caller graph for this function:

◆ operator[]() [2/2]

template<typename T, typename Allocator>

value_type & cetl::VariableLengthArray< T, Allocator >::operator[] ( size_type pos )

inlineconstexprnoexcept

Direct access to an element.

If pos is > size the behavior is undefined.

The returned reference is valid while this object is unless reserve or shrink_to_fit is called.

Parameters

pos	The index of the element to access.

Returns: A reference to the element at pos.

◆ pop_back()

template<typename T, typename Allocator>

void cetl::VariableLengthArray< T, Allocator >::pop_back ( )

inlineconstexprnoexcept

Remove and destroy the last item in the array.

This reduces the array size by 1 unless the array is already empty.

◆ push_back() [1/2]

template<typename T, typename Allocator>

void cetl::VariableLengthArray< T, Allocator >::push_back ( const value_type & value )

inlineconstexpr

Allocate a new element on to the back of the array and copy value into it.

Grows size by 1 and may grow capacity.

If exceptions are disabled the caller must check before and after to see if the size grew to determine success. If using exceptions this method throws std::length_error if the size of this collection is at capacity or std::bad_alloc if the allocator failed to provide enough memory.

If exceptions are disabled use the following logic:

const size_t size_before = my_array.size();
my_array.push_back(element);
if (size_before == my_array.size())
{
    // failure
    if (size_before == my_array.max_size())
    {
        // length_error: you probably should have checked this first.
    }
    else
    {
        // bad_alloc: out of memory
    }
} // else, success.

◆ push_back() [2/2]

template<typename T, typename Allocator>

void cetl::VariableLengthArray< T, Allocator >::push_back ( value_type && value )

inlineconstexpr

Allocate a new element on to the back of the array and move value into it.

Grows size by 1 and may grow capacity.

See VariableLengthArray::push_back(value_type&) for full documentation.

Exceptions

std::length_error	if the size of this collection is at capacity.
std::bad_alloc	if memory was needed and none could be allocated.

References std::forward().

◆ reserve()

template<typename T, typename Allocator>

void cetl::VariableLengthArray< T, Allocator >::reserve ( const size_type desired_capacity )

inline

Ensure enough memory is allocated to store at least the desired_capacity number of elements.

Parameters

desired_capacity The number of elements to allocate, but not initialize, memory for.

References max_size(), and cetl::VariableLengthArrayBase< T, Allocator >::reserve().

Referenced by VariableLengthArray(), and VariableLengthArray().

Here is the caller graph for this function:

◆ resize() [1/2]

template<typename T, typename Allocator>

void cetl::VariableLengthArray< T, Allocator >::resize ( size_type count )

inlineconstexpr

Resizes internal storage to count elements default initializing any added elements over the current size() and deleting any elements under the current size().

If size() == count then this method has no effect.

Parameters

count The new size to set for this container.

Exceptions

*	If exceptions are enabled then any exceptions that `value_type` constructors or destructors throw will escape this call
std::length_error	if the size requested is greater than `max_size()`.
std::bad_alloc	if the container cannot obtain enough memory to size up to `count`.

References max_size().

Referenced by assign(), cetl::VariableLengthArray< bool, Allocator >::assign(), and cetl::VariableLengthArray< bool, Allocator >::resize().

Here is the caller graph for this function:

◆ resize() [2/2]

template<typename T, typename Allocator>

void cetl::VariableLengthArray< T, Allocator >::resize	(	size_type	count,
		const value_type &	value )

inlineconstexpr

Resizes internal storage to count elements copy-initializing any added elements over the current size() and deleting any elements under the current size().

If size() == count then this method has no effect.

Parameters

count	The new size to set for this container.
value	The value to copy into any new elements created by the operation.

Exceptions

*	If exceptions are enabled then any exceptions that `value_type` constructors or destructors throw will escape this call
std::length_error	if the size requested is greater than `max_size()`.
std::bad_alloc	if the container cannot obtain enough memory to size up to `count`.

References max_size().

◆ shrink_to_fit()

template<typename T, typename Allocator>

void cetl::VariableLengthArray< T, Allocator >::shrink_to_fit ( )

inline

Reduce the amount of memory held by this object to the minimum required based on size.

This method may not actually deallocate any memory if if there is not enough memory to allocate a smaller buffer before moving the existing elements and freeing the larger buffer.

Exceptions

if	any items throw while being moved.

References cetl::VariableLengthArrayBase< T, Allocator >::shrink_to_fit().

◆ size()

template<typename T, typename Allocator>

size_type cetl::VariableLengthArray< T, Allocator >::size ( ) const

inlineconstexprnoexcept

The current number of elements in the array.

This number increases with each successful call to push_back and decreases with each call to pop_back (when size is > 0).

Referenced by at(), at(), cetl::VariableLengthArray< bool, Allocator >::at(), cetl::VariableLengthArray< bool, Allocator >::at(), back(), back(), cetl::VariableLengthArray< bool, Allocator >::back(), cetl::VariableLengthArray< bool, Allocator >::back(), front(), front(), cetl::VariableLengthArray< bool, Allocator >::front(), cetl::VariableLengthArray< bool, Allocator >::front(), and cetl::VariableLengthArray< bool, Allocator >::set().

Here is the caller graph for this function:

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

/__w/CETL/CETL/include/cetl/variable_length_array.hpp

	CETL 0.0.0

Public Types

Public Member Functions

Protected Types

Protected Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ allocator_type

◆ const_iterator

◆ const_reference

◆ difference_type

◆ iterator

◆ pointer

◆ reference

◆ size_type

◆ value_type

Constructor & Destructor Documentation

◆ VariableLengthArray() [1/6]

◆ VariableLengthArray() [2/6]

◆ VariableLengthArray() [3/6]

◆ VariableLengthArray() [4/6]

◆ VariableLengthArray() [5/6]

◆ VariableLengthArray() [6/6]

Member Function Documentation

◆ assign()

◆ at() [1/2]

◆ at() [2/2]

◆ back() [1/2]

◆ back() [2/2]

◆ begin()

◆ capacity()

◆ cbegin()

◆ cend()

◆ clear()

◆ data() [1/2]

◆ data() [2/2]

◆ emplace_back()

◆ empty()

◆ end()

◆ front() [1/2]

◆ front() [2/2]

◆ get_allocator()

◆ max_size()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ pop_back()

◆ push_back() [1/2]

◆ push_back() [2/2]

◆ reserve()

◆ resize() [1/2]

◆ resize() [2/2]

◆ shrink_to_fit()

◆ size()