1 /* 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 11 #ifndef WEBRTC_BASE_ARRAY_VIEW_H_ 12 #define WEBRTC_BASE_ARRAY_VIEW_H_ 13 14 #include "webrtc/base/checks.h" 15 16 namespace rtc { 17 18 // Many functions read from or write to arrays. The obvious way to do this is 19 // to use two arguments, a pointer to the first element and an element count: 20 // 21 // bool Contains17(const int* arr, size_t size) { 22 // for (size_t i = 0; i < size; ++i) { 23 // if (arr[i] == 17) 24 // return true; 25 // } 26 // return false; 27 // } 28 // 29 // This is flexible, since it doesn't matter how the array is stored (C array, 30 // std::vector, rtc::Buffer, ...), but it's error-prone because the caller has 31 // to correctly specify the array length: 32 // 33 // Contains17(arr, arraysize(arr)); // C array 34 // Contains17(&arr[0], arr.size()); // std::vector 35 // Contains17(arr, size); // pointer + size 36 // ... 37 // 38 // It's also kind of messy to have two separate arguments for what is 39 // conceptually a single thing. 40 // 41 // Enter rtc::ArrayView<T>. It contains a T pointer (to an array it doesn't 42 // own) and a count, and supports the basic things you'd expect, such as 43 // indexing and iteration. It allows us to write our function like this: 44 // 45 // bool Contains17(rtc::ArrayView<const int> arr) { 46 // for (auto e : arr) { 47 // if (e == 17) 48 // return true; 49 // } 50 // return false; 51 // } 52 // 53 // And even better, because a bunch of things will implicitly convert to 54 // ArrayView, we can call it like this: 55 // 56 // Contains17(arr); // C array 57 // Contains17(arr); // std::vector 58 // Contains17(rtc::ArrayView<int>(arr, size)); // pointer + size 59 // ... 60 // 61 // One important point is that ArrayView<T> and ArrayView<const T> are 62 // different types, which allow and don't allow mutation of the array elements, 63 // respectively. The implicit conversions work just like you'd hope, so that 64 // e.g. vector<int> will convert to either ArrayView<int> or ArrayView<const 65 // int>, but const vector<int> will convert only to ArrayView<const int>. 66 // (ArrayView itself can be the source type in such conversions, so 67 // ArrayView<int> will convert to ArrayView<const int>.) 68 // 69 // Note: ArrayView is tiny (just a pointer and a count) and trivially copyable, 70 // so it's probably cheaper to pass it by value than by const reference. 71 template <typename T> 72 class ArrayView final { 73 public: 74 // Construct an empty ArrayView. ArrayView()75 ArrayView() : ArrayView(static_cast<T*>(nullptr), 0) {} 76 77 // Construct an ArrayView for a (pointer,size) pair. 78 template <typename U> ArrayView(U * data,size_t size)79 ArrayView(U* data, size_t size) 80 : data_(size == 0 ? nullptr : data), size_(size) { 81 CheckInvariant(); 82 } 83 84 // Construct an ArrayView for an array. 85 template <typename U, size_t N> ArrayView(U (& array)[N])86 ArrayView(U (&array)[N]) : ArrayView(&array[0], N) {} 87 88 // Construct an ArrayView for any type U that has a size() method whose 89 // return value converts implicitly to size_t, and a data() method whose 90 // return value converts implicitly to T*. In particular, this means we allow 91 // conversion from ArrayView<T> to ArrayView<const T>, but not the other way 92 // around. Other allowed conversions include std::vector<T> to ArrayView<T> 93 // or ArrayView<const T>, const std::vector<T> to ArrayView<const T>, and 94 // rtc::Buffer to ArrayView<uint8_t> (with the same const behavior as 95 // std::vector). 96 template <typename U> ArrayView(U & u)97 ArrayView(U& u) : ArrayView(u.data(), u.size()) {} 98 99 // Indexing, size, and iteration. These allow mutation even if the ArrayView 100 // is const, because the ArrayView doesn't own the array. (To prevent 101 // mutation, use ArrayView<const T>.) size()102 size_t size() const { return size_; } empty()103 bool empty() const { return size_ == 0; } data()104 T* data() const { return data_; } 105 T& operator[](size_t idx) const { 106 RTC_DCHECK_LT(idx, size_); 107 RTC_DCHECK(data_); // Follows from size_ > idx and the class invariant. 108 return data_[idx]; 109 } begin()110 T* begin() const { return data_; } end()111 T* end() const { return data_ + size_; } cbegin()112 const T* cbegin() const { return data_; } cend()113 const T* cend() const { return data_ + size_; } 114 115 // Comparing two ArrayViews compares their (pointer,size) pairs; it does 116 // *not* dereference the pointers. 117 friend bool operator==(const ArrayView& a, const ArrayView& b) { 118 return a.data_ == b.data_ && a.size_ == b.size_; 119 } 120 friend bool operator!=(const ArrayView& a, const ArrayView& b) { 121 return !(a == b); 122 } 123 124 private: 125 // Invariant: !data_ iff size_ == 0. CheckInvariant()126 void CheckInvariant() const { RTC_DCHECK_EQ(!data_, size_ == 0); } 127 T* data_; 128 size_t size_; 129 }; 130 131 } // namespace rtc 132 133 #endif // WEBRTC_BASE_ARRAY_VIEW_H_ 134