Move array_view.h to webrtc/api/
We use ArrayView in our public API, so its header should be in
webrtc/api/.
BUG=none
Review-Url: https://codereview.webrtc.org/3007763002
Cr-Commit-Position: refs/heads/master@{#19658}
diff --git a/webrtc/api/array_view.h b/webrtc/api/array_view.h
new file mode 100644
index 0000000..c97d388
--- /dev/null
+++ b/webrtc/api/array_view.h
@@ -0,0 +1,263 @@
+/*
+ * Copyright 2015 The WebRTC Project Authors. All rights reserved.
+ *
+ * Use of this source code is governed by a BSD-style license
+ * that can be found in the LICENSE file in the root of the source
+ * tree. An additional intellectual property rights grant can be found
+ * in the file PATENTS. All contributing project authors may
+ * be found in the AUTHORS file in the root of the source tree.
+ */
+
+#ifndef WEBRTC_API_ARRAY_VIEW_H_
+#define WEBRTC_API_ARRAY_VIEW_H_
+
+#include <algorithm>
+#include <type_traits>
+
+#include "webrtc/rtc_base/checks.h"
+#include "webrtc/rtc_base/type_traits.h"
+
+namespace rtc {
+
+// tl;dr: rtc::ArrayView is the same thing as gsl::span from the Guideline
+// Support Library.
+//
+// Many functions read from or write to arrays. The obvious way to do this is
+// to use two arguments, a pointer to the first element and an element count:
+//
+// bool Contains17(const int* arr, size_t size) {
+// for (size_t i = 0; i < size; ++i) {
+// if (arr[i] == 17)
+// return true;
+// }
+// return false;
+// }
+//
+// This is flexible, since it doesn't matter how the array is stored (C array,
+// std::vector, rtc::Buffer, ...), but it's error-prone because the caller has
+// to correctly specify the array length:
+//
+// Contains17(arr, arraysize(arr)); // C array
+// Contains17(arr.data(), arr.size()); // std::vector
+// Contains17(arr, size); // pointer + size
+// ...
+//
+// It's also kind of messy to have two separate arguments for what is
+// conceptually a single thing.
+//
+// Enter rtc::ArrayView<T>. It contains a T pointer (to an array it doesn't
+// own) and a count, and supports the basic things you'd expect, such as
+// indexing and iteration. It allows us to write our function like this:
+//
+// bool Contains17(rtc::ArrayView<const int> arr) {
+// for (auto e : arr) {
+// if (e == 17)
+// return true;
+// }
+// return false;
+// }
+//
+// And even better, because a bunch of things will implicitly convert to
+// ArrayView, we can call it like this:
+//
+// Contains17(arr); // C array
+// Contains17(arr); // std::vector
+// Contains17(rtc::ArrayView<int>(arr, size)); // pointer + size
+// Contains17(nullptr); // nullptr -> empty ArrayView
+// ...
+//
+// ArrayView<T> stores both a pointer and a size, but you may also use
+// ArrayView<T, N>, which has a size that's fixed at compile time (which means
+// it only has to store the pointer).
+//
+// One important point is that ArrayView<T> and ArrayView<const T> are
+// different types, which allow and don't allow mutation of the array elements,
+// respectively. The implicit conversions work just like you'd hope, so that
+// e.g. vector<int> will convert to either ArrayView<int> or ArrayView<const
+// int>, but const vector<int> will convert only to ArrayView<const int>.
+// (ArrayView itself can be the source type in such conversions, so
+// ArrayView<int> will convert to ArrayView<const int>.)
+//
+// Note: ArrayView is tiny (just a pointer and a count if variable-sized, just
+// a pointer if fix-sized) and trivially copyable, so it's probably cheaper to
+// pass it by value than by const reference.
+
+namespace impl {
+
+// Magic constant for indicating that the size of an ArrayView is variable
+// instead of fixed.
+enum : std::ptrdiff_t { kArrayViewVarSize = -4711 };
+
+// Base class for ArrayViews of fixed nonzero size.
+template <typename T, std::ptrdiff_t Size>
+class ArrayViewBase {
+ static_assert(Size > 0, "ArrayView size must be variable or non-negative");
+
+ public:
+ ArrayViewBase(T* data, size_t size) : data_(data) {}
+
+ static constexpr size_t size() { return Size; }
+ static constexpr bool empty() { return false; }
+ T* data() const { return data_; }
+
+ protected:
+ static constexpr bool fixed_size() { return true; }
+
+ private:
+ T* data_;
+};
+
+// Specialized base class for ArrayViews of fixed zero size.
+template <typename T>
+class ArrayViewBase<T, 0> {
+ public:
+ explicit ArrayViewBase(T* data, size_t size) {}
+
+ static constexpr size_t size() { return 0; }
+ static constexpr bool empty() { return true; }
+ T* data() const { return nullptr; }
+
+ protected:
+ static constexpr bool fixed_size() { return true; }
+};
+
+// Specialized base class for ArrayViews of variable size.
+template <typename T>
+class ArrayViewBase<T, impl::kArrayViewVarSize> {
+ public:
+ ArrayViewBase(T* data, size_t size)
+ : data_(size == 0 ? nullptr : data), size_(size) {}
+
+ size_t size() const { return size_; }
+ bool empty() const { return size_ == 0; }
+ T* data() const { return data_; }
+
+ protected:
+ static constexpr bool fixed_size() { return false; }
+
+ private:
+ T* data_;
+ size_t size_;
+};
+
+} // namespace impl
+
+template <typename T, std::ptrdiff_t Size = impl::kArrayViewVarSize>
+class ArrayView final : public impl::ArrayViewBase<T, Size> {
+ public:
+ using value_type = T;
+ using const_iterator = const T*;
+
+ // Construct an ArrayView from a pointer and a length.
+ template <typename U>
+ ArrayView(U* data, size_t size)
+ : impl::ArrayViewBase<T, Size>::ArrayViewBase(data, size) {
+ RTC_DCHECK_EQ(size == 0 ? nullptr : data, this->data());
+ RTC_DCHECK_EQ(size, this->size());
+ RTC_DCHECK_EQ(!this->data(),
+ this->size() == 0); // data is null iff size == 0.
+ }
+
+ // Construct an empty ArrayView. Note that fixed-size ArrayViews of size > 0
+ // cannot be empty.
+ ArrayView() : ArrayView(nullptr, 0) {}
+ ArrayView(std::nullptr_t) // NOLINT
+ : ArrayView() {}
+ ArrayView(std::nullptr_t, size_t size)
+ : ArrayView(static_cast<T*>(nullptr), size) {
+ static_assert(Size == 0 || Size == impl::kArrayViewVarSize, "");
+ RTC_DCHECK_EQ(0, size);
+ }
+
+ // Construct an ArrayView from an array.
+ template <typename U, size_t N>
+ ArrayView(U (&array)[N]) // NOLINT
+ : ArrayView(array, N) {
+ static_assert(Size == N || Size == impl::kArrayViewVarSize,
+ "Array size must match ArrayView size");
+ }
+
+ // (Only if size is fixed.) Construct an ArrayView from any type U that has a
+ // static constexpr size() method whose return value is equal to Size, and a
+ // data() method whose return value converts implicitly to T*. In particular,
+ // this means we allow conversion from ArrayView<T, N> to ArrayView<const T,
+ // N>, but not the other way around. We also don't allow conversion from
+ // ArrayView<T> to ArrayView<T, N>, or from ArrayView<T, M> to ArrayView<T,
+ // N> when M != N.
+ template <
+ typename U,
+ typename std::enable_if<Size != impl::kArrayViewVarSize &&
+ HasDataAndSize<U, T>::value>::type* = nullptr>
+ ArrayView(U& u) // NOLINT
+ : ArrayView(u.data(), u.size()) {
+ static_assert(U::size() == Size, "Sizes must match exactly");
+ }
+
+ // (Only if size is variable.) Construct an ArrayView from any type U that
+ // has a size() method whose return value converts implicitly to size_t, and
+ // a data() method whose return value converts implicitly to T*. In
+ // particular, this means we allow conversion from ArrayView<T> to
+ // ArrayView<const T>, but not the other way around. Other allowed
+ // conversions include
+ // ArrayView<T, N> to ArrayView<T> or ArrayView<const T>,
+ // std::vector<T> to ArrayView<T> or ArrayView<const T>,
+ // const std::vector<T> to ArrayView<const T>,
+ // rtc::Buffer to ArrayView<uint8_t> or ArrayView<const uint8_t>, and
+ // const rtc::Buffer to ArrayView<const uint8_t>.
+ template <
+ typename U,
+ typename std::enable_if<Size == impl::kArrayViewVarSize &&
+ HasDataAndSize<U, T>::value>::type* = nullptr>
+ ArrayView(U& u) // NOLINT
+ : ArrayView(u.data(), u.size()) {}
+
+ // Indexing and iteration. These allow mutation even if the ArrayView is
+ // const, because the ArrayView doesn't own the array. (To prevent mutation,
+ // use a const element type.)
+ T& operator[](size_t idx) const {
+ RTC_DCHECK_LT(idx, this->size());
+ RTC_DCHECK(this->data());
+ return this->data()[idx];
+ }
+ T* begin() const { return this->data(); }
+ T* end() const { return this->data() + this->size(); }
+ const T* cbegin() const { return this->data(); }
+ const T* cend() const { return this->data() + this->size(); }
+
+ ArrayView<T> subview(size_t offset, size_t size) const {
+ return offset < this->size()
+ ? ArrayView<T>(this->data() + offset,
+ std::min(size, this->size() - offset))
+ : ArrayView<T>();
+ }
+ ArrayView<T> subview(size_t offset) const {
+ return subview(offset, this->size());
+ }
+};
+
+// Comparing two ArrayViews compares their (pointer,size) pairs; it does *not*
+// dereference the pointers.
+template <typename T, std::ptrdiff_t Size1, std::ptrdiff_t Size2>
+bool operator==(const ArrayView<T, Size1>& a, const ArrayView<T, Size2>& b) {
+ return a.data() == b.data() && a.size() == b.size();
+}
+template <typename T, std::ptrdiff_t Size1, std::ptrdiff_t Size2>
+bool operator!=(const ArrayView<T, Size1>& a, const ArrayView<T, Size2>& b) {
+ return !(a == b);
+}
+
+// Variable-size ArrayViews are the size of two pointers; fixed-size ArrayViews
+// are the size of one pointer. (And as a special case, fixed-size ArrayViews
+// of size 0 require no storage.)
+static_assert(sizeof(ArrayView<int>) == 2 * sizeof(int*), "");
+static_assert(sizeof(ArrayView<int, 17>) == sizeof(int*), "");
+static_assert(std::is_empty<ArrayView<int, 0>>::value, "");
+
+template <typename T>
+inline ArrayView<T> MakeArrayView(T* data, size_t size) {
+ return ArrayView<T>(data, size);
+}
+
+} // namespace rtc
+
+#endif // WEBRTC_API_ARRAY_VIEW_H_
