From 702225c24917fb4406122d109aa81e44b76f3e63 Mon Sep 17 00:00:00 2001
From: Mark Olesen <Mark.Olesen@esi-group.com>
Date: Sat, 11 Feb 2023 13:28:51 +0100
Subject: [PATCH] ENH: add stdFoam::span container

- basic functionality similar to std::span (C++20).
  Holds pointer and size: for lightweight handling of address ranges.

- implements cdata_bytes() and data_bytes() methods for similarity
  with UList. For span, however, both container accesses are const
  but the data_bytes() method is only available when the
  underlying pointer is non-const.

  No specializations of std::as_bytes() or std::as_writeable_bytes()
  as free functions, since std::byte etc are not available anyhow.
---
 applications/test/span/Make/files          |   3 +
 applications/test/span/Make/options        |   2 +
 applications/test/span/Test-stdFoam-span.C | 156 +++++++++++++++++++
 src/OpenFOAM/include/stdFoam.H             | 173 ++++++++++++++++++++-
 4 files changed, 333 insertions(+), 1 deletion(-)
 create mode 100644 applications/test/span/Make/files
 create mode 100644 applications/test/span/Make/options
 create mode 100644 applications/test/span/Test-stdFoam-span.C

diff --git a/applications/test/span/Make/files b/applications/test/span/Make/files
new file mode 100644
index 0000000000..81d892eb39
--- /dev/null
+++ b/applications/test/span/Make/files
@@ -0,0 +1,3 @@
+Test-stdFoam-span.C
+
+EXE = $(FOAM_USER_APPBIN)/Test-stdFoam-span
diff --git a/applications/test/span/Make/options b/applications/test/span/Make/options
new file mode 100644
index 0000000000..18e6fe47af
--- /dev/null
+++ b/applications/test/span/Make/options
@@ -0,0 +1,2 @@
+/* EXE_INC = */
+/* EXE_LIBS = */
diff --git a/applications/test/span/Test-stdFoam-span.C b/applications/test/span/Test-stdFoam-span.C
new file mode 100644
index 0000000000..fc6048b7b8
--- /dev/null
+++ b/applications/test/span/Test-stdFoam-span.C
@@ -0,0 +1,156 @@
+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | www.openfoam.com
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+    Copyright (C) 2023 OpenCFD Ltd.
+-------------------------------------------------------------------------------
+License
+    This file is part of OpenFOAM.
+
+    OpenFOAM is free software: you can redistribute it and/or modify it
+    under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
+    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+    for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
+
+Application
+    Test-stdFoam-span
+
+Description
+    Basic functionality test for span
+
+\*---------------------------------------------------------------------------*/
+
+#include "argList.H"
+
+#include "IOstreams.H"
+#include "StringStream.H"
+#include "scalar.H"
+#include "vector.H"
+#include "labelRange.H"
+#include "scalarList.H"
+
+using namespace Foam;
+
+template<class Type>
+void printInfo(const UList<Type>& list)
+{
+    Info<< "list: " << flatOutput(list) << nl
+        << "data: " << Foam::name(list.cdata())
+        << " size: " << Foam::name(list.size()) << nl;
+}
+
+
+template<class Type>
+void printInfo(const stdFoam::span<Type> span)
+{
+    Info<< "span: " << Foam::name(span.data())
+        << ", " << span.size() << nl;
+}
+
+template<class Type>
+void printContent(const stdFoam::span<Type> span)
+{
+    Info<< "range:";
+    for (const auto& val : span)
+    {
+        Info<< " " << val;
+    }
+    Info<< nl;
+}
+
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+//  Main program:
+
+int main(int argc, char *argv[])
+{
+    argList::noParallel();
+    argList::noFunctionObjects();
+
+    #include "setRootCase.H"
+
+    {
+        const List<label> list1(identity(15));
+
+        printInfo(list1);
+
+        stdFoam::span<const label> span1;
+        printInfo(span1);
+
+        span1 = stdFoam::span<const label>(list1.cdata(), list1.size());
+        printInfo(span1);
+        printContent(span1);
+
+        auto subspan1 = span1.subspan(5);
+
+        printInfo(subspan1);
+        printContent(subspan1);
+
+        subspan1 = span1.subspan(5, 30);
+        printInfo(subspan1);
+        printContent(subspan1);
+
+        // non-const access: span1[6] = -100;
+        // non-const access: Info<< Foam::name(span1.data_bytes()) << endl;
+
+        Info<< Foam::name(span1.cdata_bytes()) << endl;
+    }
+
+    {
+        List<label> list1(identity(15));
+
+        printInfo(list1);
+
+        stdFoam::span<label> span1;
+        printInfo(span1);
+
+        span1 = stdFoam::span<label>(list1.data(), list1.size());
+        printInfo(span1);
+        printContent(span1);
+
+        auto subspan1 = span1.subspan(5);
+
+        printInfo(subspan1);
+        printContent(subspan1);
+
+        subspan1 = span1.subspan(5, 30);
+        printInfo(subspan1);
+        printContent(subspan1);
+
+        span1[6] = -100;
+        printInfo(span1);
+        printContent(span1);
+
+        Info<< Foam::name(span1.data_bytes()) << endl;
+
+
+        // With const span
+        const auto span2 = stdFoam::span<label>(list1.data(), list1.size());
+        printContent(span2);
+
+        // Span may be const, but its contents (pointers) needn't be
+        span2[1] = 100;
+        span2.front() = -1000;
+        span2.back() = 1000;
+        printInfo(list1);
+
+        printContent(span2.first(5));
+        printContent(span2.last(5));
+    }
+
+    Info<< "\nDone\n" << nl;
+    return 0;
+}
+
+// ************************************************************************* //
diff --git a/src/OpenFOAM/include/stdFoam.H b/src/OpenFOAM/include/stdFoam.H
index 877c5ef968..b6ebf2e822 100644
--- a/src/OpenFOAM/include/stdFoam.H
+++ b/src/OpenFOAM/include/stdFoam.H
@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2017-2022 OpenCFD Ltd.
+    Copyright (C) 2017-2023 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -36,6 +36,7 @@ Description
 #include <initializer_list>
 #include <memory>
 #include <utility>
