Add extended methods and documentation

Author: sethrj

doc/modules/set.rst

@@ -2,15 +2,87 @@
 .. File  : doc/modules/set.rst
 .. ############################################################################
 
-.. _modules_set:
+.. _modules_Set:
 
 ***
 Set
 ***
 
-Sorted sets with unions, intersections, etc., are not yet implemented as
-objects. However, the :ref:`modules_algorithm_set_operations` for arrays can
-replicate some basic Set-like functionality.
+Sets are sorted containers of unique elements. The ``flc_set`` module
+defines sets of ``integer`` and of ``type(String)``.
+
+Common functionality
+====================
+
+All set types support the following basic operations.
+
+Construction and destruction
+----------------------------
+
+Like other wrapped C++ classes in Flibcpp, sets are
+constructed using an interface function. The default constructor is an empty
+set.  Sets are destroyed using the ``release`` type-bound subroutine.
+
+Modification
+------------
+
+The two primary operations on a set are ``insert`` and ``erase`` for adding
+an element to and removing an element from the set. A ``clear`` subroutine
+removes all elements from the set.
+
+The ``size`` method returns the number of elements, and ``count`` will return
+the number of elements of a given value
+
+Here's an example of creating, modifying, and destroying a set::
+
+   use flc_set, only : Set => SetInt4
+   type(Set) :: s
+   s = Set()
+   call s%insert(2)
+   call s%insert(3) ! Set has 2 elements
+   call s%insert(3) ! Duplicate element, ignored
+   call s%erase(2) ! Remove 2 from the set
+   call s%erase(1) ! Nonexistent set element, ignored
+   write(0,*) "Number of 3s in the set:" s%count(3)
+   call s%clear() ! Remove all elements, size is now zero
+   call s%insert(1)
+   call s%release() ! Free memory
+
+Set operations
+--------------
+
+Union, intersection, etc. are not yet implemented.
+
+Numeric sets
+===============
+
+Unlike :ref:`vectors<modules_Vector>`, the ``flc_set`` module includes
+a single "native integer" numeric instantiations. The value type is
+``integer(C_INT)`` and is 64 bits on most modern systems.
+
+Construct from an array
+-----------------------
+
+Numeric sets can be created very efficiently from Fortran data by accepting
+an array argument::
+
+   use flc_set, only : Set => SetInt
+   type(Set) :: s
+
+   s = Set([1, 1, 2, 10])
+   write(0,*) "Size should be 3:", s%size()
+
+The ``assign`` bound method acts like a constructor but for an existing set.
+
+String sets
+==============
+
+The native "element" type of ``SetString`` is a ``character(len=:)``. Set
+operations that accept an input will take any native character string; and
+returned values will be allocatable character arrays.
+
+An additional ``insert_ref`` function allows assignment of
+:ref:`String types <modules_string_type>`
 
 .. ############################################################################
 .. end of doc/modules/set.rst

doc/modules/vector.rst

@@ -20,15 +20,14 @@ All vector types support the following basic operations.
 Construction and destruction
 ----------------------------
 
-Vectors are constructed using three interface functions:
+Vectors are constructed using four 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)
+  - A vector object will create a copy of that vector.
 
 Here are three examples of initialization::
 
@@ -153,7 +152,7 @@ However, as with native pointers described above, these references are
 ``%release()`` bound method.
 
 An additional ``set_ref`` function allows vector elements to be assigned from
-vector classes.
+``String`` types.
 
 .. ############################################################################
 .. end of doc/modules/vector.rst

include/flc_set.i

@@ -11,17 +11,76 @@
 
 %include <std_set.i>
 
+/* -------------------------------------------------------------------------
+ * Macro definitions
+ * ------------------------------------------------------------------------- */
+
+%define %flc_extend_set_pod(CTYPE)
+  %apply (const SWIGTYPE *DATA, ::size_t SIZE)
+    { (const CTYPE* DATA, size_type SIZE) };
+
+  // Construct from an array of data
+  set(const CTYPE* DATA, size_type SIZE) {
+    return new std::set<CTYPE>(DATA, DATA + SIZE);
+  }
+
+  // Insert an array of data
+  void insert(const CTYPE* DATA, size_type SIZE) {
+    $self->insert(DATA, DATA + SIZE);
+  }
+
+%enddef
+
+/* ------------------------------------------------------------------------- */
+/*! \def %specialize_std_set_pod
+ *
+ * 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
+ * set-owned data.
+ *
+ * This definition is considered part of the \em public API so that downstream
+ * apps that generate FLC-based bindings can instantiate their own POD sets.
+ */
+%define %specialize_std_set_pod(T)
+
+// Automatically free temporary sets as appropriate
+%fortran_autofree_rvalue(std::set<T>);
+
+namespace std {
+  template<> class set<T> {
+
+    SWIG_STD_SET_COMMON(set, T, std::less<T>, std::allocator<T>)
+    %extend {
+      %flc_extend_set_pod(T)
+    }
+  };
+}
+%enddef
+
 /* -------------------------------------------------------------------------
  * Numeric sets
  * ------------------------------------------------------------------------- */
 
