Add and document numeric vectors

Author: sethrj

CMakeLists.txt

@@ -169,6 +169,8 @@ swig_fortran_add_module(flc_random)
 target_link_libraries(flc_random flc)
 swig_fortran_add_module(flc_algorithm)
 target_link_libraries(flc_algorithm flc_random flc)
+swig_fortran_add_module(flc_vector)
+target_link_libraries(flc_vector flc)
 
 #---------------------------------------------------------------------------#
 # INSTALLATION

doc/interface.rst

@@ -24,12 +24,24 @@ flc_algorithm
 .. literalinclude:: ../src/flc_algorithm.i
    :linenos:
 
+flc_chrono
+=============
+
+.. literalinclude:: ../src/flc_chrono.i
+   :linenos:
+
 flc_random
 =============
 
 .. literalinclude:: ../src/flc_random.i
    :linenos:
 
+flc_vector
+=============
+
+.. literalinclude:: ../src/flc_vector.i
+   :linenos:
+
 .. ############################################################################
 .. end of doc/interface.rst
 .. ############################################################################

doc/modules.rst

@@ -13,10 +13,24 @@ The modules themselves are namespaced with a ``flc_`` prefix, so
 for example the ``std::sort`` algorithm, available in the ``<algorithm>``
 header, can be obtained via::
 
-   use :: flc_algorithm, only : sort
+   use flc_algorithm, only : sort
 
-All templated routines are instantiated with 32- and 64-bit signed integers,
-and double-precision floats.
+All templated routines are instantiated with 32- and 64-bit signed integers
+(``integer(4)`` and ``integer(8)``), and double-precision floats (``real(8)``).
+
+Some modules support error handling for checking input values. In all cases,
+the error status and a message can be accessed and cleared through the main
+``flc`` module::
+
+   use flc, only : ierr, get_serr
+
+   ! <snip>
+   if (ierr /= 0) then
+     write(1,*) "Error", ierr, ":", get_serr()
+     ! Reset the error flag to indicate that the error has been successfully
+     ! handled.
+     ierr = 0
+   fi
 
 .. toctree::
    modules/algorithm.rst
@@ -25,6 +39,7 @@ and double-precision floats.
    modules/random.rst
    modules/set.rst
    modules/string.rst
+   modules/vector.rst
 
 
 .. ############################################################################

doc/modules/vector.rst

@@ -0,0 +1,131 @@
+.. ############################################################################
+.. File  : doc/modules/vector.rst
+.. ############################################################################
+
+.. _modules_Vector:
+
+******
+Vector
+******
+
+Vectors are resizeable arrays of elements. All vectors support the following
+basic operations.
+
+Construction and destruction
+----------------------------
+
+Vectors are constructed using three interface functions:
+
+  - The function without arguments creates an empty vector;
+  - A single integer argument assigns that many elements with default values;
+    and
+  - An integer argument followed by an element with the vector's element type
+    will copy that value to all elements of the vector.
+
+(To do: copy construction)
+
+Here are three examples of initialization::
+
+   use flc_vector, only : Vector => VectorInt4
+   type(Vector) :: v
+
+   v = Vector()
+   ! v%size() == 0
+   v = Vector(10)
+   ! v%size() == 10
+   ! v%get(i) == 0
+   v = Vector(10, 123)
+   ! v%size() == 10
+   ! v%get(i) == 123
+
+Vectors are destroyed using the ``release`` type-bound subroutine::
+
+   call v%release()
+
+Modification
+------------
+
+Vectors can be resized dynamically using ``resize``, which acts like the
+constructors described above. An element can be added to
+the end of the vector (increasing the size by one) with ``push_back``. The
+``insert`` method can insert an element at a specific index, and ``erase``
+removes a specific vector index or range of indices. ``clear`` removes
+all elements. Finally, ``set`` sets the value of an element at a given index.
+
+.. important:: Unlike the C++ version of this class, **all vectors in flibcpp
+   use 1-offset indexing**. This means that ``v%get(1)`` is the same as the C++
+   ``v[0]``: it returns the first element (i.e. the element with an offset of
+   zero).
+
+Here's an example of modifying a vector::
+
+   use flc_vector, only : Vector => VectorInt4
+   type(Vector) :: v
+   v = Vector()
+   call v%resize(4, 123) ! give each element the value 123
+   call v%push_back(-1) ! size increased by 1, last element has value -1
+   call v%insert(2, -2) ! First 3 elements are [123, 123, -2]
+   call v%erase(1, 3) ! Remove the first two elements
+   call v%erase(2) ! Remove the second element
+   call v%set(1, -123) ! Change the value of the first element
+   call v%clear() ! Remove all elements, size is now zero
+
+Access
+------
+
+The size of a vector is returned by the bound function ``size``; ``get``
+returns the value at an index; and ``front`` and ``back`` are aliases for
+``get(1)`` and ``get(v%size())``, respectively.
+
+Numeric vectors
+===============
+
+As with the algorithms and other methods, the ``flc_vector`` module includes
+three numeric instantiations. They each have distinct derived types:
+
+ - ``VectorInt4``: each element is ``integer(4)``
+ - ``VectorInt8``: each element is ``integer(8)``
+ - ``VectorReal8``: each element is ``real(8)``
+
+Construct from an array
+-----------------------
+
+Numeric vectors can be created very efficiently from Fortran data by accepting
+an array pointer::
+
+   use flc_vector, only : Vector => VectorInt4
+   integer(4), dimension(4), parameter :: iarr = [ 1, -2, 4, -8 ]
+   type(Vector) :: v
+
+   v = Vector(iarr)
+   write(0,*) "Size should be 4:", v%size()
+
+View as an array pointer
+------------------------
+
+Numeric vectors can also return an array pointer to the vector's contents.
+These views support native Fortran array operations and access the same
+underlying memory as the C++ object::
+
+   use flc_vector, only : Vector => VectorInt4
+   integer(4), dimension(:), pointer :: vptr
+   type(Vector) :: v
+
+   ! <snip>
+   vptr => v%view()
+   if (size(vptr) > 2) then
+      vptr(2) = 4
+   end if
+
+.. warning:: A vector's view is valid **only** as long as the vector's size is
+  not changed. Calling ``erase``, ``push_back``, and so forth will invalidate
+  the view; accessing it at that point results in undefined behavior.
+
+String vectors
+==============
+
+String vectors are not yet implemented.
+
+.. ############################################################################
+.. end of doc/modules/vector.rst
+.. ############################################################################

