Introduce rtc::ArrayView<T>, which keeps track of an array that it doesn't own
The main intended use case is as a function argument, replacing the
harder-to-read and harder-to-use separate pointer and size arguments.
It's easier to read because it's just one argument instead of two, and
with clearly defined semantics; it's easier to use because it has
iterators, and will automatically figure out the size of arrays.
BUG=webrtc:5028
R=andrew@webrtc.org, solenberg@webrtc.org
Review URL: https://codereview.webrtc.org/1408403002 .
Cr-Commit-Position: refs/heads/master@{#10415}
diff --git a/webrtc/base/BUILD.gn b/webrtc/base/BUILD.gn
index 916a801..11a2664 100644
--- a/webrtc/base/BUILD.gn
+++ b/webrtc/base/BUILD.gn
@@ -94,6 +94,7 @@
public_configs = [ "..:common_inherited_config" ]
sources = [
+ "array_view.h",
"atomicops.h",
"bitbuffer.cc",
"bitbuffer.h",
diff --git a/webrtc/base/array_view.h b/webrtc/base/array_view.h
new file mode 100644
index 0000000..019bd8b
--- /dev/null
+++ b/webrtc/base/array_view.h
@@ -0,0 +1,84 @@
+/*
+ * 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_BASE_ARRAY_VIEW_H_
+#define WEBRTC_BASE_ARRAY_VIEW_H_
+
+#include <vector>
+
+#include "webrtc/base/checks.h"
+
+namespace rtc {
+
+// Keeps track of an array (a pointer and a size) that it doesn't own.
+// ArrayView objects are immutable except for assignment, and small enough to
+// be cheaply passed by value.
+//
+// Note that ArrayView<T> and ArrayView<const T> are distinct types; this is
+// how you would represent mutable and unmutable views of an array.
+template <typename T>
+class ArrayView final {
+ public:
+ // Construct an empty ArrayView.
+ ArrayView() : ArrayView(static_cast<T*>(nullptr), 0) {}
+
+ // Construct an ArrayView for a (pointer,size) pair.
+ template <typename U>
+ ArrayView(U* data, size_t size)
+ : data_(size == 0 ? nullptr : data), size_(size) {
+ CheckInvariant();
+ }
+
+ // Construct an ArrayView for an array.
+ template <typename U, size_t N>
+ ArrayView(U (&array)[N]) : ArrayView(&array[0], N) {}
+
+ // Construct an ArrayView for 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 std::vector<T> to ArrayView<T>
+ // or ArrayView<const T>, const std::vector<T> to ArrayView<const T>, and
+ // rtc::Buffer to ArrayView<uint8_t> (with the same const behavior as
+ // std::vector).
+ template <typename U>
+ ArrayView(U& u) : ArrayView(u.data(), u.size()) {}
+ // TODO(kwiberg): Remove the special case for std::vector (and the include of
+ // <vector>); it is handled by the general case in C++11, since std::vector
+ // has a data() method there.
+ template <typename U>
+ ArrayView(std::vector<U>& u)
+ : ArrayView(u.empty() ? nullptr : &u[0], u.size()) {}
+
+ // Indexing, size, and iteration. These allow mutation even if the ArrayView
+ // is const, because the ArrayView doesn't own the array. (To prevent
+ // mutation, use ArrayView<const T>.)
+ size_t size() const { return size_; }
+ T* data() const { return data_; }
+ T& operator[](size_t idx) const {
+ RTC_DCHECK_LT(idx, size_);
+ RTC_DCHECK(data_); // Follows from size_ > idx and the class invariant.
+ return data_[idx];
+ }
+ T* begin() const { return data_; }
+ T* end() const { return data_ + size_; }
+ const T* cbegin() const { return data_; }
+ const T* cend() const { return data_ + size_; }
+
+ private:
+ // Invariant: !data_ iff size_ == 0.
+ void CheckInvariant() const { RTC_DCHECK_EQ(!data_, size_ == 0); }
+ T* data_;
+ size_t size_;
+};
+
+} // namespace rtc
+
+#endif // WEBRTC_BASE_ARRAY_VIEW_H_
diff --git a/webrtc/base/array_view_unittest.cc b/webrtc/base/array_view_unittest.cc
new file mode 100644
index 0000000..0d1bff0
--- /dev/null
+++ b/webrtc/base/array_view_unittest.cc
@@ -0,0 +1,217 @@
+/*
+ * 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.
+ */
+
+#include <algorithm>
+#include <string>
+#include <vector>
+
+#include "webrtc/base/array_view.h"
+#include "webrtc/base/buffer.h"
+#include "webrtc/base/checks.h"
+#include "webrtc/base/gunit.h"
+
+namespace rtc {
+
+namespace {
+template <typename T>
+void Call(ArrayView<T>) {}
+} // namespace
+
+TEST(ArrayViewTest, TestConstructFromPtrAndArray) {
+ char arr[] = "Arrr!";
+ const char carr[] = "Carrr!";
+ Call<const char>(arr);
+ Call<const char>(carr);
+ Call<char>(arr);
+ // Call<char>(carr); // Compile error, because can't drop const.
+ // Call<int>(arr); // Compile error, because incompatible types.
+ ArrayView<int*> x;
+ EXPECT_EQ(0u, x.size());
+ EXPECT_EQ(nullptr, x.data());
+ ArrayView<char> y = arr;
+ EXPECT_EQ(6u, y.size());
+ EXPECT_EQ(arr, y.data());
+ ArrayView<const char> z(arr + 1, 3);
+ EXPECT_EQ(3u, z.size());
+ EXPECT_EQ(arr + 1, z.data());
+ ArrayView<const char> w(arr, 2);
+ EXPECT_EQ(2u, w.size());
+ EXPECT_EQ(arr, w.data());
+ ArrayView<char> q(arr, 0);
+ EXPECT_EQ(0u, q.size());
+ EXPECT_EQ(nullptr, q.data());
+#if RTC_DCHECK_IS_ON && GTEST_HAS_DEATH_TEST && !defined(WEBRTC_ANDROID)
+ // DCHECK error (nullptr with nonzero size).
+ EXPECT_DEATH(ArrayView<int>(static_cast<int*>(nullptr), 5), "");
+#endif
+ // These are compile errors, because incompatible types.
+ // ArrayView<int> m = arr;
+ // ArrayView<float> n(arr + 2, 2);
+}
+
+TEST(ArrayViewTest, TestCopyConstructor) {
+ char arr[] = "Arrr!";
+ ArrayView<char> x = arr;
+ EXPECT_EQ(6u, x.size());
+ EXPECT_EQ(arr, x.data());
+ ArrayView<char> y = x; // Copy non-const -> non-const.
+ EXPECT_EQ(6u, y.size());
+ EXPECT_EQ(arr, y.data());
+ ArrayView<const char> z = x; // Copy non-const -> const.
+ EXPECT_EQ(6u, z.size());
+ EXPECT_EQ(arr, z.data());
+ ArrayView<const char> w = z; // Copy const -> const.
+ EXPECT_EQ(6u, w.size());
+ EXPECT_EQ(arr, w.data());
+ // ArrayView<char> v = z; // Compile error, because can't drop const.
+}
+
+TEST(ArrayViewTest, TestCopyAssignment) {
+ char arr[] = "Arrr!";
+ ArrayView<char> x(arr);
+ EXPECT_EQ(6u, x.size());
+ EXPECT_EQ(arr, x.data());
+ ArrayView<char> y;
+ y = x; // Copy non-const -> non-const.
+ EXPECT_EQ(6u, y.size());
+ EXPECT_EQ(arr, y.data());
+ ArrayView<const char> z;
+ z = x; // Copy non-const -> const.
+ EXPECT_EQ(6u, z.size());
+ EXPECT_EQ(arr, z.data());
+ ArrayView<const char> w;
+ w = z; // Copy const -> const.
+ EXPECT_EQ(6u, w.size());
+ EXPECT_EQ(arr, w.data());
+ // ArrayView<char> v;
+ // v = z; // Compile error, because can't drop const.
+}
+
+TEST(ArrayViewTest, TestStdVector) {
+ std::vector<int> v;
+ v.push_back(3);
+ v.push_back(11);
+ Call<const int>(v);
+ Call<int>(v);
+ // Call<unsigned int>(v); // Compile error, because incompatible types.
+ ArrayView<int> x = v;
+ EXPECT_EQ(2u, x.size());
+ EXPECT_EQ(v.data(), x.data());
+ ArrayView<const int> y;
+ y = v;
+ EXPECT_EQ(2u, y.size());
+ EXPECT_EQ(v.data(), y.data());
+ // ArrayView<double> d = v; // Compile error, because incompatible types.
+ const std::vector<int> cv;
+ Call<const int>(cv);
+ // Call<int>(cv); // Compile error, because can't drop const.
+ ArrayView<const int> z = cv;
+ EXPECT_EQ(0u, z.size());
+ EXPECT_EQ(nullptr, z.data());
+ // ArrayView<int> w = cv; // Compile error, because can't drop const.
+}
+
+TEST(ArrayViewTest, TestRtcBuffer) {
+ rtc::Buffer b = "so buffer";
+ Call<const uint8_t>(b);
+ Call<uint8_t>(b);
+ // Call<int8_t>(b); // Compile error, because incompatible types.
+ ArrayView<uint8_t> x = b;
+ EXPECT_EQ(10u, x.size());
+ EXPECT_EQ(b.data(), x.data());
+ ArrayView<const uint8_t> y;
+ y = b;
+ EXPECT_EQ(10u, y.size());
+ EXPECT_EQ(b.data(), y.data());
+ // ArrayView<char> d = b; // Compile error, because incompatible types.
+ const rtc::Buffer cb = "very const";
+ Call<const uint8_t>(cb);
+ // Call<uint8_t>(cb); // Compile error, because can't drop const.
+ ArrayView<const uint8_t> z = cb;
+ EXPECT_EQ(11u, z.size());
+ EXPECT_EQ(cb.data(), z.data());
+ // ArrayView<uint8_t> w = cb; // Compile error, because can't drop const.
+}
+
+TEST(ArrayViewTest, TestSwap) {
+ const char arr[] = "Arrr!";
+ const char aye[] = "Aye, Cap'n!";
+ ArrayView<const char> x(arr);
+ EXPECT_EQ(6u, x.size());
+ EXPECT_EQ(arr, x.data());
+ ArrayView<const char> y(aye);
+ EXPECT_EQ(12u, y.size());
+ EXPECT_EQ(aye, y.data());
+ using std::swap;
+ swap(x, y);
+ EXPECT_EQ(12u, x.size());
+ EXPECT_EQ(aye, x.data());
+ EXPECT_EQ(6u, y.size());
+ EXPECT_EQ(arr, y.data());
+ // ArrayView<char> z;
+ // swap(x, z); // Compile error, because can't drop const.
+}
+
+TEST(ArrayViewTest, TestIndexing) {
+ char arr[] = "abcdefg";
+ ArrayView<char> x(arr);
+ const ArrayView<char> y(arr);
+ ArrayView<const char> z(arr);
+ EXPECT_EQ(8u, x.size());
+ EXPECT_EQ(8u, y.size());
+ EXPECT_EQ(8u, z.size());
+ EXPECT_EQ('b', x[1]);
+ EXPECT_EQ('c', y[2]);
+ EXPECT_EQ('d', z[3]);
+ x[3] = 'X';
+ y[2] = 'Y';
+ // z[1] = 'Z'; // Compile error, because z's element type is const char.
+ EXPECT_EQ('b', x[1]);
+ EXPECT_EQ('Y', y[2]);
+ EXPECT_EQ('X', z[3]);
+#if RTC_DCHECK_IS_ON && GTEST_HAS_DEATH_TEST && !defined(WEBRTC_ANDROID)
+ EXPECT_DEATH(z[8], ""); // DCHECK error (index out of bounds).
+#endif
+}
+
+TEST(ArrayViewTest, TestIterationEmpty) {
+ ArrayView<std::vector<std::vector<std::vector<std::string>>>> av;
+ EXPECT_FALSE(av.begin());
+ EXPECT_FALSE(av.cbegin());
+ EXPECT_FALSE(av.end());
+ EXPECT_FALSE(av.cend());
+ for (auto& e : av) {
+ EXPECT_TRUE(false);
+ EXPECT_EQ(42u, e.size()); // Dummy use of e to prevent unused var warning.
+ }
+}
+
+TEST(ArrayViewTest, TestIteration) {
+ char arr[] = "Arrr!";
+ ArrayView<char> av(arr);
+ EXPECT_EQ('A', *av.begin());
+ EXPECT_EQ('A', *av.cbegin());
+ EXPECT_EQ('\0', *(av.end() - 1));
+ EXPECT_EQ('\0', *(av.cend() - 1));
+ char i = 0;
+ for (auto& e : av) {
+ EXPECT_EQ(arr + i, &e);
+ e = 's' + i;
+ ++i;
+ }
+ i = 0;
+ for (auto& e : ArrayView<const char>(av)) {
+ EXPECT_EQ(arr + i, &e);
+ // e = 'q' + i; // Compile error, because e is a const char&.
+ ++i;
+ }
+}
+
+} // namespace rtc
diff --git a/webrtc/base/base.gyp b/webrtc/base/base.gyp
index 0db0438..4b6ad85 100644
--- a/webrtc/base/base.gyp
+++ b/webrtc/base/base.gyp
@@ -29,6 +29,7 @@
'target_name': 'rtc_base_approved',
'type': 'static_library',
'sources': [
+ 'array_view.h',
'atomicops.h',
'basictypes.h',
'bitbuffer.cc',
diff --git a/webrtc/base/base_tests.gyp b/webrtc/base/base_tests.gyp
index 2c84036..4c3dd3d 100644
--- a/webrtc/base/base_tests.gyp
+++ b/webrtc/base/base_tests.gyp
@@ -45,6 +45,7 @@
'type': 'none',
'direct_dependent_settings': {
'sources': [
+ 'array_view_unittest.cc',
'atomicops_unittest.cc',
'autodetectproxy_unittest.cc',
'bandwidthsmoother_unittest.cc',
diff --git a/webrtc/base/checks.h b/webrtc/base/checks.h
index 98e896a..681361a 100644
--- a/webrtc/base/checks.h
+++ b/webrtc/base/checks.h
@@ -164,6 +164,7 @@
// code in debug builds. It does reference the condition parameter in all cases,
// though, so callers won't risk getting warnings about unused variables.
#if (!defined(NDEBUG) || defined(DCHECK_ALWAYS_ON))
+#define RTC_DCHECK_IS_ON 1
#define RTC_DCHECK(condition) RTC_CHECK(condition)
#define RTC_DCHECK_EQ(v1, v2) RTC_CHECK_EQ(v1, v2)
#define RTC_DCHECK_NE(v1, v2) RTC_CHECK_NE(v1, v2)
@@ -172,6 +173,7 @@
#define RTC_DCHECK_GE(v1, v2) RTC_CHECK_GE(v1, v2)
#define RTC_DCHECK_GT(v1, v2) RTC_CHECK_GT(v1, v2)
#else
+#define RTC_DCHECK_IS_ON 0
#define RTC_DCHECK(condition) RTC_EAT_STREAM_PARAMETERS(condition)
#define RTC_DCHECK_EQ(v1, v2) RTC_EAT_STREAM_PARAMETERS((v1) == (v2))
#define RTC_DCHECK_NE(v1, v2) RTC_EAT_STREAM_PARAMETERS((v1) != (v2))
