ArrayView.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2017-2017 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef BLE_ARRAY_VIEW_H_
00018 #define BLE_ARRAY_VIEW_H_
00019 
00020 #include <algorithm>
00021 
00022 #include <stddef.h>
00023 #include <stdint.h>
00024 #include "platform/mbed_assert.h"
00025 
00026 /**
00027  * @addtogroup ble
00028  * @{
00029  * @addtogroup common
00030  * @{
00031  */
00032 
00033 /**
00034  * @file
00035  */
00036 
00037 namespace ble {
00038 
00039 /**
00040  * Special value for the Size parameter of ArrayView.
00041  * If the type use this value then the size of the array is stored in the object
00042  * at runtime.
00043  */
00044 #define ARRAY_VIEW_DYNAMIC_SIZE -1
00045 
00046 /**
00047  * Immutable view to an array.
00048  *
00049  * Array views encapsulate the pointer to an array and its size into a single
00050  * object or type; however, it does not manage the lifetime of the array viewed.
00051  * You can use instances of ArrayView to replace the traditional pair of pointer
00052  * and size arguments in function calls.
00053  *
00054  * You can use the size member function to query the number of elements present
00055  * in the array, and overloads of the subscript operator allow code using
00056  * this object to access to the content of the array viewed.
00057  *
00058  * @note You can create ArrayView instances with the help of the function
00059  * template make_ArrayView() and make_const_ArrayView().
00060  *
00061  * @note ArrayView<T, Size> objects can be implicitly converted to ArrayView<T>
00062  * objects where required.
00063  *
00064  * @tparam T type of objects held by the array.
00065  * @tparam Size The size of the array viewed. The default value
00066  * ARRAY_VIEW_DYNAMIC_SIZE is special as it allows construction of ArrayView
00067  * objects of any size (set at runtime).
00068  */
00069 template<typename T, ptrdiff_t Size = ARRAY_VIEW_DYNAMIC_SIZE>
00070 struct ArrayView {
00071 
00072     MBED_STATIC_ASSERT(Size >= 0, "Invalid size for an ArrayView");
00073 
00074     /**
00075      * Construct a view to an empty array.
00076      *
00077      * @post a call to size() will return 0, and data() will return NULL.
00078      */
00079     ArrayView() : _array(NULL) { }
00080 
00081     /**
00082      * Construct an array view from a pointer to a buffer.
00083      *
00084      * @param array_ptr Pointer to the array data
00085      * @param array_size Number of elements of T present in the array.
00086      *
00087      * @post a call to size() will return array_size and data() will return
00088      * array_tpr.
00089      */
00090     ArrayView(T* array_ptr, size_t array_size) :
00091         _array(array_ptr) {
00092         MBED_ASSERT(array_size >= (size_t) Size);
00093     }
00094 
00095     /**
00096      * Construct an array view from the reference to an array.
00097      *
00098      * @param elements Reference to the array viewed.
00099      *
00100      * @tparam Size Number of elements of T presents in the array.
00101      *
00102      * @post a call to size() will return Size, and data() will return
00103      * a pointer to elements.
00104      */
00105     ArrayView(T (&elements)[Size]):
00106         _array(elements) { }
00107 
00108     /**
00109      * Return the size of the array viewed.
00110      *
00111      * @return The number of elements present in the array viewed.
00112      */
00113     size_t size() const
00114     {
00115         return _array ? Size : 0;
00116     }
00117 
00118     /**
00119      * Access to a mutable element of the array.
00120      *
00121      * @param index Element index to access.
00122      *
00123      * @return A reference to the element at the index specified in input.
00124      *
00125      * @pre index shall be less than size().
00126      */
00127     T& operator[](size_t index)
00128     {
00129         return _array[index];
00130     }
00131 
00132     /**
00133      * Access to an immutable element of the array.
00134      *
00135      * @param index Element index to access.
00136      *
00137      * @return A const reference to the element at the index specified in input.
00138      *
00139      * @pre index shall be less than size().
00140      */
00141     const T& operator[](size_t index) const
00142     {
00143         return _array[index];
00144     }
00145 
00146     /**
00147      * Get the raw pointer to the array.
00148      *
00149      * @return The raw pointer to the array.
00150      */
00151     T* data()
00152     {
00153         return _array;
00154     }
00155 
00156     /**
00157      * Get the raw const pointer to the array.
00158      *
00159      * @return The raw pointer to the array.
00160      */
00161     const T* data() const
00162     {
00163         return _array;
00164     }
00165 
00166 private:
00167     T* const _array;
00168 };
00169 
00170 /**
00171  * ArrayView specialisation that handle dynamic array size.
00172  */
00173 template<typename T>
00174 struct ArrayView<T, ARRAY_VIEW_DYNAMIC_SIZE> {
00175 
00176     /**
00177      * Construct a view to an empty array.
00178      *
00179      * @post a call to size() will return 0, and data() will return NULL.
00180      */
00181     ArrayView() : _array(0), _size(0) { }
00182 
00183     /**
00184      * Construct an array view from a pointer to a buffer and its size.
00185      *
00186      * @param array_ptr Pointer to the array data
00187      * @param array_size Number of elements of T present in the array.
00188      *
00189      * @post a call to size() will return array_size and data() will return
00190      * array_tpr.
00191      */
00192     ArrayView(T* array_ptr, size_t array_size) :
00193         _array(array_ptr), _size(array_size) { }
00194 
00195     /**
00196      * Construct an array view from the reference to an array.
00197      *
00198      * @param elements Reference to the array viewed.
00199      *
00200      * @tparam Size Number of elements of T presents in the array.
00201      *
00202      * @post a call to size() will return Size, and data() will return
00203      * a pointer to elements.
00204      */
00205     template<size_t Size>
00206     ArrayView(T (&elements)[Size]):
00207         _array(elements), _size(Size) { }
00208 
00209 
00210     /**
00211      * Construct a ArrayView object with a dynamic size from an ArrayView object
00212      * with a static size.
00213      * @param other The ArrayView object used to construct this.
00214      */
00215     template<size_t Size>
00216     ArrayView(ArrayView<T, Size> other):
00217         _array(other.data()), _size(other.size()) { }
00218 
00219     /**
00220      * Return the size of the array viewed.
00221      *
00222      * @return The number of elements present in the array viewed.
00223      */
00224     size_t size() const
00225     {
00226         return _size;
00227     }
00228 
00229     /**
00230      * Access to a mutable element of the array.
00231      *
00232      * @param index Element index to access.
00233      *
00234      * @return A reference to the element at the index specified in input.
00235      *
00236      * @pre index shall be less than size().
00237      */
00238     T& operator[](size_t index)
00239     {
00240         return _array[index];
00241     }
00242 
00243     /**
00244      * Access to an immutable element of the array.
00245      *
00246      * @param index Element index to access.
00247      *
00248      * @return A const reference to the element at the index specified in input.
00249      *
00250      * @pre index shall be less than size().
00251      */
00252     const T& operator[](size_t index) const
00253     {
00254         return _array[index];
00255     }
00256 
00257     /**
00258      * Get the raw pointer to the array.
00259      *
00260      * @return The raw pointer to the array.
00261      */
00262     T* data()
00263     {
00264         return _array;
00265     }
00266 
00267     /**
00268      * Get the raw const pointer to the array.
00269      *
00270      * @return The raw pointer to the array.
00271      */
00272     const T* data() const
00273     {
00274         return _array;
00275     }
00276 
00277 private:
00278     T* const _array;
00279     const size_t _size;
00280 };
00281 
00282 
00283 /**
00284  * Equality operator.
00285  *
00286  * @param lhs Left hand side of the binary operation.
00287  * @param rhs Right hand side of the binary operation.
00288  *
00289  * @return True if arrays in input have the same size and the same content
00290  * and false otherwise.
00291  */
00292 template<typename T, ptrdiff_t LhsSize, ptrdiff_t RhsSize>
00293 bool operator==(const ArrayView<T, LhsSize>& lhs, const ArrayView<T, LhsSize>& rhs)
00294 {
00295     if (lhs.size() != rhs.size()) {
00296         return false;
00297     }
00298 
00299     if (lhs.data() == rhs.data()) {
00300         return true;
00301     }
00302 
00303     return std::equal(lhs.data(), lhs.data() + lhs.size(), rhs.data());
00304 }
00305 
00306 /**
00307  * Not equal operator
00308  *
00309  * @param lhs Left hand side of the binary operation.
00310  * @param rhs Right hand side of the binary operation.
00311  *
00312  * @return True if arrays in input do not have the same size or the same
00313  * content and false otherwise.
00314  */
00315 template<typename T, ptrdiff_t LhsSize, ptrdiff_t RhsSize>
00316 bool operator!=(const ArrayView<T, LhsSize>& lhs, const ArrayView<T, LhsSize>& rhs)
00317 {
00318     return !(lhs == rhs);
00319 }
00320 
00321 
00322 /**
00323  * Generate an array view from a reference to a C/C++ array.
00324  *
00325  * @tparam T Type of elements held in elements.
00326  * @tparam Size Number of items held in elements.
00327  *
00328  * @param elements The reference to the array viewed.
00329  *
00330  * @return The ArrayView to elements.
00331  *
00332  * @note This helper avoids the typing of template parameter when ArrayView is
00333  * created 'inline'.
00334  */
00335 template<typename T, size_t Size>
00336 ArrayView<T, Size> make_ArrayView(T (&elements)[Size])
00337 {
00338     return ArrayView<T, Size>(elements);
00339 }
00340 
00341 /**
00342  * Generate an array view from a pointer to a C/C++ array.
00343  *
00344  * @tparam Size Number of items held in elements.
00345  * @tparam T Type of elements held in elements.
00346  *
00347  * @param elements The reference to the array viewed.
00348  *
00349  * @return The ArrayView to elements.
00350  *
00351  * @note This helper avoids the typing of template parameter when ArrayView is
00352  * created 'inline'.
00353  */
00354 template<size_t Size, typename T>
00355 ArrayView<T, Size> make_ArrayView(T* elements)
00356 {
00357     return ArrayView<T, Size>(elements, Size);
00358 }
00359 
00360 /**
00361  * Generate an array view from a C/C++ pointer and the size of the array.
00362  *
00363  * @tparam T Type of elements held in array_ptr.
00364  *
00365  * @param array_ptr The pointer to the array to viewed.
00366  * @param array_size The number of T elements in the array.
00367  *
00368  * @return The ArrayView to array_ptr with a size of array_size.
00369  *
00370  * @note This helper avoids the typing of template parameter when ArrayView is
00371  * created 'inline'.
00372  */
00373 template<typename T>
00374 ArrayView<T> make_ArrayView(T* array_ptr, size_t array_size)
00375 {
00376     return ArrayView<T>(array_ptr, array_size);
00377 }
00378 
00379 /**
00380  * Generate a const array view from a reference to a C/C++ array.
00381  *
00382  * @tparam T Type of elements held in elements.
00383  * @tparam Size Number of items held in elements.
00384  *
00385  * @param elements The array viewed.
00386  * @return The ArrayView to elements.
00387  *
00388  * @note This helper avoids the typing of template parameter when ArrayView is
00389  * created 'inline'.
00390  */
00391 template<typename T, size_t Size>
00392 ArrayView<const T, Size> make_const_ArrayView(T (&elements)[Size])
00393 {
00394     return ArrayView<const T, Size>(elements);
00395 }
00396 
00397 /**
00398  * Generate a const array view from a pointer to a C/C++ array.
00399  *
00400  * @tparam Size Number of items held in elements.
00401  * @tparam T Type of elements held in elements.
00402  *
00403  * @param elements The reference to the array viewed.
00404  *
00405  * @return The ArrayView to elements.
00406  *
00407  * @note This helper avoids the typing of template parameter when ArrayView is
00408  * created 'inline'.
00409  */
00410 template<size_t Size, typename T>
00411 ArrayView<const T, Size> make_const_ArrayView(const T* elements)
00412 {
00413     return ArrayView<const T, Size>(elements, Size);
00414 }
00415 
00416 /**
00417  * Generate a const array view from a C/C++ pointer and the size of the array.
00418  *
00419  * @tparam T Type of elements held in array_ptr.
00420  *
00421  * @param array_ptr The pointer to the array to viewed.
00422  * @param array_size The number of T elements in the array.
00423  *
00424  * @return The ArrayView to array_ptr with a size of array_size.
00425  *
00426  * @note This helper avoids the typing of template parameter when ArrayView is
00427  * created 'inline'.
00428  */
00429 template<typename T>
00430 ArrayView<const T> make_const_ArrayView(T* array_ptr, size_t array_size)
00431 {
00432     return ArrayView<const T>(array_ptr, array_size);
00433 }
00434 
00435 } // namespace ble
00436 
00437 /**
00438  * @}
00439  * @}
00440  */
00441 
00442 
00443 #endif /* BLE_ARRAY_VIEW_H_ */