-%template(SetInt) std::set<int>;
+%specialize_std_set_pod(int)
 
-%include <std_string.i>
-%import "flc_string.i"
+%template(SetInt) std::set<int>;
 
 /* -------------------------------------------------------------------------
  * String sets
  * ------------------------------------------------------------------------- */
 
+%fortran_autofree_rvalue(std::set<std::string>);
+
+// Allow direct insertion of a wrapped std::string
+%extend std::set<std::string> {
+  void insert_ref(std::string& str) {
+    $self->insert(str);
+  }
+}
+
+%include <std_string.i>
+%import "flc_string.i"
 %template(SetString) std::set<std::string>;
+

src/flc_set.f90

@@ -23,6 +23,10 @@ module flc_set
   type(C_PTR), public :: cptr = C_NULL_PTR
   integer(C_INT), public :: cmemflags = 0
  end type
+ type, bind(C) :: SwigArrayWrapper
+  type(C_PTR), public :: data = C_NULL_PTR
+  integer(C_SIZE_T), public :: size = 0
+ end type
  ! class std::set< int >
  type, public :: SetInt
   type(SwigClassWrapper), public :: swigdata
@@ -32,18 +36,17 @@ module flc_set
   procedure :: clear => swigf_SetInt_clear
   procedure :: erase => swigf_SetInt_erase
   procedure :: count => swigf_SetInt_count
-  procedure :: insert => swigf_SetInt_insert
+  procedure, private :: swigf_SetInt_insert__SWIG_0
+  procedure, private :: swigf_SetInt_insert__SWIG_1
   procedure :: release => swigf_release_SetInt
   procedure, private :: swigf_SetInt_op_assign__
   generic :: assignment(=) => swigf_SetInt_op_assign__
+  generic :: insert => swigf_SetInt_insert__SWIG_0, swigf_SetInt_insert__SWIG_1
  end type SetInt
  interface SetInt
-  module procedure swigf_create_SetInt
+  module procedure swigf_new_SetInt__SWIG_0
+  module procedure swigf_new_SetInt__SWIG_1
  end interface
- type, bind(C) :: SwigArrayWrapper
-  type(C_PTR), public :: data = C_NULL_PTR
-  integer(C_SIZE_T), public :: size = 0
- end type
  ! class std::set< std::string >
  type, public :: SetString
   type(SwigClassWrapper), public :: swigdata
@@ -54,6 +57,7 @@ module flc_set
   procedure :: erase => swigf_SetString_erase
   procedure :: count => swigf_SetString_count
   procedure :: insert => swigf_SetString_insert
+  procedure :: insert_ref => swigf_SetString_insert_ref
   procedure :: release => swigf_release_SetString
   procedure, private :: swigf_SetString_op_assign__
   generic :: assignment(=) => swigf_SetString_op_assign__
@@ -64,8 +68,8 @@ module flc_set
 
 ! WRAPPER DECLARATIONS
 interface
-function swigc_new_SetInt() &
-bind(C, name="_wrap_new_SetInt") &
+function swigc_new_SetInt__SWIG_0() &
+bind(C, name="_wrap_new_SetInt__SWIG_0") &
 result(fresult)
 use, intrinsic :: ISO_C_BINDING
 import :: swigclasswrapper
@@ -117,14 +121,33 @@ function swigc_SetInt_count(farg1, farg2) &
 integer(C_LONG) :: fresult
 end function
 
-subroutine swigc_SetInt_insert(farg1, farg2) &
-bind(C, name="_wrap_SetInt_insert")
+subroutine swigc_SetInt_insert__SWIG_0(farg1, farg2) &
+bind(C, name="_wrap_SetInt_insert__SWIG_0")
 use, intrinsic :: ISO_C_BINDING
 import :: swigclasswrapper
 type(SwigClassWrapper) :: farg1
 integer(C_INT), intent(in) :: farg2
 end subroutine
 
+function swigc_new_SetInt__SWIG_1(farg1) &
+bind(C, name="_wrap_new_SetInt__SWIG_1") &
+result(fresult)
+use, intrinsic :: ISO_C_BINDING
+import :: swigclasswrapper
+import :: swigarraywrapper
+type(SwigArrayWrapper) :: farg1
+type(SwigClassWrapper) :: fresult
+end function
+
+subroutine swigc_SetInt_insert__SWIG_1(farg1, farg2) &
+bind(C, name="_wrap_SetInt_insert__SWIG_1")
+use, intrinsic :: ISO_C_BINDING
+import :: swigclasswrapper
+import :: swigarraywrapper
+type(SwigClassWrapper) :: farg1
+type(SwigArrayWrapper) :: farg2
+end subroutine
+
 subroutine swigc_delete_SetInt(farg1) &
 bind(C, name="_wrap_delete_SetInt")
 use, intrinsic :: ISO_C_BINDING
