blob: 7e01959b01a4c2ee27b8e20c98912b378355f57f [file] [log] [blame]
kwiberg529662a2017-09-04 12:43:171/*
2 * Copyright 2015 The WebRTC Project Authors. All rights reserved.
3 *
4 * Use of this source code is governed by a BSD-style license
5 * that can be found in the LICENSE file in the root of the source
6 * tree. An additional intellectual property rights grant can be found
7 * in the file PATENTS. All contributing project authors may
8 * be found in the AUTHORS file in the root of the source tree.
9 */
10
Mirko Bonadei92ea95e2017-09-15 04:47:3111#ifndef API_ARRAY_VIEW_H_
12#define API_ARRAY_VIEW_H_
kwiberg529662a2017-09-04 12:43:1713
14#include <algorithm>
Yves Gerey665174f2018-06-19 13:03:0515#include <array>
Alessio Bazzicae2c54852020-10-20 15:24:5516#include <iterator>
kwiberg529662a2017-09-04 12:43:1717#include <type_traits>
18
Mirko Bonadei92ea95e2017-09-15 04:47:3119#include "rtc_base/checks.h"
20#include "rtc_base/type_traits.h"
kwiberg529662a2017-09-04 12:43:1721
22namespace rtc {
23
24// tl;dr: rtc::ArrayView is the same thing as gsl::span from the Guideline
25// Support Library.
26//
27// Many functions read from or write to arrays. The obvious way to do this is
28// to use two arguments, a pointer to the first element and an element count:
29//
30// bool Contains17(const int* arr, size_t size) {
31// for (size_t i = 0; i < size; ++i) {
32// if (arr[i] == 17)
33// return true;
34// }
35// return false;
36// }
37//
38// This is flexible, since it doesn't matter how the array is stored (C array,
39// std::vector, rtc::Buffer, ...), but it's error-prone because the caller has
40// to correctly specify the array length:
41//
42// Contains17(arr, arraysize(arr)); // C array
43// Contains17(arr.data(), arr.size()); // std::vector
44// Contains17(arr, size); // pointer + size
45// ...
46//
47// It's also kind of messy to have two separate arguments for what is
48// conceptually a single thing.
49//
50// Enter rtc::ArrayView<T>. It contains a T pointer (to an array it doesn't
51// own) and a count, and supports the basic things you'd expect, such as
52// indexing and iteration. It allows us to write our function like this:
53//
54// bool Contains17(rtc::ArrayView<const int> arr) {
55// for (auto e : arr) {
56// if (e == 17)
57// return true;
58// }
59// return false;
60// }
61//
62// And even better, because a bunch of things will implicitly convert to
63// ArrayView, we can call it like this:
64//
65// Contains17(arr); // C array
66// Contains17(arr); // std::vector
67// Contains17(rtc::ArrayView<int>(arr, size)); // pointer + size
68// Contains17(nullptr); // nullptr -> empty ArrayView
69// ...
70//
71// ArrayView<T> stores both a pointer and a size, but you may also use
72// ArrayView<T, N>, which has a size that's fixed at compile time (which means
73// it only has to store the pointer).
74//
75// One important point is that ArrayView<T> and ArrayView<const T> are
76// different types, which allow and don't allow mutation of the array elements,
77// respectively. The implicit conversions work just like you'd hope, so that
78// e.g. vector<int> will convert to either ArrayView<int> or ArrayView<const
79// int>, but const vector<int> will convert only to ArrayView<const int>.
80// (ArrayView itself can be the source type in such conversions, so
81// ArrayView<int> will convert to ArrayView<const int>.)
82//
83// Note: ArrayView is tiny (just a pointer and a count if variable-sized, just
84// a pointer if fix-sized) and trivially copyable, so it's probably cheaper to
85// pass it by value than by const reference.
86
Mirko Bonadei6b891302021-08-16 12:51:4087namespace array_view_internal {
kwiberg529662a2017-09-04 12:43:1788
89// Magic constant for indicating that the size of an ArrayView is variable
90// instead of fixed.
91enum : std::ptrdiff_t { kArrayViewVarSize = -4711 };
92
93// Base class for ArrayViews of fixed nonzero size.
94template <typename T, std::ptrdiff_t Size>
95class ArrayViewBase {
96 static_assert(Size > 0, "ArrayView size must be variable or non-negative");
97
98 public:
99 ArrayViewBase(T* data, size_t size) : data_(data) {}
100
101 static constexpr size_t size() { return Size; }
102 static constexpr bool empty() { return false; }
103 T* data() const { return data_; }
104
105 protected:
106 static constexpr bool fixed_size() { return true; }
107
108 private:
109 T* data_;
110};
111
112// Specialized base class for ArrayViews of fixed zero size.
113template <typename T>
114class ArrayViewBase<T, 0> {
115 public:
116 explicit ArrayViewBase(T* data, size_t size) {}
117
118 static constexpr size_t size() { return 0; }
119 static constexpr bool empty() { return true; }
120 T* data() const { return nullptr; }
121
122 protected:
123 static constexpr bool fixed_size() { return true; }
124};
125
126// Specialized base class for ArrayViews of variable size.
127template <typename T>
Mirko Bonadei6b891302021-08-16 12:51:40128class ArrayViewBase<T, array_view_internal::kArrayViewVarSize> {
kwiberg529662a2017-09-04 12:43:17129 public:
130 ArrayViewBase(T* data, size_t size)
131 : data_(size == 0 ? nullptr : data), size_(size) {}
132
133 size_t size() const { return size_; }
134 bool empty() const { return size_ == 0; }
135 T* data() const { return data_; }
136
137 protected:
138 static constexpr bool fixed_size() { return false; }
139
140 private:
141 T* data_;
142 size_t size_;
143};
144
Mirko Bonadei6b891302021-08-16 12:51:40145} // namespace array_view_internal
kwiberg529662a2017-09-04 12:43:17146
Mirko Bonadei6b891302021-08-16 12:51:40147template <typename T,
148 std::ptrdiff_t Size = array_view_internal::kArrayViewVarSize>
149class ArrayView final : public array_view_internal::ArrayViewBase<T, Size> {
kwiberg529662a2017-09-04 12:43:17150 public:
151 using value_type = T;
Daniel Cheng0e1d3c52023-04-03 22:51:18152 using reference = value_type&;
153 using const_reference = const value_type&;
154 using pointer = value_type*;
155 using const_pointer = const value_type*;
kwiberg529662a2017-09-04 12:43:17156 using const_iterator = const T*;
157
158 // Construct an ArrayView from a pointer and a length.
159 template <typename U>
160 ArrayView(U* data, size_t size)
Mirko Bonadei6b891302021-08-16 12:51:40161 : array_view_internal::ArrayViewBase<T, Size>::ArrayViewBase(data, size) {
kwiberg529662a2017-09-04 12:43:17162 RTC_DCHECK_EQ(size == 0 ? nullptr : data, this->data());
163 RTC_DCHECK_EQ(size, this->size());
164 RTC_DCHECK_EQ(!this->data(),
165 this->size() == 0); // data is null iff size == 0.
166 }
167
168 // Construct an empty ArrayView. Note that fixed-size ArrayViews of size > 0
169 // cannot be empty.
170 ArrayView() : ArrayView(nullptr, 0) {}
171 ArrayView(std::nullptr_t) // NOLINT
172 : ArrayView() {}
173 ArrayView(std::nullptr_t, size_t size)
174 : ArrayView(static_cast<T*>(nullptr), size) {
Mirko Bonadei6b891302021-08-16 12:51:40175 static_assert(Size == 0 || Size == array_view_internal::kArrayViewVarSize,
176 "");
kwiberg529662a2017-09-04 12:43:17177 RTC_DCHECK_EQ(0, size);
178 }
179
Alessio Bazzica858c4d72018-05-14 14:33:58180 // Construct an ArrayView from a C-style array.
kwiberg529662a2017-09-04 12:43:17181 template <typename U, size_t N>
182 ArrayView(U (&array)[N]) // NOLINT
183 : ArrayView(array, N) {
Mirko Bonadei6b891302021-08-16 12:51:40184 static_assert(Size == N || Size == array_view_internal::kArrayViewVarSize,
kwiberg529662a2017-09-04 12:43:17185 "Array size must match ArrayView size");
186 }
187
Alessio Bazzica28a325b2018-05-15 12:57:51188 // (Only if size is fixed.) Construct a fixed size ArrayView<T, N> from a
189 // non-const std::array instance. For an ArrayView with variable size, the
190 // used ctor is ArrayView(U& u) instead.
Alessio Bazzica858c4d72018-05-14 14:33:58191 template <typename U,
192 size_t N,
193 typename std::enable_if<
194 Size == static_cast<std::ptrdiff_t>(N)>::type* = nullptr>
195 ArrayView(std::array<U, N>& u) // NOLINT
196 : ArrayView(u.data(), u.size()) {}
197
Alessio Bazzica28a325b2018-05-15 12:57:51198 // (Only if size is fixed.) Construct a fixed size ArrayView<T, N> where T is
199 // const from a const(expr) std::array instance. For an ArrayView with
200 // variable size, the used ctor is ArrayView(U& u) instead.
201 template <typename U,
202 size_t N,
203 typename std::enable_if<
204 Size == static_cast<std::ptrdiff_t>(N)>::type* = nullptr>
205 ArrayView(const std::array<U, N>& u) // NOLINT
206 : ArrayView(u.data(), u.size()) {}
207
kwiberg529662a2017-09-04 12:43:17208 // (Only if size is fixed.) Construct an ArrayView from any type U that has a
209 // static constexpr size() method whose return value is equal to Size, and a
210 // data() method whose return value converts implicitly to T*. In particular,
211 // this means we allow conversion from ArrayView<T, N> to ArrayView<const T,
212 // N>, but not the other way around. We also don't allow conversion from
213 // ArrayView<T> to ArrayView<T, N>, or from ArrayView<T, M> to ArrayView<T,
214 // N> when M != N.
215 template <
216 typename U,
Mirko Bonadei6b891302021-08-16 12:51:40217 typename std::enable_if<Size != array_view_internal::kArrayViewVarSize &&
kwiberg529662a2017-09-04 12:43:17218 HasDataAndSize<U, T>::value>::type* = nullptr>
219 ArrayView(U& u) // NOLINT
220 : ArrayView(u.data(), u.size()) {
221 static_assert(U::size() == Size, "Sizes must match exactly");
222 }
Karl Wibergff61f3a2020-02-28 09:01:18223 template <
224 typename U,
Mirko Bonadei6b891302021-08-16 12:51:40225 typename std::enable_if<Size != array_view_internal::kArrayViewVarSize &&
Karl Wibergff61f3a2020-02-28 09:01:18226 HasDataAndSize<U, T>::value>::type* = nullptr>
227 ArrayView(const U& u) // NOLINT(runtime/explicit)
228 : ArrayView(u.data(), u.size()) {
229 static_assert(U::size() == Size, "Sizes must match exactly");
230 }
kwiberg529662a2017-09-04 12:43:17231
232 // (Only if size is variable.) Construct an ArrayView from any type U that
233 // has a size() method whose return value converts implicitly to size_t, and
234 // a data() method whose return value converts implicitly to T*. In
235 // particular, this means we allow conversion from ArrayView<T> to
236 // ArrayView<const T>, but not the other way around. Other allowed
237 // conversions include
238 // ArrayView<T, N> to ArrayView<T> or ArrayView<const T>,
239 // std::vector<T> to ArrayView<T> or ArrayView<const T>,
240 // const std::vector<T> to ArrayView<const T>,
241 // rtc::Buffer to ArrayView<uint8_t> or ArrayView<const uint8_t>, and
242 // const rtc::Buffer to ArrayView<const uint8_t>.
243 template <
244 typename U,
Mirko Bonadei6b891302021-08-16 12:51:40245 typename std::enable_if<Size == array_view_internal::kArrayViewVarSize &&
kwiberg529662a2017-09-04 12:43:17246 HasDataAndSize<U, T>::value>::type* = nullptr>
247 ArrayView(U& u) // NOLINT
248 : ArrayView(u.data(), u.size()) {}
Karl Wiberg30abc362019-02-04 12:07:18249 template <
250 typename U,
Mirko Bonadei6b891302021-08-16 12:51:40251 typename std::enable_if<Size == array_view_internal::kArrayViewVarSize &&
Karl Wiberg30abc362019-02-04 12:07:18252 HasDataAndSize<U, T>::value>::type* = nullptr>
253 ArrayView(const U& u) // NOLINT(runtime/explicit)
254 : ArrayView(u.data(), u.size()) {}
kwiberg529662a2017-09-04 12:43:17255
256 // Indexing and iteration. These allow mutation even if the ArrayView is
257 // const, because the ArrayView doesn't own the array. (To prevent mutation,
258 // use a const element type.)
259 T& operator[](size_t idx) const {
260 RTC_DCHECK_LT(idx, this->size());
261 RTC_DCHECK(this->data());
262 return this->data()[idx];
263 }
264 T* begin() const { return this->data(); }
265 T* end() const { return this->data() + this->size(); }
266 const T* cbegin() const { return this->data(); }
267 const T* cend() const { return this->data() + this->size(); }
Alessio Bazzicae2c54852020-10-20 15:24:55268 std::reverse_iterator<T*> rbegin() const {
269 return std::make_reverse_iterator(end());
270 }
271 std::reverse_iterator<T*> rend() const {
272 return std::make_reverse_iterator(begin());
273 }
274 std::reverse_iterator<const T*> crbegin() const {
275 return std::make_reverse_iterator(cend());
276 }
277 std::reverse_iterator<const T*> crend() const {
278 return std::make_reverse_iterator(cbegin());
279 }
kwiberg529662a2017-09-04 12:43:17280
281 ArrayView<T> subview(size_t offset, size_t size) const {
282 return offset < this->size()
283 ? ArrayView<T>(this->data() + offset,
284 std::min(size, this->size() - offset))
285 : ArrayView<T>();
286 }
287 ArrayView<T> subview(size_t offset) const {
288 return subview(offset, this->size());
289 }
290};
291
292// Comparing two ArrayViews compares their (pointer,size) pairs; it does *not*
293// dereference the pointers.
294template <typename T, std::ptrdiff_t Size1, std::ptrdiff_t Size2>
295bool operator==(const ArrayView<T, Size1>& a, const ArrayView<T, Size2>& b) {
296 return a.data() == b.data() && a.size() == b.size();
297}
298template <typename T, std::ptrdiff_t Size1, std::ptrdiff_t Size2>
299bool operator!=(const ArrayView<T, Size1>& a, const ArrayView<T, Size2>& b) {
300 return !(a == b);
301}
302
303// Variable-size ArrayViews are the size of two pointers; fixed-size ArrayViews
304// are the size of one pointer. (And as a special case, fixed-size ArrayViews
305// of size 0 require no storage.)
306static_assert(sizeof(ArrayView<int>) == 2 * sizeof(int*), "");
307static_assert(sizeof(ArrayView<int, 17>) == sizeof(int*), "");
308static_assert(std::is_empty<ArrayView<int, 0>>::value, "");
309
310template <typename T>
311inline ArrayView<T> MakeArrayView(T* data, size_t size) {
312 return ArrayView<T>(data, size);
313}
314
Amit Hilbuche155dd02019-03-22 17:16:07315// Only for primitive types that have the same size and aligment.
316// Allow reinterpret cast of the array view to another primitive type of the
317// same size.
318// Template arguments order is (U, T, Size) to allow deduction of the template
319// arguments in client calls: reinterpret_array_view<target_type>(array_view).
320template <typename U, typename T, std::ptrdiff_t Size>
321inline ArrayView<U, Size> reinterpret_array_view(ArrayView<T, Size> view) {
322 static_assert(sizeof(U) == sizeof(T) && alignof(U) == alignof(T),
323 "ArrayView reinterpret_cast is only supported for casting "
324 "between views that represent the same chunk of memory.");
325 static_assert(
326 std::is_fundamental<T>::value && std::is_fundamental<U>::value,
327 "ArrayView reinterpret_cast is only supported for casting between "
328 "fundamental types.");
329 return ArrayView<U, Size>(reinterpret_cast<U*>(view.data()), view.size());
330}
331
kwiberg529662a2017-09-04 12:43:17332} // namespace rtc
333
Mirko Bonadei92ea95e2017-09-15 04:47:31334#endif // API_ARRAY_VIEW_H_