diff options
Diffstat (limited to 'webrtc/api/array_view.h')
| -rw-r--r-- | webrtc/api/array_view.h | 315 |
1 files changed, 315 insertions, 0 deletions
diff --git a/webrtc/api/array_view.h b/webrtc/api/array_view.h new file mode 100644 index 0000000..a66369a --- /dev/null +++ b/webrtc/api/array_view.h @@ -0,0 +1,315 @@ +/* + * 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 API_ARRAY_VIEW_H_ +#define API_ARRAY_VIEW_H_ + +#include <algorithm> +#include <array> +#include <type_traits> + +#include "rtc_base/checks.h" +#include "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 a C-style 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 a fixed size ArrayView<T, N> from a + // non-const std::array instance. For an ArrayView with variable size, the + // used ctor is ArrayView(U& u) instead. + template <typename U, + size_t N, + typename std::enable_if< + Size == static_cast<std::ptrdiff_t>(N)>::type* = nullptr> + ArrayView(std::array<U, N>& u) // NOLINT + : ArrayView(u.data(), u.size()) {} + + // (Only if size is fixed.) Construct a fixed size ArrayView<T, N> where T is + // const from a const(expr) std::array instance. For an ArrayView with + // variable size, the used ctor is ArrayView(U& u) instead. + template <typename U, + size_t N, + typename std::enable_if< + Size == static_cast<std::ptrdiff_t>(N)>::type* = nullptr> + ArrayView(const std::array<U, N>& u) // NOLINT + : ArrayView(u.data(), u.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"); + } + template < + typename U, + typename std::enable_if<Size != impl::kArrayViewVarSize && + HasDataAndSize<U, T>::value>::type* = nullptr> + ArrayView(const U& u) // NOLINT(runtime/explicit) + : 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()) {} + template < + typename U, + typename std::enable_if<Size == impl::kArrayViewVarSize && + HasDataAndSize<U, T>::value>::type* = nullptr> + ArrayView(const U& u) // NOLINT(runtime/explicit) + : 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); +} + +// Only for primitive types that have the same size and aligment. +// Allow reinterpret cast of the array view to another primitive type of the +// same size. +// Template arguments order is (U, T, Size) to allow deduction of the template +// arguments in client calls: reinterpret_array_view<target_type>(array_view). +template <typename U, typename T, std::ptrdiff_t Size> +inline ArrayView<U, Size> reinterpret_array_view(ArrayView<T, Size> view) { + static_assert(sizeof(U) == sizeof(T) && alignof(U) == alignof(T), + "ArrayView reinterpret_cast is only supported for casting " + "between views that represent the same chunk of memory."); + static_assert( + std::is_fundamental<T>::value && std::is_fundamental<U>::value, + "ArrayView reinterpret_cast is only supported for casting between " + "fundamental types."); + return ArrayView<U, Size>(reinterpret_cast<U*>(view.data()), view.size()); +} + +} // namespace rtc + +#endif // API_ARRAY_VIEW_H_ |