Add std::string support

Author: sethrj

CMakeLists.txt

@@ -165,10 +165,16 @@ endfunction()
 
 # Four SWIG libraries
 swig_fortran_add_module(flc "${FLIBCPP_VERSION_CPP}")
-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_random)
+target_link_libraries(flc_random flc)
+
+swig_fortran_add_module(flc_string)
+target_link_libraries(flc_string flc)
+
 swig_fortran_add_module(flc_vector)
 target_link_libraries(flc_vector flc)
 

doc/interface.rst

@@ -36,6 +36,12 @@ flc_random
 .. literalinclude:: ../src/flc_random.i
    :linenos:
 
+flc_string
+=============
+
+.. literalinclude:: ../src/flc_string.i
+   :linenos:
+
 flc_vector
 =============
 

doc/modules/algorithm.rst

@@ -72,6 +72,8 @@ zero.
 
 .. _argsort: https://docs.scipy.org/doc/numpy-1.15.0/reference/generated/numpy.argsort.html
 
+.. _modules_algorithm_searching:
+
 Searching
 =========
 

doc/modules/string.rst

@@ -8,7 +8,139 @@
 String
 ******
 
-String manipulation is not yet implemented.
+The string module includes the ``String`` derived type and a handful of string
+conversion functions.
+
+String type
+===========
+
+The C++ standard library "string" is a dynamically resizable, mutable character
+array.
+
+Construction and destruction
+----------------------------
+
+Strings are constructed using three interface functions:
+
+  - The function without arguments creates an empty string;
+  - An integer argument ``count`` and a single character will create a string
+    of size ``count`` filled with that character; and
+  - A standard Fortran ``character(kind=C_CHAR, len=*)`` which will be copied
+    to the string.
+
+Here are three examples of initialization::
+
+   use flc_string, only : String
+   type(String) :: v
+
+   s = String()
+   ! s%size() == 0
+   s = String(10, "!")
+   ! s%size() == 10
+   ! s%get(i) == "!"
+   s = String("I am a string!")
+
+Modification
+------------
+
+Like :ref:`vectors <modules_Vector>`, Strings can be resized dynamically using
+a variety of methods:
+
+  - ``resize`` to specify an exact size;
+  - ``push_back`` to add a new character to the end of it;
+  - ``append`` to add another string to the end
+  - ``pop_back`` to remove the last character;
+  - ``clear`` to remove all elements.
+
+The string also has a ``set`` bound subroutine for assigning a character to a
+specified index::
+
+   type(String) :: s
+
+   s = String("=", 10)
+   call s%set(1, "8")
+   call s%set(s%size(), "D")
+
+.. important:: Unlike the C++ version of this class, **strings in Flibcpp
+   use 1-offset indexing**. This means that ``s%get(1)`` is the same as the C++
+   ``s[0]``: it returns the first element (i.e. the element with an offset of
+   zero).
+
+Access
+------
+
+The size of a string is returned by the bound function ``size``; ``get``
+returns the character at an index; and ``front`` and ``back`` are aliases for
+``get(1)`` and ``get(v%size())``, respectively.
+
+Search
+------
+
+The ``find`` bound function will search for a substring, starting at an
+optional position. Like the :ref:`search
+algorithms <modules_algorithm_searching>` in Flibcpp, a search result of `0`
+indicates "not found" and any other result is the 1-offset index in the
+string. ::
+
+   type(String) :: s
+   integer :: i
+
+   s = String("meowmeow")
+   i = s%find("meow")    ! Returns 1
+   i = s%find("meow", 3) ! Returns 5
+   i = s%find("woof")    ! Returns 0
+
+View as an array pointer
+------------------------
+
+The string can be viewed (and indeed modified) as an array of character
+elements::
+
+   type(String) :: s
+   character, dimension(:), pointer :: charptr
+
+   s = String("Hello!")
+   charptr => s%view()
+   charptr(6) = "?" ! change greeting to a question
+
+Conversion to native string
+---------------------------
+
+The ``str`` type-bound function returns an allocated character string::
+
+   character(len=:), allocatable :: native
+   type(String) :: s
+
+   s = String("Hello world")
+   native = s%str()
+   write(0,"(a)") native
+
+
+Conversion functions
+====================
+
+The ``flc_string`` module includes several module procedures for converting
+native Fortran strings to integers and real numbers. These functions are robust
+and exception-safe, allowing intelligent error handling from the Fortran side.
+
+ - Integer conversion: ``stoi``, ``stol``, ``stoll``
+ - Real conversion: ``stof``, ``stod``
+
+::
+
+   use flc, only : ierr, get_serr, SWIG_OverflowError, SWIG_ValueError
+   use flc_string
+   implicit none
+   integer(4) :: temp
+   character(len=100) :: tempstr
+
+   read(*, '(a)') tempstr
+   temp = stoi(trim(tempstr))
+   if (ierr == SWIG_OverflowError) then
+     write(0,*) "Your integer is too darn big!"
+   elseif (ierr == SWIG_ValueError) then
+     write(0,*) "That thing you entered? It wasn't an integer."
+   end if
 
 .. ############################################################################
 .. end of doc/modules/string.rst

doc/modules/vector.rst

@@ -52,7 +52,7 @@ the end of the vector (increasing the size by one) with ``push_back``. The
 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
+.. 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).

src/flc_string.i

