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 16namespace 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. 71template <typename T> 72class ArrayView final { 73 public: 74 // Construct an empty ArrayView. 75 ArrayView() : ArrayView(static_cast<T*>(nullptr), 0) {} 76 77 // Construct an ArrayView for a (pointer,size) pair. 78 template <typename U> 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> 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> 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>.) 102 size_t size() const { return size_; } 103 bool empty() const { return size_ == 0; } 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 } 110 T* begin() const { return data_; } 111 T* end() const { return data_ + size_; } 112 const T* cbegin() const { return data_; } 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. 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