Mistake on this page?
Report an issue in GitHub or email us
ArrayView.h
Go to the documentation of this file.
1 /* mbed Microcontroller Library
2  * Copyright (c) 2017-2017 ARM Limited
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef BLE_ARRAY_VIEW_H_
18 #define BLE_ARRAY_VIEW_H_
19 
20 #include <algorithm>
21 
22 #include <stddef.h>
23 #include <stdint.h>
24 #include "platform/mbed_assert.h"
25 
26 /**
27  * @addtogroup ble
28  * @{
29  * @addtogroup common
30  * @{
31  */
32 
33 /**
34  * @file
35  */
36 
37 namespace ble {
38 
39 /**
40  * Special value for the Size parameter of ArrayView.
41  * If the type use this value then the size of the array is stored in the object
42  * at runtime.
43  */
44 #define ARRAY_VIEW_DYNAMIC_SIZE -1
45 
46 /**
47  * Immutable view to an array.
48  *
49  * Array views encapsulate the pointer to an array and its size into a single
50  * object or type; however, it does not manage the lifetime of the array viewed.
51  * You can use instances of ArrayView to replace the traditional pair of pointer
52  * and size arguments in function calls.
53  *
54  * You can use the size member function to query the number of elements present
55  * in the array, and overloads of the subscript operator allow code using
56  * this object to access to the content of the array viewed.
57  *
58  * @note You can create ArrayView instances with the help of the function
59  * template make_ArrayView() and make_const_ArrayView().
60  *
61  * @note ArrayView<T, Size> objects can be implicitly converted to ArrayView<T>
62  * objects where required.
63  *
64  * @tparam T type of objects held by the array.
65  * @tparam Size The size of the array viewed. The default value
66  * ARRAY_VIEW_DYNAMIC_SIZE is special as it allows construction of ArrayView
67  * objects of any size (set at runtime).
68  */
69 template<typename T, ptrdiff_t Size = ARRAY_VIEW_DYNAMIC_SIZE>
70 struct ArrayView {
71 
72  MBED_STATIC_ASSERT(Size >= 0, "Invalid size for an ArrayView");
73 
74  /**
75  * Construct a view to an empty array.
76  *
77  * @post a call to size() will return 0, and data() will return NULL.
78  */
79  ArrayView() : _array(NULL) { }
80 
81  /**
82  * Construct an array view from a pointer to a buffer.
83  *
84  * @param array_ptr Pointer to the array data
85  * @param array_size Number of elements of T present in the array.
86  *
87  * @post a call to size() will return array_size and data() will return
88  * array_tpr.
89  */
90  ArrayView(T* array_ptr, size_t array_size) :
91  _array(array_ptr) {
92  MBED_ASSERT(array_size >= (size_t) Size);
93  }
94 
95  /**
96  * Construct an array view from the reference to an array.
97  *
98  * @param elements Reference to the array viewed.
99  *
100  * @tparam Size Number of elements of T presents in the array.
101  *
102  * @post a call to size() will return Size, and data() will return
103  * a pointer to elements.
104  */
105  ArrayView(T (&elements)[Size]):
106  _array(elements) { }
107 
108  /**
109  * Return the size of the array viewed.
110  *
111  * @return The number of elements present in the array viewed.
112  */
113  size_t size() const
114  {
115  return _array ? Size : 0;
116  }
117 
118  /**
119  * Access to a mutable element of the array.
120  *
121  * @param index Element index to access.
122  *
123  * @return A reference to the element at the index specified in input.
124  *
125  * @pre index shall be less than size().
126  */
127  T& operator[](size_t index)
128  {
129  return _array[index];
130  }
131 
132  /**
133  * Access to an immutable element of the array.
134  *
135  * @param index Element index to access.
136  *
137  * @return A const reference to the element at the index specified in input.
138  *
139  * @pre index shall be less than size().
140  */
141  const T& operator[](size_t index) const
142  {
143  return _array[index];
144  }
145 
146  /**
147  * Get the raw pointer to the array.
148  *
149  * @return The raw pointer to the array.
150  */
151  T* data()
152  {
153  return _array;
154  }
155 
156  /**
157  * Get the raw const pointer to the array.
158  *
159  * @return The raw pointer to the array.
160  */
161  const T* data() const
162  {
163  return _array;
164  }
165 
166 private:
167  T* const _array;
168 };
169 
170 /**
171  * ArrayView specialisation that handle dynamic array size.
172  */
173 template<typename T>
175 
176  /**
177  * Construct a view to an empty array.
178  *
179  * @post a call to size() will return 0, and data() will return NULL.
180  */
181  ArrayView() : _array(0), _size(0) { }
182 
183  /**
184  * Construct an array view from a pointer to a buffer and its size.
185  *
186  * @param array_ptr Pointer to the array data
187  * @param array_size Number of elements of T present in the array.
188  *
189  * @post a call to size() will return array_size and data() will return
190  * array_tpr.
191  */
192  ArrayView(T* array_ptr, size_t array_size) :
193  _array(array_ptr), _size(array_size) { }
194 
195  /**
196  * Construct an array view from the reference to an array.
197  *
198  * @param elements Reference to the array viewed.
199  *
200  * @tparam Size Number of elements of T presents in the array.
201  *
202  * @post a call to size() will return Size, and data() will return
203  * a pointer to elements.
204  */
205  template<size_t Size>
206  ArrayView(T (&elements)[Size]):
207  _array(elements), _size(Size) { }
208 
209 
210  /**
211  * Construct a ArrayView object with a dynamic size from an ArrayView object
212  * with a static size.
213  * @param other The ArrayView object used to construct this.
214  */
215  template<size_t Size>
217  _array(other.data()), _size(other.size()) { }
218 
219  /**
220  * Return the size of the array viewed.
221  *
222  * @return The number of elements present in the array viewed.
223  */
224  size_t size() const
225  {
226  return _size;
227  }
228 
229  /**
230  * Access to a mutable element of the array.
231  *
232  * @param index Element index to access.
233  *
234  * @return A reference to the element at the index specified in input.
235  *
236  * @pre index shall be less than size().
237  */
238  T& operator[](size_t index)
239  {
240  return _array[index];
241  }
242 
243  /**
244  * Access to an immutable element of the array.
245  *
246  * @param index Element index to access.
247  *
248  * @return A const reference to the element at the index specified in input.
249  *
250  * @pre index shall be less than size().
251  */
252  const T& operator[](size_t index) const
253  {
254  return _array[index];
255  }
256 
257  /**
258  * Get the raw pointer to the array.
259  *
260  * @return The raw pointer to the array.
261  */
262  T* data()
263  {
264  return _array;
265  }
266 
267  /**
268  * Get the raw const pointer to the array.
269  *
270  * @return The raw pointer to the array.
271  */
272  const T* data() const
273  {
274  return _array;
275  }
276 
277 private:
278  T* const _array;
279  const size_t _size;
280 };
281 
282 
283 /**
284  * Equality operator.
285  *
286  * @param lhs Left hand side of the binary operation.
287  * @param rhs Right hand side of the binary operation.
288  *
289  * @return True if arrays in input have the same size and the same content
290  * and false otherwise.
291  */
292 template<typename T, ptrdiff_t LhsSize, ptrdiff_t RhsSize>
294 {
295  if (lhs.size() != rhs.size()) {
296  return false;
297  }
298 
299  if (lhs.data() == rhs.data()) {
300  return true;
301  }
302 
303  return std::equal(lhs.data(), lhs.data() + lhs.size(), rhs.data());
304 }
305 
306 /**
307  * Not equal operator
308  *
309  * @param lhs Left hand side of the binary operation.
310  * @param rhs Right hand side of the binary operation.
311  *
312  * @return True if arrays in input do not have the same size or the same
313  * content and false otherwise.
314  */
315 template<typename T, ptrdiff_t LhsSize, ptrdiff_t RhsSize>
317 {
318  return !(lhs == rhs);
319 }
320 
321 
322 /**
323  * Generate an array view from a reference to a C/C++ array.
324  *
325  * @tparam T Type of elements held in elements.
326  * @tparam Size Number of items held in elements.
327  *
328  * @param elements The reference to the array viewed.
329  *
330  * @return The ArrayView to elements.
331  *
332  * @note This helper avoids the typing of template parameter when ArrayView is
333  * created 'inline'.
334  */
335 template<typename T, size_t Size>
336 ArrayView<T, Size> make_ArrayView(T (&elements)[Size])
337 {
338  return ArrayView<T, Size>(elements);
339 }
340 
341 /**
342  * Generate an array view from a pointer to a C/C++ array.
343  *
344  * @tparam Size Number of items held in elements.
345  * @tparam T Type of elements held in elements.
346  *
347  * @param elements The reference to the array viewed.
348  *
349  * @return The ArrayView to elements.
350  *
351  * @note This helper avoids the typing of template parameter when ArrayView is
352  * created 'inline'.
353  */
354 template<size_t Size, typename T>
356 {
357  return ArrayView<T, Size>(elements, Size);
358 }
359 
360 /**
361  * Generate an array view from a C/C++ pointer and the size of the array.
362  *
363  * @tparam T Type of elements held in array_ptr.
364  *
365  * @param array_ptr The pointer to the array to viewed.
366  * @param array_size The number of T elements in the array.
367  *
368  * @return The ArrayView to array_ptr with a size of array_size.
369  *
370  * @note This helper avoids the typing of template parameter when ArrayView is
371  * created 'inline'.
372  */
373 template<typename T>
374 ArrayView<T> make_ArrayView(T* array_ptr, size_t array_size)
375 {
376  return ArrayView<T>(array_ptr, array_size);
377 }
378 
379 /**
380  * Generate a const array view from a reference to a C/C++ array.
381  *
382  * @tparam T Type of elements held in elements.
383  * @tparam Size Number of items held in elements.
384  *
385  * @param elements The array viewed.
386  * @return The ArrayView to elements.
387  *
388  * @note This helper avoids the typing of template parameter when ArrayView is
389  * created 'inline'.
390  */
391 template<typename T, size_t Size>
393 {
394  return ArrayView<const T, Size>(elements);
395 }
396 
397 /**
398  * Generate a const array view from a pointer to a C/C++ array.
399  *
400  * @tparam Size Number of items held in elements.
401  * @tparam T Type of elements held in elements.
402  *
403  * @param elements The reference to the array viewed.
404  *
405  * @return The ArrayView to elements.
406  *
407  * @note This helper avoids the typing of template parameter when ArrayView is
408  * created 'inline'.
409  */
410 template<size_t Size, typename T>
412 {
413  return ArrayView<const T, Size>(elements, Size);
414 }
415 
416 /**
417  * Generate a const array view from a C/C++ pointer and the size of the array.
418  *
419  * @tparam T Type of elements held in array_ptr.
420  *
421  * @param array_ptr The pointer to the array to viewed.
422  * @param array_size The number of T elements in the array.
423  *
424  * @return The ArrayView to array_ptr with a size of array_size.
425  *
426  * @note This helper avoids the typing of template parameter when ArrayView is
427  * created 'inline'.
428  */
429 template<typename T>
430 ArrayView<const T> make_const_ArrayView(T* array_ptr, size_t array_size)
431 {
432  return ArrayView<const T>(array_ptr, array_size);
433 }
434 
435 } // namespace ble
436 
437 /**
438  * @}
439  * @}
440  */
441 
442 
443 #endif /* BLE_ARRAY_VIEW_H_ */
ArrayView< T, Size > make_ArrayView(T(&elements)[Size])
Generate an array view from a reference to a C/C++ array.
Definition: ArrayView.h:336
T & operator[](size_t index)
Access to a mutable element of the array.
Definition: ArrayView.h:238
bool operator==(const ArrayView< T, LhsSize > &lhs, const ArrayView< T, LhsSize > &rhs)
Equality operator.
Definition: ArrayView.h:293
T * data()
Get the raw pointer to the array.
Definition: ArrayView.h:262
size_t size() const
Return the size of the array viewed.
Definition: ArrayView.h:113
size_t size() const
Return the size of the array viewed.
Definition: ArrayView.h:224
const T * data() const
Get the raw const pointer to the array.
Definition: ArrayView.h:161
ArrayView()
Construct a view to an empty array.
Definition: ArrayView.h:181
ArrayView(T *array_ptr, size_t array_size)
Construct an array view from a pointer to a buffer and its size.
Definition: ArrayView.h:192
Immutable view to an array.
Definition: ArrayView.h:70
#define ARRAY_VIEW_DYNAMIC_SIZE
Special value for the Size parameter of ArrayView.
Definition: ArrayView.h:44
ArrayView(T(&elements)[Size])
Construct an array view from the reference to an array.
Definition: ArrayView.h:105
ArrayView()
Construct a view to an empty array.
Definition: ArrayView.h:79
ArrayView(T *array_ptr, size_t array_size)
Construct an array view from a pointer to a buffer.
Definition: ArrayView.h:90
const T & operator[](size_t index) const
Access to an immutable element of the array.
Definition: ArrayView.h:252
const T & operator[](size_t index) const
Access to an immutable element of the array.
Definition: ArrayView.h:141
bool operator!=(const ArrayView< T, LhsSize > &lhs, const ArrayView< T, LhsSize > &rhs)
Not equal operator.
Definition: ArrayView.h:316
#define MBED_ASSERT(expr)
MBED_ASSERT Declare runtime assertions: results in runtime error if condition is false.
Definition: mbed_assert.h:65
ArrayView< const T, Size > make_const_ArrayView(T(&elements)[Size])
Generate a const array view from a reference to a C/C++ array.
Definition: ArrayView.h:392
T & operator[](size_t index)
Access to a mutable element of the array.
Definition: ArrayView.h:127
T * data()
Get the raw pointer to the array.
Definition: ArrayView.h:151
ArrayView(ArrayView< T, Size > other)
Construct a ArrayView object with a dynamic size from an ArrayView object with a static size...
Definition: ArrayView.h:216
Entry namespace for all BLE API definitions.
Definition: ArrayView.h:37
ArrayView(T(&elements)[Size])
Construct an array view from the reference to an array.
Definition: ArrayView.h:206
const T * data() const
Get the raw const pointer to the array.
Definition: ArrayView.h:272
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.