Added to_lower, to_upper, reverse and to_title function to stdlib_string_type.f90 file (#346)

* added interface for to_lower, to_upper, to_title, reverse functions

* added better comments to the stdlib_ascii.f90

* added comments to stdlib_string_type.f90.   function is elemental or pure (query)??

* improved line spacing; nothing special in this commit

* cleaning namespace and using the maybe

Note: here how using maybe(string) automatically access the string%raw.
maybe is used for safe memory access.

Co-authored-by: Sebastian Ehlert <[email protected]>

* stay within 80 characters line length

* fix result variable names

* added dependency of modules in Makefile.manual, updated comments, fixed typo in README.md

* adding unit tests for to_lower, to_upper, reverse, to_title functions of stdlib_string_type module

* Documented the newly created functions in stdlib_string_type.md

* improved documentation of to_title function

* Reorder function exports

Co-authored-by: Sebastian Ehlert <[email protected]>
Co-authored-by: milancurcic <[email protected]>

Author: 3 people

README.md

@@ -150,7 +150,7 @@ To test your build, run the test suite after the build has finished with
 cmake --build build --target test
 ```
 
-Please report failing tests on our [issue tracker](https://github.com/fortran-lang/stdlib/issues/new/choose) including details on the compiler used, the operating system and platform architecture.
+Please report failing tests on our [issue tracker](https://github.com/fortran-lang/stdlib/issues/new/choose) including details of the compiler used, the operating system and platform architecture.
 
 To install the project to the declared prefix run
 

doc/specs/stdlib_string_type.md

@@ -1041,6 +1041,187 @@ end program demo
 ```
 
 
+<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
+### To\_lower function
+
+#### Description
+
+Returns a new string_type instance which holds the lowercase version of the character sequence hold by the input string.
+
+#### Syntax
+
+`lowercase_string = [[stdlib_string_type(module): to_lower(interface)]] (string)`
+
+#### Status
+
+Experimental
+
+#### Class
+
+Elemental function.
+
+#### Argument
+
+`string`: Instance of `string_type`. This argument is `intent(in)`.
+
+#### Result Value
+
+The Result is a scalar `string_type` value.
+
+#### Example
+
+```fortran
+program demo
+  use stdlib_string_type
+  implicit none
+  type(string_type) :: string, lowercase_string
+
+  string = "Lowercase This String"
+  ! string <-- "Lowercase This String"
+
+  lowercase_string = to_lower(string)
+  ! string <-- "Lowercase This String"
+  ! lowercase_string <-- "lowercase this string"
+end program demo
+```
+
+
+<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
+### To\_upper function
+
+#### Description
+
+Returns a new string_type instance which holds the uppercase version of the character sequence hold by the input string.
+
+#### Syntax
+
+`uppercase_string = [[stdlib_string_type(module): to_upper(interface)]] (string)`
+
+#### Status
+
+Experimental
+
+#### Class
+
+Elemental function.
+
+#### Argument
+
+`string`: Instance of `string_type`. This argument is `intent(in)`.
+
+#### Result Value
+
+The Result is a scalar `string_type` value.
+
+#### Example
+
+```fortran
+program demo
+  use stdlib_string_type
+  implicit none
+  type(string_type) :: string, uppercase_string
+
+  string = "Uppercase This String"
+  ! string <-- "Uppercase This String"
+
+  uppercase_string = to_upper(string)
+  ! string <-- "Uppercase This String"
+  ! uppercase_string <-- "UPPERCASE THIS STRING"
+end program demo
+```
+
+
+<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
+### To\_title function
+
+#### Description
+
+Returns a new string_type instance which holds the titlecase (or capitalized) version of the character sequence hold by the input string.
+Capitalized version: The first alphabetical character of the input character sequence is transformed to uppercase unless it 
+follows a numeral and the rest of the characters in the sequence are transformed to lowercase.
+
+#### Syntax
+
+`titlecase_string = [[stdlib_string_type(module): to_title(interface)]] (string)`
+
+#### Status
+
+Experimental
+
+#### Class
+
+Elemental function.
+
+#### Argument
+
+`string`: Instance of `string_type`. This argument is `intent(in)`.
+
+#### Result Value
+
+The Result is a scalar `string_type` value.
+
+#### Example
+
+```fortran
+program demo
+  use stdlib_string_type
+  implicit none
+  type(string_type) :: string, titlecase_string
+
+  string = "Titlecase This String"
+  ! string <-- "Titlecase This String"
+
+  titlecase_string = to_title(string)
+  ! string <-- "Titlecase This String"
+  ! titlecase_string <-- "Titlecase this string"
+end program demo
+```
+
+<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
+### Reverse function
+
+#### Description
+
+Returns a new string_type instance which holds the reversed version of the character sequence hold by the input string.
+
+#### Syntax
+
+`reverse_string = [[stdlib_string_type(module): reverse(interface)]] (string)`
+
+#### Status
+
+Experimental
+
+#### Class
+
+Elemental function.
+
+#### Argument
+
+`string`: Instance of `string_type`. This argument is `intent(in)`.
+
+#### Result Value
+
+The Result is a scalar `string_type` value.
+
+#### Example
+
+```fortran
+program demo
+  use stdlib_string_type
+  implicit none
+  type(string_type) :: string, reverse_string
+  
+  string = "Reverse This String"
+  ! string <-- "Reverse This String"
+
+  reverse_string = reverse(string)
+  ! string <-- "Reverse This String"
+  ! reverse_string <-- "gnirtS sihT esreveR"
+end program demo
+```
+
+
 <!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
 ### Comparison operator greater
 

src/Makefile.manual

@@ -109,3 +109,4 @@ stdlib_stats_var.o: \
 stdlib_stats_distribution_PRNG.o: \
         stdlib_kinds.o \
 	stdlib_error.o
+stdlib_string_type.o: stdlib_ascii.o

src/stdlib_ascii.f90

@@ -64,6 +64,36 @@ module stdlib_ascii
     character(len=*), public, parameter :: lowercase = letters(27:) !! a .. z
     character(len=*), public, parameter :: whitespace = " "//TAB//VT//CR//LF//FF !! ASCII _whitespace
 
+
+    !> Returns a new character sequence which is the lower case 
+    !> version of the input character sequence
+    !> This method is pure and returns a character sequence
+    interface to_lower
+        module procedure :: to_lower
+    end interface to_lower
+
+    !> Returns a new character sequence which is the upper case
+    !> version of the input character sequence
+    !> This method is pure and returns a character sequence
+    interface to_upper
+        module procedure :: to_upper
+    end interface to_upper
+
+    !> Returns a new character sequence which is the title case
+    !> version of the input character sequence
+    !> This method is pure and returns a character sequence
+    interface to_title
+        module procedure :: to_title
+    end interface to_title
+
+    !> Returns a new character sequence which is reverse of
+    !> the input charater sequence
+    !> This method is pure and returns a character sequence
+    interface reverse
+        module procedure :: reverse
+    end interface reverse
+    
+
 contains
 
     !> Checks whether `c` is an ASCII letter (A .. Z, a .. z).

src/stdlib_string_type.f90

@@ -12,12 +12,16 @@
 !>
 !> The specification of this module is available [here](../page/specs/stdlib_string_type.html).
 module stdlib_string_type
+    use stdlib_ascii, only: to_lower_ => to_lower, to_upper_ => to_upper, &
+                            to_title_ => to_title, reverse_ => reverse
+
     implicit none
     private
 
     public :: string_type
     public :: len, len_trim, trim, index, scan, verify, repeat, adjustr, adjustl
     public :: lgt, lge, llt, lle, char, ichar, iachar
+    public :: to_lower, to_upper, to_title, reverse
     public :: assignment(=)
     public :: operator(>), operator(>=), operator(<), operator(<=)
     public :: operator(==), operator(/=), operator(//)
@@ -89,6 +93,38 @@ module stdlib_string_type
         module procedure :: repeat_string
     end interface repeat
 
+    !> Returns the lowercase version of the character sequence hold by the input string
+    !>
+    !> This method is Elemental and returns a new string_type instance which holds this
+    !> lowercase character sequence
+    interface to_lower
+        module procedure :: to_lower_string
+    end interface to_lower
+
+    !> Returns the uppercase version of the character sequence hold by the input string
+    !>
+    !> This method is Elemental and returns a new string_type instance which holds this
+    !> uppercase character sequence
+    interface to_upper
+        module procedure :: to_upper_string
+    end interface to_upper
+
+    !> Returns the titlecase version of the character sequence hold by the input string
+    !>
+    !> This method is Elemental and returns a new string_type instance which holds this
+    !> titlecase character sequence
+    interface to_title
+        module procedure :: to_title_string
+    end interface to_title
+
+    !> Reverses the character sequence hold by the input string
+    !> 
+    !> This method is Elemental and returns a new string_type instance which holds this
+    !> reverse character sequence
+    interface reverse
+        module procedure :: reverse_string
+    end interface reverse
+
     !> Return the character sequence represented by the string.
     !>
     !> This method is elemental and returns a scalar character value.
@@ -447,6 +483,46 @@ elemental function repeat_string(string, ncopies) result(repeated_string)
     end function repeat_string
 
 
+    !> Convert the character sequence hold by the input string to lower case
+    elemental function to_lower_string(string) result(lowercase_string)
+        type(string_type), intent(in) :: string
+        type(string_type) :: lowercase_string
+
+        lowercase_string%raw = to_lower_(maybe(string))
+
+    end function to_lower_string
+
+
+    !> Convert the character sequence hold by the input string to upper case
+    elemental function to_upper_string(string) result(uppercase_string)
+        type(string_type), intent(in) :: string
+        type(string_type) :: uppercase_string
+
+        uppercase_string%raw = to_upper_(maybe(string))
+
+    end function to_upper_string
+
+
+    !> Convert the character sequence hold by the input string to title case
+    elemental function to_title_string(string) result(titlecase_string)
+        type(string_type), intent(in) :: string
+        type(string_type) :: titlecase_string
+
+        titlecase_string%raw = to_title_(maybe(string))
+
+    end function to_title_string
+
+
+    !> Reverse the character sequence hold by the input string
+    elemental function reverse_string(string) result(reversed_string)
+        type(string_type), intent(in) :: string
+        type(string_type) :: reversed_string
+
+        reversed_string%raw = reverse_(maybe(string))
+
+    end function reverse_string
+
+
     !> Position of a sequence of character within a character sequence.
     !> In this version both character sequences are represented by a string.
     elemental function index_string_string(string, substring, back) result(pos)