Extend stdlib_ascii module for handling character variables

- extend to_lower function to work on character strings
- extend to_upper function to work on character strings
- implement to_title function
- implement reverse function

Author: awvwgk

doc/specs/index.md

@@ -11,6 +11,7 @@ This is and index/directory of the specifications (specs) for each new module/fe
 
 ## Experimental Features & Modules
 
+ - [ascii](./stdlib_ascii.html) - Procedures for handling ASCII characters
  - [bitsets](./stdlib_bitsets.html) - Bitset data types and procedures
  - [error](./stdlib_error.html) - Catching and handling errors
  - [IO](./stdlib_io.html) - Input/output helper & convenience
@@ -22,7 +23,6 @@ This is and index/directory of the specifications (specs) for each new module/fe
 
 ## Missing specs
 
- - [ascii](https://github.com/fortran-lang/stdlib/blob/master/src/stdlib_ascii.f90)
  - [kinds](https://github.com/fortran-lang/stdlib/blob/master/src/stdlib_kinds.f90)
 
 ## Released/Stable Features & Modules

doc/specs/stdlib_ascii.md

@@ -0,0 +1,149 @@
+---
+title: ASCII
+---
+
+# The `stdlib_ascii` module
+
+[TOC]
+
+## Introduction
+
+The `stdlib_ascii` module provides procedures for handling and manipulating
+intrinsic character variables and constants.
+
+
+## Constants provided by `stdlib_ascii`
+
+@note Specification of constants is currently incomplete.
+
+
+## Specification of the `stdlib_ascii` procedures
+
+@note Specification of procedures is currently incomplete.
+
+
+### `to_lower`
+
+#### Status
+
+Experimental
+
+#### Description
+
+Converts input character variable to all lowercase.
+
+#### Syntax
+
+```f90
+res = to_lower("HELLO!")
+! res == "hello!"
+```
+
+#### Class
+
+Pure function.
+
+#### Argument
+
+`string`: shall be an intrinsic character type. It is an `intent(in)` argument.
+
+#### Result value
+
+The result is an intrinsic character type of the same length as `string`.
+
+
+### `to_upper`
+
+#### Status
+
+Experimental
+
+#### Description
+
+Converts input character variable to all uppercase.
+
+#### Syntax
+
+```
+res = to_upper("hello!")
+! res == "HELLO!"
+```
+
+#### Class
+
+Pure function.
+
+#### Argument
+
+`string`: shall be an intrinsic character type. It is an `intent(in)` argument.
+
+#### Result value
+
+The result is an intrinsic character type of the same length as `string`.
+
+
+### `to_title`
+
+#### Status
+
+Experimental
+
+#### Description
+
+Returns capitalized version of input character variable.
+The first alphanumeric character is capitalized.
+
+#### Syntax
+
+```
+res = to_title("hello!")
+! res == "Hello!"
+res = to_title("'enquoted'")
+! res == "'Enquoted'"
+res = to_title("1st")
+! res == "1st"
+```
+
+#### Class
+
+Pure function.
+
+#### Argument
+
+`string`: shall be an intrinsic character type. It is an `intent(in)` argument.
+
+#### Result value
+
+The result is an intrinsic character type of the same length as `string`.
+
+
+### `reverse`
+
+#### Status
+
+Experimental
+
+#### Description
+
+Reverses the order of all characters in the input character type.
+
+#### Syntax
+
+```f90
+res = reverse("Hello, World!")
+! res == "!dlroW ,olleH"
+res = reverse(res)
+! res == "Hello, World!"
+```
+
+#### Class
+
+Pure function.
+
+#### Argument
+
+`string`: shall be an intrinsic character type. It is an `intent(in)` argument.
+
+#### Result value
+
+The result is an intrinsic character type of the same length as `string`.

src/stdlib_ascii.f90

@@ -12,7 +12,7 @@ module stdlib_ascii
     public :: is_lower, is_upper
 
     ! Character conversion functions
-    public :: to_lower, to_upper
+    public :: to_lower, to_upper, to_title, reverse
 
     ! All control characters in the ASCII table (see www.asciitable.com).
     character(len=1), public, parameter :: NUL = achar(int(z'00')) !! Null
@@ -60,9 +60,6 @@ module stdlib_ascii
     character(len=*), public, parameter :: lowercase = letters(27:) !! a .. z
     character(len=*), public, parameter :: whitespace = " "//TAB//VT//CR//LF//FF !! ASCII _whitespace
 
-    character(len=26), parameter, private :: lower_case = 'abcdefghijklmnopqrstuvwxyz'
-    character(len=26), parameter, private :: upper_case = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
-
 contains
 
     !> Checks whether `c` is an ASCII letter (A .. Z, a .. z).
@@ -179,34 +176,94 @@ pure logical function is_blank(c)
 
     !> Returns the corresponding lowercase letter, if `c` is an uppercase
     !  ASCII character, otherwise `c` itself.
-    pure function to_lower(c) result(t)
+    pure function char_to_lower(c) result(t)
         character(len=1), intent(in) :: c !! A character.
         character(len=1)             :: t
         integer :: k
 
-        k = index( upper_case, c )
+        k = index( uppercase, c )
 
         if ( k > 0 ) then
-            t = lower_case(k:k)
+            t = lowercase(k:k)
         else
             t = c
         endif
-    end function
+    end function char_to_lower
 
     !> Returns the corresponding uppercase letter, if `c` is a lowercase
     !  ASCII character, otherwise `c` itself.
-    pure function to_upper(c) result(t)
+    pure function char_to_upper(c) result(t)
         character(len=1), intent(in) :: c !! A character.
         character(len=1)             :: t
         integer :: k
 
-        k = index( lower_case, c )
+        k = index( lowercase, c )
 
         if ( k > 0 ) then
-            t = upper_case(k:k)
+            t = uppercase(k:k)
         else
             t = c
         endif
-    end function
+    end function char_to_upper
+
+    !> Convert character variable to lower case
+    pure function to_lower(string) result(lower_string)
+        character(len=*), intent(in) :: string
+        character(len=len(string)) :: lower_string
+        integer :: i
+
+        do i = 1, len(string)
+            lower_string(i:i) = char_to_lower(string(i:i))
+        end do
+
+    end function to_lower
+
+    !> Convert character variable to upper case
+    pure function to_upper(string) result(upper_string)
+        character(len=*), intent(in) :: string
+        character(len=len(string)) :: upper_string
+        integer :: i
+
+        do i = 1, len(string)
+            upper_string(i:i) = char_to_upper(string(i:i))
+        end do
+
+    end function to_upper
+
+    !> Convert character variable to title case
+    pure function to_title(string) result(title_string)
+        character(len=*), intent(in) :: string
+        character(len=len(string)) :: title_string
+        integer :: i, n
+
+        n = len(string)
+        do i = 1, len(string)
+            if (is_alphanum(string(i:i))) then
+                title_string(i:i) = char_to_upper(string(i:i))
+                n = i
+                exit
+            else
+                title_string(i:i) = string(i:i)
+            end if
+        end do
+
+        do i = n + 1, len(string)
+            title_string(i:i) = char_to_lower(string(i:i))
+        end do
+
+    end function to_title
+
+    !> Reverse the character order in the input character variable
+    pure function reverse(string) result(reverse_string)
+        character(len=*), intent(in) :: string
+        character(len=len(string)) :: reverse_string
+        integer :: i, n
+
+        n = len(string)
+        do i = 1, n
+            reverse_string(n-i+1:n-i+1) = string(i:i)
+        end do
+
+    end function reverse
 
-end module
+end module stdlib_ascii

src/tests/ascii/test_ascii.f90

@@ -6,7 +6,7 @@ program test_ascii
         whitespace, letters, is_alphanum, is_alpha, is_lower, is_upper, &
         is_digit, is_octal_digit, is_hex_digit, is_white, is_blank, &
         is_control, is_punctuation, is_graphical, is_printable, is_ascii, &
-        to_lower, to_upper, LF, TAB, NUL, DEL
+        to_lower, to_upper, to_title, reverse, LF, TAB, NUL, DEL
 
     implicit none
 
@@ -68,6 +68,11 @@ program test_ascii
 
     ! call test_ascii_table
 
+    call test_to_upper_string
+    call test_to_lower_string
+    call test_to_title_string
+    call test_reverse_string
+
 contains
 
     subroutine test_is_alphanum_short
@@ -540,4 +545,72 @@ pure logical function validation_func_interface(c)
         write(*,'(5X,12(I4))') (count(table(:,i)),i=1,12)
     end subroutine test_ascii_table
 
+    subroutine test_to_lower_string
+        character(len=:), allocatable :: dlc
+        character(len=32), parameter :: input = "UPPERCASE"
+
+        dlc = to_lower("UPPERCASE")
+        call check(dlc == "uppercase")
+
+        dlc = to_lower(input)
+        call check(len(dlc) == 32)
+        call check(len_trim(dlc) == 9)
+        call check(trim(dlc) == "uppercase")
+
+        dlc = to_lower("0123456789ABCDE")
+        call check(dlc == "0123456789abcde")
+    end subroutine test_to_lower_string
+
+    subroutine test_to_upper_string
+        character(len=:), allocatable :: dlc
+        character(len=32), parameter :: input = "lowercase"
+
+        dlc = to_upper("lowercase")
+        call check(dlc == "LOWERCASE")
+
+        dlc = to_upper(input)
+        call check(len(dlc) == 32)
+        call check(len_trim(dlc) == 9)
+        call check(trim(dlc) == "LOWERCASE")
+
+        dlc = to_upper("0123456789abcde")
+        call check(dlc == "0123456789ABCDE")
+    end subroutine test_to_upper_string
+
+    subroutine test_to_title_string
+        character(len=:), allocatable :: dlc
+        character(len=32), parameter :: input = "tiTLe"
+
+        dlc = to_title("tiTLe")
+        call check(dlc == "Title")
+
+        dlc = to_title(input)
+        call check(len(dlc) == 32)
+        call check(len_trim(dlc) == 5)
+        call check(trim(dlc) == "Title")
+
+        dlc = to_title(" s P a C e D !")
+        call check(dlc == " S p a c e d !")
+
+        dlc = to_title("1st, 2nd, 3rd")
+        call check(dlc == "1st, 2nd, 3rd")
+
+        dlc = to_title("""quOTed""")
+        call check(dlc == """Quoted""")
+    end subroutine test_to_title_string
+
+    subroutine test_reverse_string
+        character(len=:), allocatable :: dlc
+        character(len=32), parameter :: input = "reversed"
+
+        dlc = reverse("reversed")
+        call check(dlc == "desrever")
+
+        dlc = reverse(input)
+        call check(len(dlc) == 32)
+        call check(len_trim(dlc) == 32)
+        call check(trim(dlc) == "                        desrever")
+        call check(trim(adjustl(dlc)) == "desrever")
+    end subroutine test_reverse_string
+
 end program test_ascii