src/flc_vector.i

@@ -0,0 +1,69 @@
+/*!
+ * \file flc_vector.i
+ *
+ * Copyright (c) 2019 Oak Ridge National Laboratory, UT-Battelle, LLC.
+ * Distributed under an MIT open source license: see LICENSE for details.
+ */
+
+%module "flc_vector"
+%include "import_flc.i"
+
+%include <std_vector.i>
+
+/* ------------------------------------------------------------------------- */
+%define EXTEND_STD_VECTOR_POD_INTERNAL(CTYPE)
+  %apply (const SWIGTYPE *DATA, ::size_t SIZE)
+    { (const CTYPE* DATA, size_type SIZE) };
+
+  // Construct from an array of data
+  vector(const CTYPE* DATA, size_type SIZE) {
+    return new std::vector<CTYPE>(DATA, DATA + SIZE);
+  }
+
+  // Assign from another vector
+  void assign(const CTYPE* DATA, size_type SIZE) {
+    $self->assign(DATA, DATA + SIZE);
+  }
+
+  // Get a mutable view to ourself
+  %fortran_array_pointer(CTYPE, vector<CTYPE>& view);
+
+  %typemap(out, noblock=1) vector<CTYPE>& view {
+    $result.data = ($1->empty() ? NULL : &(*$1->begin()));
+    $result.size = $1->size();
+  }
+
+  vector<CTYPE>& view() {
+    return *$self;
+  }
+%enddef
+
+/* ------------------------------------------------------------------------- */
+/*! \def EXTEND_STD_VECTOR_POD_INTERNAL
+ *
+ * Inject member functions and typemaps for POD classes.
+ *
+ * These provide an efficient constructor from a Fortan array view. It also
+ * offers a "view" functionality for getting an array pointer to the
+ * vector-owned data.
+ */
+%define %specialize_std_vector_pod(T)
+namespace std {
+  template<> class vector<T> {
+    SWIG_STD_VECTOR_MINIMUM_INTERNAL(T, const T&)
+    %extend {
+      EXTEND_STD_VECTOR_POD_INTERNAL(T)
+    }
+  };
+}
+%enddef
+
+/* ------------------------------------------------------------------------- */
+
+%specialize_std_vector_pod(int32_t)
+%specialize_std_vector_pod(int64_t)
+%specialize_std_vector_pod(double)
+
+%template(VectorInt4) std::vector<int32_t>;
+%template(VectorInt8) std::vector<int64_t>;
+%template(VectorReal8) std::vector<double>;