@@ -0,0 +1,132 @@
+/*!
+ * \file flc_string.i
+ *
+ * Copyright (c) 2019 Oak Ridge National Laboratory, UT-Battelle, LLC.
+ * Distributed under an MIT open source license: see LICENSE for details.
+ */
+
+%module "flc_string"
+%include "import_flc.i"
+
+// SWIG always represents std::string as native strings. We load its typemaps
+// but will explicitly create the class.
+%include <std_string.i>
+
+// Include typemaps for integer offsets and native integer types
+%include <std_common.i>
+
+// Typemap to convert positions from npos -> 0 and 1-offset otherwise
+%apply int FORTRAN_INT { std::size_t POSITION };
+%typemap(out, noblock=1) std::size_t POSITION {
+  $result = ($1 == std::string::npos ? 0 : $1 + 1);
+}
+
+namespace std {
+class string {
+  public:
+    // >>> TYPES
+    typedef size_t size_type;
+    typedef ptrdiff_t difference_type;
+    typedef char value_type;
+    typedef const char& const_reference;
+
+    // Typemaps for making std::vector feel more like native Fortran:
+    // - Use Fortran 1-offset indexing
+    %apply int FORTRAN_INDEX {size_type pos,
+                              size_type index,
+                              size_type start_index,
+                              size_type stop_index};
+    // - Use native Fortran integers in proxy code
+    %apply int FORTRAN_INT {size_type};
+
+    // - Use fortran indexing (and 0 for not found) for search
+    %apply std::size_t POSITION {size_type find};
+
+    // - Allow access as an array view
+    %apply SWIGTYPE& { string& view };
+    %fortran_array_pointer(char, string& view);
+    %typemap(out, noblock=1) string& view {
+      $result.data = ($1->empty() ? NULL : const_cast<char*>($1->data()));
+      $result.size = $1->size();
+    }
+
+    // - Allow interaction with other string objects
+    %apply SWIGTYPE& {const string& OTHER};
+
+  public:
+    // >>> MEMBER FUNCTIONS
+
+    // TODO: add more constructors
+    string();
+    string(size_type count, value_type ch);
+    string(const std::string& s);
+
+    // Accessors
+    size_type size() const;
+    bool empty() const;
+
+    const_reference front() const;
+    const_reference back() const;
+
+    // Modify
+    void resize(size_type count);
+    void resize(size_type count, value_type v);
+    void assign(const string& s);
+    void push_back(value_type v);
+    void pop_back();
+    void clear();
+
+    // String operations
+    size_type find(const string& s, size_type pos = 0);
+    void append(const string& s);
+    int compare(const string& OTHER);
+
+    // >>> EXTENSIONS
+    // (TODO: add the same erase/insert extensions as std::vector)
+
+    %extend {
+      %fragment("SWIG_check_range");
+
+      void set(size_type index, value_type v) {
+        SWIG_check_range(index, $self->size(),
+                         "std::string::set",
+                         return);
+        (*$self)[index] = v;
+      }
+
+      value_type get(size_type index) {
+        SWIG_check_range(index, $self->size(),
+                         "std::string::get",
+                         return $self->front());
+        return (*$self)[index];
+      }
+
+      // Get a character array view
+      string& view() { return *$self; }
+
+      // Get a copy as a native Fortran string
+      const string& str() { return *$self; }
+    }
+};
+
+%exception {
+  SWIG_check_unhandled_exception();
+  try {
+    $action
+  }
+  catch (const std::invalid_argument& e) {
+    SWIG_exception(SWIG_ValueError, e.what());
+  }
+  catch (const std::out_of_range& e) {
+    SWIG_exception(SWIG_OverflowError, e.what());
+  }
+}
+
+// String conversion
+int stoi(const std::string& s);
+long stol(const std::string& s);
+long long stoll(const std::string& s);
+float stof(const std::string& s);
+double stod(const std::string& s);
+
+} // namespace std

src/generated/flc.f90

@@ -21,6 +21,19 @@ module flc
   integer(C_SIZE_T), public :: size = 0
  end type
  public :: get_serr
+ integer(C_INT), parameter, public :: SWIG_UnknownError = -1_C_INT
+ integer(C_INT), parameter, public :: SWIG_IOError = -2_C_INT
+ integer(C_INT), parameter, public :: SWIG_RuntimeError = -3_C_INT
+ integer(C_INT), parameter, public :: SWIG_IndexError = -4_C_INT
+ integer(C_INT), parameter, public :: SWIG_TypeError = -5_C_INT
+ integer(C_INT), parameter, public :: SWIG_DivisionByZero = -6_C_INT
+ integer(C_INT), parameter, public :: SWIG_OverflowError = -7_C_INT
+ integer(C_INT), parameter, public :: SWIG_SyntaxError = -8_C_INT
+ integer(C_INT), parameter, public :: SWIG_ValueError = -9_C_INT
+ integer(C_INT), parameter, public :: SWIG_SystemError = -10_C_INT
+ integer(C_INT), parameter, public :: SWIG_AttributeError = -11_C_INT
+ integer(C_INT), parameter, public :: SWIG_MemoryError = -12_C_INT
+ integer(C_INT), parameter, public :: SWIG_NullReferenceError = -13_C_INT
  public :: get_flibcpp_version
  integer(C_INT), protected, public, &
    bind(C, name="flibcpp_version_major") :: flibcpp_version_major