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