@@ -204,6 +227,14 @@ subroutine swigc_SetString_insert(farg1, farg2) &
 type(SwigArrayWrapper) :: farg2
 end subroutine
 
+subroutine swigc_SetString_insert_ref(farg1, farg2) &
+bind(C, name="_wrap_SetString_insert_ref")
+use, intrinsic :: ISO_C_BINDING
+import :: swigclasswrapper
+type(SwigClassWrapper) :: farg1
+type(SwigClassWrapper) :: farg2
+end subroutine
+
 subroutine swigc_delete_SetString(farg1) &
 bind(C, name="_wrap_delete_SetString")
 use, intrinsic :: ISO_C_BINDING
@@ -224,13 +255,13 @@ subroutine swigc_SetString_op_assign__(farg1, farg2) &
 
 contains
  ! MODULE SUBPROGRAMS
-function swigf_create_SetInt() &
+function swigf_new_SetInt__SWIG_0() &
 result(self)
 use, intrinsic :: ISO_C_BINDING
 type(SetInt) :: self
 type(SwigClassWrapper) :: fresult 
 
-fresult = swigc_new_SetInt()
+fresult = swigc_new_SetInt__SWIG_0()
 self%swigdata = fresult
 end function
 
@@ -316,7 +347,7 @@ function swigf_SetInt_count(self, x) &
 swig_result = int(fresult)
 end function
 
-subroutine swigf_SetInt_insert(self, x)
+subroutine swigf_SetInt_insert__SWIG_0(self, x)
 use, intrinsic :: ISO_C_BINDING
 class(SetInt), intent(in) :: self
 integer(C_INT), intent(in) :: x
@@ -325,7 +356,48 @@ subroutine swigf_SetInt_insert(self, x)
 
 farg1 = self%swigdata
 farg2 = x
-call swigc_SetInt_insert(farg1, farg2)
+call swigc_SetInt_insert__SWIG_0(farg1, farg2)
+end subroutine
+
+subroutine SWIGTM_fin_int_Sb__SB_(finp, iminp)
+  use, intrinsic :: ISO_C_BINDING
+  integer(C_INT), dimension(:), intent(in), target :: finp
+  type(SwigArrayWrapper), intent(out) :: iminp
+  integer(C_SIZE_T) :: sz
+  integer(C_INT), pointer :: imtemp
+
+  sz = size(finp, kind=C_SIZE_T)
+  if (sz > 0_c_size_t) then
+    imtemp => finp(1)
+    iminp%data = c_loc(imtemp)
+  else
+    iminp%data = c_null_ptr
+  end if
+  iminp%size = sz
+end subroutine
+function swigf_new_SetInt__SWIG_1(data) &
+result(self)
+use, intrinsic :: ISO_C_BINDING
+type(SetInt) :: self
+integer(C_INT), dimension(:), intent(in), target :: data
+type(SwigClassWrapper) :: fresult 
+type(SwigArrayWrapper) :: farg1 
+
+call SWIGTM_fin_int_Sb__SB_(data, farg1)
+fresult = swigc_new_SetInt__SWIG_1(farg1)
+self%swigdata = fresult
+end function
+
+subroutine swigf_SetInt_insert__SWIG_1(self, data)
+use, intrinsic :: ISO_C_BINDING
+class(SetInt), intent(in) :: self
+integer(C_INT), dimension(:), intent(in), target :: data
+type(SwigClassWrapper) :: farg1 
+type(SwigArrayWrapper) :: farg2 
+
+farg1 = self%swigdata
+call SWIGTM_fin_int_Sb__SB_(data, farg2)
+call swigc_SetInt_insert__SWIG_1(farg1, farg2)
 end subroutine
 
 subroutine swigf_release_SetInt(self)
@@ -467,6 +539,18 @@ subroutine swigf_SetString_insert(self, x)
 call swigc_SetString_insert(farg1, farg2)
 end subroutine
 
+subroutine swigf_SetString_insert_ref(self, str)
+use, intrinsic :: ISO_C_BINDING
+class(SetString), intent(in) :: self
+class(string), intent(in) :: str
+type(SwigClassWrapper) :: farg1 
+type(SwigClassWrapper) :: farg2 
+
+farg1 = self%swigdata
+farg2 = str%swigdata
+call swigc_SetString_insert_ref(farg1, farg2)
+end subroutine
+
 subroutine swigf_release_SetString(self)
 use, intrinsic :: ISO_C_BINDING
 class(SetString), intent(inout) :: self