fprime/Fw/DataStructures/docs/ExternalRedBlackTreeSet.md

ExternalRedBlackTreeSet

ExternalRedBlackTreeSet is a final class template defined in Fw/DataStructures. It represents a set based on a red-black tree with external storage. Internally it maintains an RedBlackTreeSetOrMapImpl as the set implementation.

1. Template Parameters

ExternalRedBlackTreeSet has the following template parameters.

Kind	Name	Purpose
typename	T	The type of an element in the set

2. Base Class

ExternalRedBlackTreeSet is publicly derived from SetBase<T>.

3. Public Types

ExternalRedBlackTreeSet defines the following public types:

Name	Definition
ConstIterator	Alias of MapConstIterator<T>
Entry	Alias of SetOrMapImplEntry<T, Nil>

The type Nil is defined in this file.

4. Private Member Variables

ExternalRedBlackTreeSet has the following private member variables.

Name	Type	Purpose	Default Value
m_impl	RedBlackTreeSetOrMapImpl<T, Nil>	The set implementation	C++ default initialization

The type Nil is defined in this file.

classDiagram
    ExternalRedBlackTreeSet *-- RedBlackTreeSetOrMapImpl

5. Public Constructors and Destructors

5.1. Zero-Argument Constructor

ExternalRedBlackTreeSet()

Initialize each member variable with its default value.

Example:

ExternalRedBlackTreeSet<U32> set;

5.2. Constructor Providing Typed Backing Storage

ExternalRedBlackTreeSet(Entry* entries, FwSizeType capacity)

entries must point to a primitive array of at least capacity elements of type Entry. The type Entry is defined in this section.

Call setStorage(entries, capacity).

Example:

using Set = ExternalRedBlackTreeSet<U32>;
constexpr FwSizeType capacity = 10;
Set::Entry entries[capacity];
Set set(entries, capacity);

5.3. Constructor Providing Untyped Backing Storage

ExternalRedBlackTreeSet(ByteArray data, FwSizeType capacity)

data must be aligned according to getByteArrayAlignment() and must contain at least getByteArraySize(capacity) bytes.

Call setStorage(data, capacity).

Example:

using Set = ExternalRedBlackTreeSet<U32>;
constexpr FwSizeType capacity = 10;
constexpr U8 alignment = Set::getByteArrayAlignment();
constexpr FwSizeType byteArraySize = Set::getByteArraySize(capacity);
alignas(alignment) U8 bytes[byteArraySize];
ExternalRedBlackTreeSet<U32> set(ByteArray(&bytes[0], sizeof bytes), capacity);

5.4. Copy Constructor

ExternalRedBlackTreeSet(const ExternalRedBlackTreeSet<T>& set)

Set *this = set.

Example:

using Set = ExternalRedBlackTreeSet<U32>;
constexpr FwSizeType capacity = 3;
Set::Entry entries[capacity];
// Call the constructor providing backing storage
Set m1(entries, capacity);
// Insert an item
const auto status = m1.insert(42);
ASSERT_EQ(status, Success::SUCCESS);
// Call the copy constructor
Set m2(m1);
ASSERT_EQ(m2.getSize(), 1);

5.5. Destructor

~ExternalRedBlackTreeSet() override

Defined as = default.

6. Public Member Functions

6.1. operator=

ExternalRedBlackTreeSet<T>& operator=(const ExternalRedBlackTreeSet<T>& set)

1. If &set != this

   1. Set m_impl = set.m_impl.

2. Return *this.

Example:

using Set = ExternalRedBlackTreeSet<U32>;
constexpr FwSizeType capacity = 3;
Set::Entry entries[capacity];
// Call the constructor providing backing storage
Set m1(entries, capacity);
// Insert an item
const auto status = m1.insert(42);
ASSERT_EQ(status, Success::SUCCESS);
// Call the default constructor
Set m2;
ASSERT_EQ(m2.getSize(), 0);
// Call the copy assignment operator
m2 = m1;
ASSERT_EQ(m2.getSize(), 1);

6.2. begin

ConstIterator begin() const

Return m_impl.begin().

Example:

using Set = ExternalRedBlackTreeSet<U32>;
constexpr FwSizeType capacity = 10;
Set::Entry entries[capacity];
// Call the constructor providing backing storage
Set set(entries, capacity);
// Insert an entry in the set
const auto status = set.insert(42);
ASSERT_EQ(status, Fw::Success::SUCCESS);
// Get a set const iterator object
auto it = set.begin();
// Use the iterator to access the element
ASSERT_EQ(*it, 42);

6.3. clear

void clear() override

Call m_impl.clear().

Example:

using Set = ExternalRedBlackTreeSet<U32>;
constexpr FwSizeType capacity = 10;
Set::Entry entries[capacity];
Set set(entries, capacity);
const auto status = set.insert(42);
ASSERT_EQ(set.getSize(), 1);
set.clear();
ASSERT_EQ(set.getSize(), 0);

