From 810d4c6bc053c37f6e5c95e99754791d131b5ca9 Mon Sep 17 00:00:00 2001
From: Anthony Calandra <anthony@anthony-calandra.com>
Date: Sat, 22 Feb 2020 15:59:58 -0500
Subject: [PATCH] Include std::span.

---
 CPP20.md  | 38 ++++++++++++++++++++++++++++++++++++++
 README.md | 38 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 76 insertions(+)

diff --git a/CPP20.md b/CPP20.md
index 032ae80..d9bcd50 100644
--- a/CPP20.md
+++ b/CPP20.md
@@ -20,6 +20,7 @@ C++20 includes the following new language features:
 C++20 includes the following new library features:
 - [concepts library](#concepts-library)
 - [synchronized buffered outputstream](#synchronized-buffered-outputstream)
+- [std::span](#stdspan)
 
 ## C++20 Language Features
 
@@ -371,6 +372,43 @@ Buffers output operations for the wrapped output stream ensuring synchronization
 std::osyncstream{std::cout} << "The value of x is:" << x << std::endl;
 ```
 
+### std::span
+A span is a view (i.e. non-owning) of a container providing bounds-checked access to a contiguous group of elements. Since views do not own their elements they are cheap to construct and copy -- a simplified way to think about views is they are holding references to their data. Spans can be dynamically-sized or fixed-sized.
+```c++
+void f(std::span<int> ints) {
+    std::for_each(ints.begin(), ints.end(), [](auto i) {
+        // ...
+    });
+}
+
+std::vector<int> v = {1, 2, 3};
+f(v);
+std::array<int, 3> a = {1, 2, 3};
+f(a);
+// etc.
+```
+Example: as opposed to maintaining a pointer and length field, a span wraps both of those up in a single container.
+```c++
+constexpr size_t LENGTH_ELEMENTS = 3;
+int* arr = new int[LENGTH_ELEMENTS]; // arr = {0, 0, 0}
+
+// Fixed-sized span which provides a view of `arr`.
+std::span<int, LENGTH_ELEMENTS> span = arr;
+span[1] = 1; // arr = {0, 1, 0}
+
+// Dynamic-sized span which provides a view of `arr`.
+std::span<int> d_span = arr;
+span[0] = 1; // arr = {1, 1, 0}
+```
+```c++
+constexpr size_t LENGTH_ELEMENTS = 3;
+int* arr = new int[LENGTH_ELEMENTS];
+
+std::span<int, LENGTH_ELEMENTS> span = arr; // OK
+std::span<double, LENGTH_ELEMENTS> span2 = arr; // ERROR
+std::span<int, 1> span3 = arr; // ERROR
+```
+
 ## Acknowledgements
 * [cppreference](http://en.cppreference.com/w/cpp) - especially useful for finding examples and documentation of new library features.
 * [C++ Rvalue References Explained](http://thbecker.net/articles/rvalue_references/section_01.html) - a great introduction I used to understand rvalue references, perfect forwarding, and move semantics.
diff --git a/README.md b/README.md
index 2134639..cfae902 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,7 @@ C++20 includes the following new language features:
 C++20 includes the following new library features:
 - [concepts library](#concepts-library)
 - [synchronized buffered outputstream](#synchronized-buffered-outputstream)
+- [std::span](#stdspan)
 
 C++17 includes the following new language features:
 - [template argument deduction for class templates](#template-argument-deduction-for-class-templates)
@@ -463,6 +464,43 @@ Buffers output operations for the wrapped output stream ensuring synchronization
 std::osyncstream{std::cout} << "The value of x is:" << x << std::endl;
 ```
 
+### std::span
+A span is a view (i.e. non-owning) of a container providing bounds-checked access to a contiguous group of elements. Since views do not own their elements they are cheap to construct and copy -- a simplified way to think about views is they are holding references to their data. Spans can be dynamically-sized or fixed-sized.
+```c++
+void f(std::span<int> ints) {
+    std::for_each(ints.begin(), ints.end(), [](auto i) {
+        // ...
+    });
+}
+
+std::vector<int> v = {1, 2, 3};
+f(v);
+std::array<int, 3> a = {1, 2, 3};
+f(a);
+// etc.
+```
+Example: as opposed to maintaining a pointer and length field, a span wraps both of those up in a single container.
+```c++
+constexpr size_t LENGTH_ELEMENTS = 3;
+int* arr = new int[LENGTH_ELEMENTS]; // arr = {0, 0, 0}
+
+// Fixed-sized span which provides a view of `arr`.
+std::span<int, LENGTH_ELEMENTS> span = arr;
+span[1] = 1; // arr = {0, 1, 0}
+
+// Dynamic-sized span which provides a view of `arr`.
+std::span<int> d_span = arr;
+span[0] = 1; // arr = {1, 1, 0}
+```
+```c++
+constexpr size_t LENGTH_ELEMENTS = 3;
+int* arr = new int[LENGTH_ELEMENTS];
+
+std::span<int, LENGTH_ELEMENTS> span = arr; // OK
+std::span<double, LENGTH_ELEMENTS> span2 = arr; // ERROR
+std::span<int, 1> span3 = arr; // ERROR
+```
+
 ## C++17 Language Features
 
 ### Template argument deduction for class templates