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