6.4. end

ConstIterator end() const

Return m_impl.end().

Example:

using Set = ExternalRedBlackTreeSet<U32>;
constexpr FwSizeType capacity = 10;
Set::Entry entries[capacity];
// Call the constructor providing backing storage
Set set(entries, capacity);
// Insert an entry in the set
auto status = set.insert(42);
ASSERT_EQ(status, Fw::Success::SUCCESS);
// Get a set const iterator object
auto iter = set.begin();
// Check that iter is not at the end
ASSERT_NE(iter, set.end());
// Increment iter
it++;
// Check that iter is at the end
ASSERT_EQ(iter, set.end());

6.5. find

Success find(const T& element) override

1. Set Nil nil = {}.

2. Return m_impl.find(key, nil).

Example:

using Set = ExternalRedBlackTreeSet<U32>;
constexpr FwSizeType capacity = 10;
Set::Entry entries[capacity];
Set set(entries, capacity);
auto status = set.find(42);
ASSERT_EQ(status, Success::FAILURE);
status = set.insert(42);
ASSERT_EQ(status, Success::SUCCESS);
status = set.find(42);
ASSERT_EQ(status, Success::SUCCESS);

6.6. getCapacity

FwSizeType getCapacity() const override

Return m_impl.getCapacity().

Example:

using Set = ExternalRedBlackTreeSet<U32>;
constexpr FwSizeType capacity = 10;
Set::Entry entries[capacity];
Set set(entries, capacity);
ASSERT_EQ(set.getCapacity(), capacity);

6.8. getSize

FwSizeType getSize() const override

Return m_impl.getSize().

Example:

using Set = ExternalRedBlackTreeSet<U32>;
constexpr FwSizeType capacity = 10;
Set::Entry entries[capacity];
Set set(entries, capacity);
auto size = set.getSize();
ASSERT_EQ(size, 0);
const auto status = set.insert(42);
ASSERT_EQ(status, Success::SUCCESS);
size = set.getSize();
ASSERT_EQ(size, 1);

6.9. insert

Success insert(const T& element) override

Return m_impl.insert(key, Nil()).

Example:

using Set = ExternalRedBlackTreeSet<U32>;
constexpr FwSizeType capacity = 10;
Set::Entry entries[capacity];
Set set(entries, capacity);
auto size = set.getSize();
ASSERT_EQ(size, 0);
const auto status = set.insert(42);
ASSERT_EQ(status, Success::SUCCESS);
size = set.getSize();
ASSERT_EQ(size, 1);

6.10. remove

Success remove(const T& element) override

1. Set Nil nil = {}.

2. Return m_impl.remove(key, nil).

Example:

using Set = ExternalRedBlackTreeSet<U32>;
constexpr FwSizeType capacity = 10;
Set::Entry entries[capacity];
Set set(entries, capacity);
auto size = set.getSize();
ASSERT_EQ(size, 0);
auto status = set.insert(42);
ASSERT_EQ(status, Success::SUCCESS);
size = set.getSize();
ASSERT_EQ(size, 1);
// Element does not exist
status = set.remove(0);
ASSERT_EQ(status, Success::FAILURE);
ASSERT_EQ(size, 1);
// Element exists
status = set.remove(42);
ASSERT_EQ(status, Success::SUCCESS);
ASSERT_EQ(size, 0);

6.11. setStorage (Typed Data)

void setStorage(Entry* entries, FwSizeType capacity)

entries must point to a primitive array of at least capacity elements of type Entry. The type Entry is defined in this section.

Call m_impl.setStorage(entries, capacity).

Example:

using Set = ExternalRedBlackTreeSet<U32>;
constexpr FwSizeType capacity = 10;
Set set;
Set::Entry entries[capacity];
set.setStorage(entries, capacity);

6.12. setStorage (Untyped Data)

void setStorage(ByteArray data, FwSizeType capacity)

data must be aligned according to getByteArrayAlignment() and must contain at least getByteArraySize(capacity) bytes.

1. Call m_entries.setStorage(data, capacity).

2. Call clear().

using Set = ExternalRedBlackTreeSet<U32>;
constexpr FwSizeType capacity = 10;
constexpr U8 alignment = Set::getByteArrayAlignment();
constexpr FwSizeType byteArraySize = Set::getByteArraySize(capacity);
alignas(alignment) U8 bytes[byteArraySize];
Set set;
set.setStorage(ByteArray(&bytes[0], sizeof bytes), capacity);

7. Public Static Functions

7.1. getByteArrayAlignment

static constexpr U8 getByteArrayAlignment()

Return RedBlackTreeSetOrMapImpl<Entry>::getByteArrayAlignment().

7.2. getByteArraySize

static constexpr FwSizeType getByteArraySize(FwSizeType capacity)

Return RedBlackTreeSetOrMapImpl<Entry>::getByteArraySize(capacity).