[poly_span] doc

README.md

@@ -31,6 +31,7 @@ In the list below each library shows its minimum supported C++ standard and has
  [**make_ptr.hpp**](https://github.com/iboB/itlib/blob/master/include/itlib/make_ptr.hpp) [![Standard](https://img.shields.io/badge/C%2B%2B-11-blue.svg)](https://en.wikipedia.org/wiki/C%2B%2B#Standardization) | Small helper functions for creating `std::shared_ptr` and `std::unique_ptr` which make the code shorter and more readable.
  [**mem_streambuf.hpp**](https://github.com/iboB/itlib/tree/master/include/itlib/mem_streambuf.hpp) [![Standard](https://img.shields.io/badge/C%2B%2B-11-blue.svg)](https://en.wikipedia.org/wiki/C%2B%2B#Standardization) | Two helper classes: `mem_ostreambuf` and `mem_istreambuf` which allow you to work with `std::stream`-s with buffers of contiguous memory.
  [**pod_vector.hpp**](https://github.com/iboB/itlib/tree/master/include/itlib/pod_vector.hpp) [![Standard](https://img.shields.io/badge/C%2B%2B-11-blue.svg)](https://en.wikipedia.org/wiki/C%2B%2B#Standardization) | A container similar to `std::vector`, which contains PODs. This fact is used to improve performance by skipping constructor and destructor calls and using `memcpy` and `memmove` to copy data, and `malloc` and `free`, and, most importantly `realloc`, to manage memory.
+ [**poly_span.hpp**](https://github.com/iboB/itlib/tree/master/include/itlib/poly_span.hpp) [![Standard](https://img.shields.io/badge/C%2B%2B-11-blue.svg)](https://en.wikipedia.org/wiki/C%2B%2B#Standardization) | A class similar to C++20's `std::span` which offers a polymorphic view over a buffer of objects.
  [**qalgorithm.hpp**](https://github.com/iboB/itlib/tree/master/include/itlib/qalgorithm.hpp) [![Standard](https://img.shields.io/badge/C%2B%2B-11-blue.svg)](https://en.wikipedia.org/wiki/C%2B%2B#Standardization) | Wrappers of `<algorithm>` functions which work on entire containers for less typing in the most common use-cases.
  [**rstream.hpp**](https://github.com/iboB/itlib/tree/master/include/itlib/rstream.hpp) [![Standard](https://img.shields.io/badge/C%2B%2B-11-blue.svg)](https://en.wikipedia.org/wiki/C%2B%2B#Standardization) | Read stream. Simple `std::istream` wrappers which don't allow seeks, allowing you to be certain that reads are sequential, and thus allow a redirect, so you can represent several streams as one.
  [**sentry.hpp**](https://github.com/iboB/itlib/tree/master/include/itlib/sentry.hpp) [![Standard](https://img.shields.io/badge/C%2B%2B-11-blue.svg)](https://en.wikipedia.org/wiki/C%2B%2B#Standardization) [![Standard](https://img.shields.io/badge/C%2B%2B-17-red.svg)](https://en.wikipedia.org/wiki/C%2B%2B#Standardization) | A sentry class which executes a function object on destruction. Works with C++11, but it's slightly easier to use with C++17.

include/itlib/poly_span.hpp

@@ -29,13 +29,40 @@
 //
 //                  VERSION HISTORY
 //
-//  1.00 (2022-xx-xx) Initial release
+//  1.00 (2022-05-19) Initial release
 //
 //
 //                  DOCUMENTATION
 //
 // Simply include this file wherever you need.
 //
+// poly_span is similar to C++20's std::span, as it can be constructed from a
+// contiguous block of data, but whereas std::span offers an identity view of
+// the block, poly_span offers a polymorphic one. By providing an access
+// function which is called upon dereferencing elements, one can access
+// different aspects of the elements of the original array.
+//
+// As opposed to std::span, itlib::span and itlib::stride_span, poly_span's
+// template argument is not a "value_type". It is instead what is returned
+// by dereferencing elements.
+//
+//                  Example
+//
+//  struct person { std::string& first_name, std::string& last_name, int age };
+//  std::vector<person> ps;
+//  ...
+//  poly_span<string&> names(ps.data(), ps.size(), [](person& p) -> std::string& {
+//      if (p.age < 18) return p.first_name;
+//      return p.last_name;
+//  });
+//
+//  for (auto& name : names) cout << "Hello, " << name << ".\n";
+//
+// Thus we greet young people by first name, and the rest by last name.
+// Note the template argument of poly_span there. It's string&. This allows us
+// to change the names from the point of view of the span. You can use
+// `const string&` if you want to disable that.
+//
 //
 //                  Configuration
 //