Document containers (esp. Vc::span)

Signed-off-by: Matthias Kretz <[email protected]>

Author: mattkretz

README.md

@@ -112,7 +112,7 @@ The documentation is generated via [doxygen](http://doxygen.org). You can build
 the documentation by running `doxygen` in the `doc` subdirectory.
 Alternatively, you can find nightly builds of the documentation at:
 
-* [master branch](https://web-docs.gsi.de/~mkretz/Vc-master/)
+* [1.3 branch](https://web-docs.gsi.de/~mkretz/Vc-1.3/)
 * [1.3.0 release](https://web-docs.gsi.de/~mkretz/Vc-1.3.0/)
 * [1.2.0 release](https://web-docs.gsi.de/~mkretz/Vc-1.2.0/)
 * [1.1.0 release](https://web-docs.gsi.de/~mkretz/Vc-1.1.0/)

common/interleavedmemory.h

@@ -171,7 +171,7 @@ struct InterleavedMemoryAccess : public InterleavedMemoryReadAccess<StructSize,
  * members inside the struct.
  *
  * \see operator[]
- * \ingroup Utilities
+ * \ingroup Containers
  * \headerfile interleavedmemory.h <Vc/Memory>
  */
 template<typename S, typename V> class InterleavedMemoryWrapper

common/memory.h

@@ -118,7 +118,7 @@ template<typename V, size_t Size> struct _MemorySizeCalculation
 };
 
 /**
- * \ingroup Utilities
+ * \ingroup Containers
  * \headerfile memory.h <Vc/Memory>
  *
  * A helper class for fixed-size two-dimensional arrays.
@@ -282,7 +282,7 @@ class Memory : public AlignedBase<V::MemoryAlignment>,
      *
      * \see Memory<V, 0u>
      *
-     * \ingroup Utilities
+     * \ingroup Containers
      * \headerfile memory.h <Vc/Memory>
      */
 template <typename V, size_t Size, bool InitPadding>
@@ -451,7 +451,7 @@ class Memory<V, Size, 0u, InitPadding> :
      *
      * \see Memory<V, Size>
      *
-     * \ingroup Utilities
+     * \ingroup Containers
      * \headerfile memory.h <Vc/Memory>
      */
     template<typename V> class Memory<V, 0u, 0u, true> : public MemoryBase<V, Memory<V, 0u, 0u, true>, 1, void>

common/span.h

@@ -609,6 +609,28 @@ span(const Container&)->span<const typename Container::value_type>;
 
 }  // namespace Common
 
+/**
+ * \ingroup Containers
+ * \headerfile span.h <Vc/span>
+ *
+ * An adapted `std::span` with additional subscript operators supporting gather and scatter operations.
+ *
+ * The [std::span](https://en.cppreference.com/w/cpp/container/span) documentation applies.
+ *
+ * Example:
+ * \code
+ * struct Point {
+ *   float x, y;
+ * };
+ * Point data[100];
+ * // initialize values in data
+ *
+ * Vc::span<Point, 100> view(data);
+ * float_v::IndexType indexes = ...;  // values between 0-99
+ * float_v x = view[indexes][&Point::x];
+ * float_v y = view[indexes][&Point::y];
+ * \endcode
+ */
 template <typename T, ptrdiff_t Extent>
 using span = Common::AdaptSubscriptOperator<Common::span<T, Extent>>;
 

doc/dox.h

@@ -55,6 +55,7 @@ This documentation is structured in three main areas:
    \li \ref Simdize
    \li \ref Math
    \li \ref Utilities
+   \li \ref Containers
 
 3. The *Indexes* section contains automatically generated indexes to the same API
    documentation.
@@ -444,7 +445,7 @@ If your project does not use CMake all you need to do is the following:
 \defgroup Simdize simdize<T>
 \defgroup Math Math
 \defgroup Utilities Utilities
-
+\defgroup Containers Containers
 
 \addtogroup Vectors
 
@@ -512,6 +513,27 @@ Additional classes, macros, and functions that help to work more easily with the
 types.
 
 
+\addtogroup Containers
+
+For some problems, standard (or third-party) containers can be used.
+Simply use a `value_type` of `Vc::Vector<T>`.
+However, this requires:
+\li You actually have control over the data structures and can design/modify them for easy
+    vectorization usage.
+\li The access patterns are non-random. Because random access to individual `value_type`
+    \em elements is going to be a pain (two subscripts, first into the container, then
+    into the `Vc::Vector`)
+
+Therefore, for some problems you need to work with containers over elements of
+non-`Vector` type (e.g. of type `double` or a `struct`).
+Vc provides some help:
+\li Vc::vector
+\li Vc::array
+\li Vc::span
+\li Vc::Common::Memory (discouraged)
+\li Vc::Common::InterleavedMemoryWrapper
+
+
 \addtogroup Math
 
 Functions that implement math functions. Take care that some of the implementations will return

include/Vc/array

@@ -46,6 +46,43 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 namespace Vc_VERSIONED_NAMESPACE
 {
+/**
+ * \ingroup Containers
+ * This is `std::array` with additional subscript operators supporting gather and scatter operations.
+ *
+ * The [std::array](https://en.cppreference.com/w/cpp/container/array) documentation applies.
+ *
+ * Gathers from structured data (AoS: arrays of struct) are possible via a special
+ * subscript operator.
+ * Example:
+ * \code
+ * Vc::array<float, 100> data;
+ * std::iota(data.begin(), data.end(), 0.f);  // fill with values 0, 1, 2, ...
+ * auto indexes = float_v::IndexType::IndexesFromZero();
+ * float_v gathered = data[indexes];  // gathered == [0, 1, 2, ...]
+ * \endcode
+ *
+ * This also works for gathers into arrays of structures:
+ * \code
+ * struct Point { float x, y, z; };
+ * Vc::array<Point, 100> points;
+ * // fill points ...
+ * auto indexes = float_v::IndexType::IndexesFromZero();
+ * float_v xs = data[indexes][&Point::x];  // [points[0].x, points[1].x, points[2].x, ...]
+ * float_v ys = data[indexes][&Point::y];  // [points[0].y, points[1].y, points[2].y, ...]
+ * float_v zs = data[indexes][&Point::z];  // [points[0].z, points[1].z, points[2].z, ...]
+ * \endcode
+ *
+ * Arrays may also be nested:
+ * \code:
+ * Vc::array<Vc::array<float, 3>, 100> points;
+ * // fill points ...
+ * auto indexes = float_v::IndexType::IndexesFromZero();
+ * float_v xs = data[indexes][0];  // [points[0][0], points[1][0], points[2][0], ...]
+ * float_v ys = data[indexes][1];  // [points[0][1], points[1][1], points[2][1], ...]
+ * float_v zs = data[indexes][2];  // [points[0][2], points[1][2], points[2][2], ...]
+ * \endcode
+ */
 template <class T, size_t Size> struct array {
     // types:
     typedef array self_;

include/Vc/vector

@@ -30,10 +30,14 @@
 namespace Vc_VERSIONED_NAMESPACE
 {
 /**
- * \ingroup Utilities
+ * \ingroup Containers
+ * \headerfile vector <Vc/vector>
+ *
  * An adapted `std::vector` container with an additional subscript operator which
  * implements gather and scatter operations.
  *
+ * The [std::vector](https://en.cppreference.com/w/cpp/container/vector) documentation applies.
+ *
  * Example:
  * \code
  * struct Point {