+#include <type_traits>
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
@@ -397,6 +398,176 @@ constexpr inline const T& max(const T& a, const T& b)
     )
 
 
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+namespace stdFoam
+{
+
+/*---------------------------------------------------------------------------*\
+                        Class stdFoam::span Declaration
+\*---------------------------------------------------------------------------*/
+
+//- Rudimentary functionality similar to std::span for holding memory view
+template<class Type>
+class span
+{
+    // Private Data
+
+        //- The data pointer
+        Type* data_;
+
+        //- The size of the span
+        std::size_t size_;
+
+
+public:
+
+    // STL type definitions
+
+        using element_type = Type;
+        using value_type = std::remove_cv<Type>;
+        using size_type = std::size_t;
+        using pointer = Type*;
+        using const_pointer = const Type*;
+        using reference = Type&;
+        using const_reference = const Type&;
+        using difference_type = std::ptrdiff_t;
+        using iterator = Type*;
+
+
+    // Generated Methods
+
+        //- Copy construct
+        span(const span& other) noexcept = default;
+
+        //- Copy assignment
+        span& operator=(const span& other) noexcept = default;
+
+
+    // Constructors
+
+        //- Default construct
+        constexpr span() noexcept
+        :
+            data_(nullptr),
+            size_(0)
+        {}
+
+        //- Construct from pointer and size
+        constexpr span(pointer ptr, size_type count) noexcept
+        :
+            data_(ptr),
+            size_(count)
+        {}
+
+        //- Construct from begin/end pointers
+        constexpr span(pointer first, pointer last) noexcept
+        :
+            data_(first),
+            size_(last - first)
+        {}
+
+
+    //- Destructor
+    ~span() noexcept = default;
+
+
+    // Member Functions
+
+    // Iterators
+
+        //- Iterator to begin of span
+        constexpr iterator begin() const noexcept { return data_; }
+
+        //- Iterator to one-past end of span
+        constexpr iterator end() const noexcept { return (data_ + size_); }
+
+
+    // Element access
+
+        //- Access the first element. Undefined if span is empty
+        constexpr reference front() const { return *(data_); }
+
+        //- Access the last element. Undefined if span is empty
+        constexpr reference back() const { return *(data_ + size_ - 1); }
+
+        //- Access an element of the sequence
+        constexpr reference operator[](size_type idx) const
+        {
+           return *(data_ + idx);
+        }
+
+        //- Return a pointer to the beginning of the sequence
+        constexpr pointer data() const noexcept { return data_; }
+
+
+    // Observers
+
+        //- Number of elements in the sequence
+        constexpr size_type size() const noexcept { return size_; }
+
+        //- The size of the sequence in bytes
+        constexpr size_type size_bytes() const noexcept
+        {
+            return (size_*sizeof(Type));
+        }
+
+        //- True if the sequence is empty
+        constexpr bool empty() const noexcept { return !size_; }
+
+
+    // Subview
+
+        //- Obtains a span of the first count elements
+        span<Type> first(size_type count) const noexcept
+        {
+            return span<Type>(data_, count);
+        }
+
+        //- Obtains a span of the last count elements
+        span<Type> last(size_type count) const noexcept
+        {
+            return span<Type>(data_ + (size_ - count), count);
+        }
+
+        //- Obtains a sub-span starting at pos until end of the sequence
+        span<Type> subspan(size_type pos) const noexcept
+        {
+            return span<Type>(data_ + pos, size_ - pos);
+        }
+
+        //- Obtains a sub-span of length len starting at pos.
+        //  Graciously handles excess lengths.
+        span<Type> subspan(size_type pos, size_type len) const noexcept
+        {
+            return span<Type>(data_ + pos, std::min(size_ - pos, len));
+        }
+
+
+    // Additional members, similar to UList etc.
+    // The std::span has as_bytes() and as_writeable_bytes() as free functions
+
+        //- A readonly view as byte content
+        constexpr const char* cdata_bytes() const noexcept
+        {
+            return reinterpret_cast<const char*>(data_);
+        }
+
+        //- A writable view as byte content (if the pointer type is non-const).
+        //- Like data(), the const access itself is const.
+        template<class TypeT = Type>
+        typename std::enable_if<!std::is_const<TypeT>::value, char*>::type
+        data_bytes() const noexcept
+        {
+            return reinterpret_cast<char*>(data_);
+        }
+};
+
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+} // End namespace stdFoam
+
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
 #endif