518 lines
18 KiB
C++
518 lines
18 KiB
C++
/*
|
|
* Copyright (c) 2021, The OpenThread Authors.
|
|
* All rights reserved.
|
|
*
|
|
* Redistribution and use in source and binary forms, with or without
|
|
* modification, are permitted provided that the following conditions are met:
|
|
* 1. Redistributions of source code must retain the above copyright
|
|
* notice, this list of conditions and the following disclaimer.
|
|
* 2. Redistributions in binary form must reproduce the above copyright
|
|
* notice, this list of conditions and the following disclaimer in the
|
|
* documentation and/or other materials provided with the distribution.
|
|
* 3. Neither the name of the copyright holder nor the
|
|
* names of its contributors may be used to endorse or promote products
|
|
* derived from this software without specific prior written permission.
|
|
*
|
|
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
|
|
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
* POSSIBILITY OF SUCH DAMAGE.
|
|
*/
|
|
|
|
/**
|
|
* @file
|
|
* This file includes definitions for a generic array.
|
|
*/
|
|
|
|
#ifndef ARRAY_HPP_
|
|
#define ARRAY_HPP_
|
|
|
|
#include "openthread-core-config.h"
|
|
|
|
#include "common/code_utils.hpp"
|
|
#include "common/const_cast.hpp"
|
|
#include "common/error.hpp"
|
|
#include "common/numeric_limits.hpp"
|
|
#include "common/type_traits.hpp"
|
|
|
|
namespace ot {
|
|
|
|
/**
|
|
* This function returns the length of a given array (number of elements in the array).
|
|
*
|
|
* This template function is `constexpr`. The template arguments are expected to be deduced by the compiler allowing
|
|
* callers to simply use `GetArrayLength(aArray)`.
|
|
*
|
|
* @tparam Type The array element type.
|
|
* @tparam kArrayLength The array length.
|
|
*
|
|
* @returns The array length (number of elements in the array).
|
|
*
|
|
*/
|
|
template <typename Type, uint16_t kArrayLength> constexpr inline uint16_t GetArrayLength(const Type (&)[kArrayLength])
|
|
{
|
|
return kArrayLength;
|
|
}
|
|
|
|
/**
|
|
* This function returns a pointer to end of a given array (pointing to the past-the-end element).
|
|
*
|
|
* Note that the past-the-end element is a theoretical element that would follow the last element in the array. It does
|
|
* not point to an actual element in array, and thus should not be dereferenced.
|
|
*
|
|
* @tparam Type The array element type.
|
|
* @tparam kArrayLength The array length.
|
|
*
|
|
* @param[in] aArray A reference to the array.
|
|
*
|
|
* @returns Pointer to the past-the-end element.
|
|
*
|
|
*/
|
|
template <typename Type, uint16_t kArrayLength> inline Type *GetArrayEnd(Type (&aArray)[kArrayLength])
|
|
{
|
|
return &aArray[kArrayLength];
|
|
}
|
|
|
|
/**
|
|
* This function returns a pointer to end of a given array (pointing to the past-the-end element).
|
|
*
|
|
* Note that the past-the-end element is a theoretical element that would follow the last element in the array. It does
|
|
* not point to an actual element in array, and thus should not be dereferenced.
|
|
*
|
|
* @tparam Type The array element type.
|
|
* @tparam kArrayLength The array length.
|
|
*
|
|
* @param[in] aArray A reference to the array.
|
|
*
|
|
* @returns Pointer to the past-the-end element.
|
|
*
|
|
*/
|
|
template <typename Type, uint16_t kArrayLength> inline const Type *GetArrayEnd(const Type (&aArray)[kArrayLength])
|
|
{
|
|
return &aArray[kArrayLength];
|
|
}
|
|
|
|
/**
|
|
* This template class represents an array of elements with a fixed max size.
|
|
*
|
|
* @tparam Type The array element type.
|
|
* @tparam kMaxSize Specifies the max array size (maximum number of elements in the array).
|
|
* @tparam SizeType The type to be used for array size, length, and index. If not specified, a default `uint` type
|
|
* is determined based on `kMaxSize`, i.e., if `kMaxSize <= 255` then `uint8_t` will be used,
|
|
* otherwise `uint16_t` will be used.
|
|
*
|
|
*/
|
|
template <typename Type,
|
|
uint16_t kMaxSize,
|
|
typename SizeType =
|
|
typename TypeTraits::Conditional<kMaxSize <= NumericLimits<uint8_t>::kMax, uint8_t, uint16_t>::Type>
|
|
class Array
|
|
{
|
|
static_assert(kMaxSize != 0, "Array `kMaxSize` cannot be zero");
|
|
|
|
public:
|
|
/**
|
|
* This type represents the length or index in array.
|
|
*
|
|
* It is typically either `uint8_t` or `uint16_t` (determined based on the maximum array size (`kMaxSize`)).
|
|
*
|
|
*/
|
|
typedef SizeType IndexType;
|
|
|
|
/**
|
|
* This constructor initializes the array as empty.
|
|
*
|
|
*/
|
|
Array(void)
|
|
: mLength(0)
|
|
{
|
|
}
|
|
|
|
/**
|
|
* This constructor initializes the array by copying elements from another array.
|
|
*
|
|
* The method uses assignment `=` operator on `Type` to copy each element from @p aOtherArray into the elements of
|
|
* the array.
|
|
*
|
|
* @param[in] aOtherArray Another array to copy from.
|
|
*
|
|
*/
|
|
Array(const Array &aOtherArray) { *this = aOtherArray; }
|
|
|
|
/**
|
|
* This method clears the array.
|
|
*
|
|
*/
|
|
void Clear(void) { mLength = 0; }
|
|
|
|
/**
|
|
* This method indicates whether or not the array is empty.
|
|
*
|
|
* @retval TRUE when array is empty.
|
|
* @retval FALSE when array is not empty.
|
|
*
|
|
*/
|
|
bool IsEmpty(void) const { return (mLength == 0); }
|
|
|
|
/**
|
|
* This method indicates whether or not the array is full.
|
|
*
|
|
* @retval TRUE when array is full.
|
|
* @retval FALSE when array is not full.
|
|
*
|
|
*/
|
|
bool IsFull(void) const { return (mLength == GetMaxSize()); }
|
|
|
|
/**
|
|
* This method returns the maximum array size (max number of elements).
|
|
*
|
|
* @returns The maximum array size (max number of elements that can be added to the array).
|
|
*
|
|
*/
|
|
IndexType GetMaxSize(void) const { return static_cast<IndexType>(kMaxSize); }
|
|
|
|
/**
|
|
* This method returns the current length of array (number of elements).
|
|
*
|
|
* @returns The current array length.
|
|
*
|
|
*/
|
|
IndexType GetLength(void) const { return mLength; }
|
|
|
|
/**
|
|
* This method overloads the `[]` operator to get the element at a given index.
|
|
*
|
|
* This method does not perform index bounds checking. Behavior is undefined if @p aIndex is not valid.
|
|
*
|
|
* @param[in] aIndex The index to get.
|
|
*
|
|
* @returns A reference to the element in array at @p aIndex.
|
|
*
|
|
*/
|
|
Type &operator[](IndexType aIndex) { return mElements[aIndex]; }
|
|
|
|
/**
|
|
* This method overloads the `[]` operator to get the element at a given index.
|
|
*
|
|
* This method does not perform index bounds checking. Behavior is undefined if @p aIndex is not valid.
|
|
*
|
|
* @param[in] aIndex The index to get.
|
|
*
|
|
* @returns A reference to the element in array at @p aIndex.
|
|
*
|
|
*/
|
|
const Type &operator[](IndexType aIndex) const { return mElements[aIndex]; }
|
|
|
|
/**
|
|
* This method gets a pointer to the element at a given index.
|
|
*
|
|
* Unlike `operator[]`, this method checks @p aIndex to be valid and within the current length.
|
|
*
|
|
* @param[in] aIndex The index to get.
|
|
*
|
|
* @returns A pointer to element in array at @p aIndex or `nullptr` if @p aIndex is not valid.
|
|
*
|
|
*/
|
|
Type *At(IndexType aIndex) { return (aIndex < mLength) ? &mElements[aIndex] : nullptr; }
|
|
|
|
/**
|
|
* This method gets a pointer to the element at a given index.
|
|
*
|
|
* Unlike `operator[]`, this method checks @p aIndex to be valid and within the current length.
|
|
*
|
|
* @param[in] aIndex The index to get.
|
|
*
|
|
* @returns A pointer to element in array at @p aIndex or `nullptr` if @p aIndex is not valid.
|
|
*
|
|
*/
|
|
const Type *At(IndexType aIndex) const { return (aIndex < mLength) ? &mElements[aIndex] : nullptr; }
|
|
|
|
/**
|
|
* This method gets a pointer to the element at the front of the array (first element).
|
|
*
|
|
* @returns A pointer to the front element or `nullptr` if array is empty.
|
|
*
|
|
*/
|
|
Type *Front(void) { return At(0); }
|
|
|
|
/**
|
|
* This method gets a pointer to the element at the front of the array (first element).
|
|
*
|
|
* @returns A pointer to the front element or `nullptr` if array is empty.
|
|
*
|
|
*/
|
|
const Type *Front(void) const { return At(0); }
|
|
|
|
/**
|
|
* This method gets a pointer to the element at the back of the array (last element).
|
|
*
|
|
* @returns A pointer to the back element or `nullptr` if array is empty.
|
|
*
|
|
*/
|
|
Type *Back(void) { return At(mLength - 1); }
|
|
|
|
/**
|
|
* This method gets a pointer to the element at the back of the array (last element).
|
|
*
|
|
* @returns A pointer to the back element or `nullptr` if array is empty.
|
|
*
|
|
*/
|
|
const Type *Back(void) const { return At(mLength - 1); }
|
|
|
|
/**
|
|
* This method appends a new entry to the end of the array.
|
|
*
|
|
* The method uses assignment `=` operator on `Type` to copy @p aEntry into the added array element.
|
|
*
|
|
* @param[in] aEntry The new entry to push back.
|
|
*
|
|
* @retval kErrorNone Successfully pushed back @p aEntry to the end of the array.
|
|
* @retval kErrorNoBufs Could not append the new element since array is full.
|
|
*
|
|
*/
|
|
Error PushBack(const Type &aEntry) { return IsFull() ? kErrorNoBufs : (mElements[mLength++] = aEntry, kErrorNone); }
|
|
|
|
/**
|
|
* This method appends a new entry to the end of the array.
|
|
*
|
|
* On success, this method returns a pointer to the newly appended element in the array for the caller to
|
|
* initialize and use.
|
|
*
|
|
* @return A pointer to the newly appended element or `nullptr` if array is full.
|
|
*
|
|
*/
|
|
Type *PushBack(void) { return IsFull() ? nullptr : &mElements[mLength++]; }
|
|
|
|
/**
|
|
* This method removes the last element in the array.
|
|
*
|
|
* @returns A pointer to the removed element from the array, or `nullptr` if array is empty.
|
|
*
|
|
*/
|
|
Type *PopBack(void) { return IsEmpty() ? nullptr : &mElements[--mLength]; }
|
|
|
|
/**
|
|
* This method returns the index of an element in the array.
|
|
*
|
|
* The @p aElement MUST be from the array, otherwise the behavior of this method is undefined.
|
|
*
|
|
* @param[in] aElement A reference to an element in the array.
|
|
*
|
|
* @returns The index of @p aElement in the array.
|
|
*
|
|
*/
|
|
IndexType IndexOf(const Type &aElement) const { return static_cast<IndexType>(&aElement - &mElements[0]); }
|
|
|
|
/**
|
|
* This method removes an element from the array.
|
|
*
|
|
* The @p aElement MUST be from the array, otherwise the behavior of this method is undefined.
|
|
*
|
|
* To remove @p aElement, it is replaced by the last element in array, so the order of items in the array can
|
|
* change after a call to this method.
|
|
*
|
|
* The method uses assignment `=` operator on `Type` to copy the last element in place of @p aElement.
|
|
*
|
|
*/
|
|
void Remove(Type &aElement)
|
|
{
|
|
Type *lastElement = PopBack();
|
|
|
|
if (lastElement != &aElement)
|
|
{
|
|
aElement = *lastElement;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* This method finds the first match of a given entry in the array.
|
|
*
|
|
* This method uses `==` operator on `Type` to compare the array element with @p aEntry.
|
|
*
|
|
* @param[in] aEntry The entry to search for within the array.
|
|
*
|
|
* @returns A pointer to matched array element, or `nullptr` if a match could not be found.
|
|
*
|
|
*/
|
|
Type *Find(const Type &aEntry) { return AsNonConst(AsConst(this)->Find(aEntry)); }
|
|
|
|
/**
|
|
* This method finds the first match of a given entry in the array.
|
|
*
|
|
* This method uses `==` operator to compare the array elements with @p aEntry.
|
|
*
|
|
* @param[in] aEntry The entry to search for within the array.
|
|
*
|
|
* @returns A pointer to matched array element, or `nullptr` if a match could not be found.
|
|
*
|
|
*/
|
|
const Type *Find(const Type &aEntry) const
|
|
{
|
|
const Type *matched = nullptr;
|
|
|
|
for (const Type &element : *this)
|
|
{
|
|
if (element == aEntry)
|
|
{
|
|
matched = &element;
|
|
break;
|
|
}
|
|
}
|
|
|
|
return matched;
|
|
}
|
|
|
|
/**
|
|
* This method indicates whether or not a match to given entry exists in the array.
|
|
*
|
|
* This method uses `==` operator on `Type` to compare the array elements with @p aEntry.
|
|
*
|
|
* @param[in] aEntry The entry to search for within the array.
|
|
*
|
|
* @retval TRUE The array contains a matching element with @p aEntry.
|
|
* @retval FALSE The array does not contain a matching element with @p aEntry.
|
|
*
|
|
*/
|
|
bool Contains(const Type &aEntry) const { return Find(aEntry) != nullptr; }
|
|
|
|
/**
|
|
* This template method finds the first element in the array matching a given indicator.
|
|
*
|
|
* The template type `Indicator` specifies the type of @p aIndicator object which is used to match against elements
|
|
* in the array. To check that an element matches the given indicator, the `Matches()` method is invoked on each
|
|
* `Type` element in the array. The `Matches()` method should be provided by `Type` class accordingly:
|
|
*
|
|
* bool Type::Matches(const Indicator &aIndicator) const
|
|
*
|
|
* @param[in] aIndicator An indicator to match with elements in the array.
|
|
*
|
|
* @returns A pointer to the matched array element, or `nullptr` if a match could not be found.
|
|
*
|
|
*/
|
|
template <typename Indicator> Type *FindMatching(const Indicator &aIndicator)
|
|
{
|
|
return AsNonConst(AsConst(this)->FindMatching(aIndicator));
|
|
}
|
|
|
|
/**
|
|
* This template method finds the first element in the array matching a given indicator.
|
|
*
|
|
* The template type `Indicator` specifies the type of @p aIndicator object which is used to match against elements
|
|
* in the array. To check that an element matches the given indicator, the `Matches()` method is invoked on each
|
|
* `Type` element in the array. The `Matches()` method should be provided by `Type` class accordingly:
|
|
*
|
|
* bool Type::Matches(const Indicator &aIndicator) const
|
|
*
|
|
* @param[in] aIndicator An indicator to match with elements in the array.
|
|
*
|
|
* @returns A pointer to the matched array element, or `nullptr` if a match could not be found.
|
|
*
|
|
*/
|
|
template <typename Indicator> const Type *FindMatching(const Indicator &aIndicator) const
|
|
{
|
|
const Type *matched = nullptr;
|
|
|
|
for (const Type &element : *this)
|
|
{
|
|
if (element.Matches(aIndicator))
|
|
{
|
|
matched = &element;
|
|
break;
|
|
}
|
|
}
|
|
|
|
return matched;
|
|
}
|
|
|
|
/**
|
|
* This template method indicates whether or not the array contains an element matching a given indicator.
|
|
*
|
|
* The template type `Indicator` specifies the type of @p aIndicator object which is used to match against elements
|
|
* in the array. To check that an element matches the given indicator, the `Matches()` method is invoked on each
|
|
* `Type` element in the array. The `Matches()` method should be provided by `Type` class accordingly:
|
|
*
|
|
* bool Type::Matches(const Indicator &aIndicator) const
|
|
*
|
|
* @param[in] aIndicator An indicator to match with elements in the array.
|
|
*
|
|
* @retval TRUE The array contains a matching element with @p aIndicator.
|
|
* @retval FALSE The array does not contain a matching element with @p aIndicator.
|
|
*
|
|
*/
|
|
template <typename Indicator> bool ContainsMatching(const Indicator &aIndicator) const
|
|
{
|
|
return FindMatching(aIndicator) != nullptr;
|
|
}
|
|
|
|
/**
|
|
* This template method removes the first element in the array matching a given indicator.
|
|
*
|
|
* This method behaves similar to `Remove()`, i.e., the matched element (if found) is replaced with the last element
|
|
* in the array (using `=` operator on `Type`). So the order of items in the array can change after a call to this
|
|
* method.
|
|
*
|
|
* The template type `Indicator` specifies the type of @p aIndicator object which is used to match against elements
|
|
* in the array. To check that an element matches the given indicator, the `Matches()` method is invoked on each
|
|
* `Type` element in the array. The `Matches()` method should be provided by `Type` class accordingly:
|
|
*
|
|
* bool Type::Matches(const Indicator &aIndicator) const
|
|
*
|
|
* @param[in] aIndicator An indicator to match with elements in the array.
|
|
*
|
|
*/
|
|
template <typename Indicator> void RemoveMatching(const Indicator &aIndicator)
|
|
{
|
|
Type *entry = FindMatching(aIndicator);
|
|
|
|
if (entry != nullptr)
|
|
{
|
|
Remove(*entry);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* This method overloads assignment `=` operator to copy elements from another array into the array.
|
|
*
|
|
* The method uses assignment `=` operator on `Type` to copy each element from @p aOtherArray into the elements of
|
|
* the array.
|
|
*
|
|
* @param[in] aOtherArray Another array to copy from.
|
|
*
|
|
*/
|
|
Array &operator=(const Array &aOtherArray)
|
|
{
|
|
Clear();
|
|
|
|
for (const Type &otherElement : aOtherArray)
|
|
{
|
|
IgnoreError(PushBack(otherElement));
|
|
}
|
|
|
|
return *this;
|
|
}
|
|
|
|
// The following methods are intended to support range-based `for`
|
|
// loop iteration over the array elements and should not be used
|
|
// directly.
|
|
|
|
Type * begin(void) { return &mElements[0]; }
|
|
Type * end(void) { return &mElements[mLength]; }
|
|
const Type *begin(void) const { return &mElements[0]; }
|
|
const Type *end(void) const { return &mElements[mLength]; }
|
|
|
|
private:
|
|
Type mElements[kMaxSize];
|
|
IndexType mLength;
|
|
};
|
|
|
|
} // namespace ot
|
|
|
|
#endif // ARRAY_HPP_
|