ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

BLE: Improve ArrayView documentation. 

- Improve detailed description of the class.
- Add undefined params tparams and return documentation.
- Add pre and postcondition when valuable.
- Put the elements of the file in the ble.common group.
pull/5392/head
Vincent Coubard 2017-10-17 12:21:51 +01:00
parent 20d93bf78d
commit 7254ceb01b
1 changed files with 139 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

171
features/FEATURE_BLE/ble/ArrayView.h
View File

@ -20,28 +20,67 @@
#include <stddef.h>
#include <stdint.h>
/**
* @addtogroup ble
* @{
* @addtogroup common
* @{
*/
/**
* @file
*/
namespace ble {
/**
* Immutable view to an array.
*
* Array views encapsulate the pointer to an array and its size into a single
* object however it does not manage the lifetime of the array viewed.
* Instances of ArrayView can be used to replace the traditional pair of pointer
* and size arguments in function calls.
*
* The size member function can be used to query the number of elements present
* in the array and overloads of the subscript operator allow code using
* this object to access to the content of the array viewed.
*
* @note ArrayView instances can be created easily with the help of the function
* template make_ArrayView() and make_const_ArrayView().
*
* @tparam T type of objects held by the array.
*/
template<typename T>
struct ArrayView {
/**
* construct an array view to an empty array
* Construct a view to an empty array.
*
* @post a call to size() will return 0 and data() will return NULL.
*/
ArrayView() : _array(0), _size(0) { }
/**
* construct an array view from a pointer.
* and its size.
* Construct an array view from a pointer to a buffer and its size.
*
* @param array_ptr Pointer to the array data
* @param array_size Number of elements of T present in the array.
*
* @post a call to size() will return array_size and data() will return
* array_tpr.
*/
ArrayView(T* array_ptr, size_t array_size) :
_array(array_ptr), _size(array_size) { }
/**
* Construct an array view from the reference to an array.
*
* @param elements Reference to the array viewed.
*
* @tparam Size Number of elements of T presents in the array.
*
* @post a call to size() will return Size and data() will return
* a pointer to elements.
*/
template<size_t Size>
ArrayView(T (&elements)[Size]):
@ -49,43 +88,73 @@ struct ArrayView {
/**
* Return the size of the array viewed.
*
* @return The number of elements present in the array viewed.
*/
size_t size() const {
size_t size() const
{
return _size;
}
/**
* Access to a mutable element of the array.
*
* @param index Element index to access.
*
* @return A reference to the element at the index specified in input.
*
* @pre index shall be less than size().
*/
T& operator[](size_t index) {
T& operator[](size_t index)
{
return _array[index];
}
/**
* Access to an immutable element of the array.
*
* @param index Element index to access.
*
* @return A const reference to the element at the index specified in input.
*
* @pre index shall be less than size().
*/
const T& operator[](size_t index) const {
const T& operator[](size_t index) const
{
return _array[index];
}
/**
* Get the pointer to the array
* Get the raw pointer to the array.
*
* @return The raw pointer to the array.
*/
T* data() {
T* data()
{
return _array;
}
/**
* Get the pointer to the const array
* Get the raw const pointer to the array.
*
* @return The raw pointer to the array.
*/
const T* data() const {
const T* data() const
{
return _array;
}
/**
* Equality operator
* Equality operator.
*
* @param lhs Left hand side of the binary operation.
* @param rhs Right hand side of the binary operation.
*
* @return True if arrays in input have the same size and the same content
* and false otherwise.
*/
friend bool operator==(const ArrayView& lhs, const ArrayView& rhs) {
friend bool operator==(const ArrayView& lhs, const ArrayView& rhs)
{
if (lhs.size() != rhs.size()) {
return false;
}
@ -99,8 +168,15 @@ struct ArrayView {
/**
* Not equal operator
*
* @param lhs Left hand side of the binary operation.
* @param rhs Right hand side of the binary operation.
*
* @return True if arrays in input does not have the same size or the same
* content and false otherwise.
*/
friend bool operator!=(const ArrayView& lhs, const ArrayView& rhs) {
friend bool operator!=(const ArrayView& lhs, const ArrayView& rhs)
{
return !(lhs == rhs);
}
@ -111,55 +187,86 @@ private:
/**
* Generate an array view from a C/C++ array.
* This helper avoid the typing of template parameter when ArrayView are
* Generate an array view from a reference to a C/C++ array.
*
* @tparam T Type of elements held in elements.
* @tparam Size Number of items held in elements.
*
* @param elements The reference to the array viewed.
*
* @return The ArrayView to elements.
*
* @note This helper avoid the typing of template parameter when ArrayView are
* created 'inline'.
* @param elements The array viewed.
* @return The array_view to elements.
*/
template<typename T, size_t Size>
ArrayView<T> make_ArrayView(T (&elements)[Size]) {
ArrayView<T> make_ArrayView(T (&elements)[Size])
{
return ArrayView<T>(elements);
}
/**
* Generate an array view from a C/C++ pointer and the size of the array.
* This helper avoid the typing of template parameter when ArrayView are
*
* @tparam T Type of elements held in array_ptr.
*
* @param array_ptr The pointer to the array to viewed.
* @param array_size The number of T elements in the array.
*
* @return The ArrayView to array_ptr with a size of array_size.
*
* @note This helper avoid the typing of template parameter when ArrayView are
* created 'inline'.
* @param array_ptr The pointer to the array to view.
* @param array_size The size of the array.
* @return The array_view to array_ptr with a size of array_size.
*/
template<typename T>
ArrayView<T> make_ArrayView(T* array_ptr, size_t array_size) {
ArrayView<T> make_ArrayView(T* array_ptr, size_t array_size)
{
return ArrayView<T>(array_ptr, array_size);
}
/**
* Generate a const array view from a C/C++ array.
* This helper avoid the typing of template parameter when ArrayView are
* created 'inline'.
* Generate a const array view from a reference to a C/C++ array.
*
* @tparam T Type of elements held in elements.
* @tparam Size Number of items held in elements.
*
* @param elements The array viewed.
* @return The ArrayView to elements.
*
* @note This helper avoid the typing of template parameter when ArrayView are
* created 'inline'.
*/
template<typename T, size_t Size>
ArrayView<const T> make_const_ArrayView(T (&elements)[Size]) {
ArrayView<const T> make_const_ArrayView(T (&elements)[Size])
{
return ArrayView<const T>(elements);
}
/**
* Generate a const array view from a C/C++ pointer and the size of the array.
* This helper avoid the typing of template parameter when ArrayView are
* created 'inline'.
* @param array_ptr The pointer to the array to view.
* @param array_size The size of the array.
*
* @tparam T Type of elements held in array_ptr.
*
* @param array_ptr The pointer to the array to viewed.
* @param array_size The number of T elements in the array.
*
* @return The ArrayView to array_ptr with a size of array_size.
*
* @note This helper avoid the typing of template parameter when ArrayView are
* created 'inline'.
*/
template<typename T>
ArrayView<const T> make_const_ArrayView(T* array_ptr, size_t array_size) {
ArrayView<const T> make_const_ArrayView(T* array_ptr, size_t array_size)
{
return ArrayView<const T>(array_ptr, array_size);
}
} // namespace ble
/**
* @}
* @}
*/
#endif /* BLE_ARRAY_VIEW_H_ */