implemented intelligent slice functionality

doc/specs/stdlib_string_type.md

@@ -1254,7 +1254,7 @@ The result is a scalar `string_type` value.
 
 ```fortran
 program demo_to_title
-  use stdlib_string_type, only: string_type, to_title
+  use stdlib_string_type
   implicit none
   type(string_type) :: string, titlecase_string
 
@@ -1302,7 +1302,7 @@ The result is a scalar `string_type` value.
 
 ```fortran
 program demo_to_sentence
-  use stdlib_string_type, only: string_type, to_sentence
+  use stdlib_string_type
   implicit none
   type(string_type) :: string, sentencecase_string
 

doc/specs/stdlib_strings.md

@@ -192,3 +192,64 @@ program demo
   print'(a)', ends_with("pattern", "pat")  ! F
 end program demo
 ```
+
+
+<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
+### `slice`
+
+#### Description
+
+Extracts the characters from the defined region of the input string.  
+Argument `first` and `last` defines the region for the function `slice` to operate.  
+Extraction starts from the index `first` and takes stride of length `stride`.  
+Argument `stride` cannot take the value 0.
+
+#### Syntax
+
+`string = [[stdlib_strings(module):slice(interface)]] (string, first, last, stride)`
+
+#### Status
+
+Experimental
+
+#### Class
+
+Pure function.
+
+#### Argument
+
+- `string`: Character scalar or [[stdlib_string_type(module):string_type(type)]]
+  This argument is intent(in).
+- `first`: integer
+  This argument is intent(in) and optional.
+- `last`: integer
+  This argument is intent(in) and optional.
+- `stride`: integer
+  This argument is intent(in) and optional.
+
+#### Result value
+
+The result is of the same type as `string`.
+
+#### Example
+
+```fortran
+program demo_slice
+  use stdlib_string_type
+  use stdlib_strings, only : slice
+  implicit none
+  type(string_type) :: string
+  character(len=10) :: char
+
+  string = "abcdefghij"
+  ! string <-- "abcdefghij"
+
+  char = "abcdefghij"
+  ! char <-- "abcdefghij"
+
+  print'(a)', slice("abcdefghij", 2, 6, 2)   ! "bdf"
+  print'(a)', slice(string, 2, 6, 2)         ! "bdf"
+  print'(a)', slice(char, 2, 6, 2)           ! "bdf"
+
+end program demo_slice
+```

src/Makefile.manual

@@ -112,6 +112,9 @@ stdlib_stats_var.o: \
 stdlib_stats_distribution_PRNG.o: \
         stdlib_kinds.o \
 	stdlib_error.o
-stdlib_string_type.o: stdlib_ascii.o stdlib_kinds.o
-stdlib_strings.o: stdlib_ascii.o stdlib_string_type.o
+stdlib_string_type.o: stdlib_ascii.o \
+	stdlib_kinds.o
+stdlib_strings.o: stdlib_ascii.o \
+	stdlib_string_type.o \
+	stdlib_math.o
 stdlib_math.o: stdlib_kinds.o

src/stdlib_strings.f90

@@ -6,11 +6,13 @@
 module stdlib_strings
     use stdlib_ascii, only : whitespace
     use stdlib_string_type, only : string_type, char, verify
+    use stdlib_math, only: clip
     implicit none
     private
 
     public :: strip, chomp
     public :: starts_with, ends_with
+    public :: slice
 
 
     !> Remove leading and trailing whitespace characters.
@@ -57,6 +59,14 @@ module stdlib_strings
         module procedure :: ends_with_char_string
         module procedure :: ends_with_char_char
     end interface ends_with
+
+    !> Slices the input string to return a new string
+    !> 
+    !> Version: experimental
+    interface slice
+        module procedure :: slice_string
+        module procedure :: slice_char
+    end interface slice
 
 
 contains
@@ -290,5 +300,67 @@ elemental function ends_with_string_string(string, substring) result(match)
 
     end function ends_with_string_string
 
+    !> Slices the region between the input 'first' and 'last' index (both inclusive)
+    !> of the input 'string' by taking strides of length 'stride'
+    !> Returns a new string_type object
+    elemental function slice_string(string, first, last, stride) result(sliced_string)
+        type(string_type), intent(in) :: string
+        integer, intent(in), optional :: first, last, stride
+        type(string_type) :: sliced_string
+
+        sliced_string = string_type(slice(char(string), first, last, stride))
+
+    end function slice_string
+
+    !> Slices the region between the input 'first' and 'last' index (both inclusive)
+    !> of the input 'string' by taking strides of length 'stride'
+    !> Returns a new string
+    pure function slice_char(string, first, last, stride) result(sliced_string)
+        character(len=*), intent(in) :: string
+        integer, intent(in), optional :: first, last, stride
+        integer :: first_index, last_index, stride_vector, n, i, j
+        character(len=:), allocatable :: sliced_string
+
+        if (len(string) > 0) then
+            first_index = 1
+            last_index = len(string)
+            stride_vector = 1
+
+            if (present(stride)) then
+                if (stride /= 0) then
+                    if (stride < 0) then
+                        first_index = len(string)
+                        last_index = 1
+                    end if
+                    stride_vector = stride
+                end if
+            else
+                if (present(first) .and. present(last)) then
+                    if (last < first) then
+                        stride_vector = -1
+                    end if
+                end if
+            end if
+
+            if (present(first)) then
+                first_index =  clip(first, 1, len(string))
+            end if
+            if (present(last)) then
+                last_index = clip(last, 1, len(string))
+            end if
+
+            n = int((last_index - first_index) / stride_vector)
+            allocate(character(len=max(0, n + 1)) :: sliced_string)
+
+            j = 1
+            do i = first_index, last_index, stride_vector
+                sliced_string(j:j) = string(i:i)
+                j = j + 1
+            end do
+        else
+            sliced_string = ""
+        end if
+    end function slice_char
+
 
 end module stdlib_strings

src/tests/string/test_string_functions.f90

@@ -3,6 +3,7 @@ module test_string_functions
     use stdlib_error, only : check
     use stdlib_string_type, only : string_type, assignment(=), operator(==), &
                                     to_lower, to_upper, to_title, to_sentence, reverse
+    use stdlib_strings, only: slice                                    
     implicit none
 
 contains
@@ -52,6 +53,46 @@ subroutine test_reverse_string
 
     end subroutine test_reverse_string
 
+    subroutine test_slice_string
+        type(string_type) :: test_string
+        character(len=:), allocatable :: test_char
+        test_string = "abcdefghijklmnopqrstuvwxyz"
+        test_char = "abcdefghijklmnopqrstuvwxyz"
+
+        call check(slice(test_string, 2, 16, 3) == "behkn", &
+                    'function slice failed', warn=.true.)
+        call check(slice(test_char, 15, stride=-1) == "onmlkjihgfedcba", &
+                    'function slice failed', warn=.true.)
+        call check(slice(test_string, last=22, stride=-1) == "zyxwv", &
+                    'function slice failed', warn=.true.)
+        call check(slice(test_char, 7, 2) == "gfedcb", &
+                    'function slice failed', warn=.true.)
+        call check(slice(test_string, 7, 2, 1) == "", &
+                    'function slice failed', warn=.true.)
+        call check(slice(test_char, 2, 6, -1) == "", &
+                    'function slice failed', warn=.true.)
+        call check(slice(test_string, stride=-1) == "zyxwvutsrqponmlkjihgfedcba", &
+                    'function slice failed', warn=.true.)
+        call check(slice(test_string, 7, 7, -4) == "g", &
+                    'function slice failed', warn=.true.)
+        call check(slice(test_char, 7, 7, 3) == "g", &
+                    'function slice failed', warn=.true.)
+        call check(slice(test_string, 7, 7, 3) == "g", &
+                    'function slice failed', warn=.true.)
+        call check(slice(test_char, 7, -10) == "gfedcba", &
+                    'function slice failed', warn=.true.)
+        call check(slice(test_string, 500, 22) == "zyxwv", &
+                    'function slice failed', warn=.true.)
+
+        test_string = ""
+        test_char = ""
+        call check(slice(test_string, 2, 16, 3) == "", &
+                    'function slice failed', warn=.true.)
+        call check(slice(test_char, 2, 16, 3) == "", &
+                    'function slice failed', warn=.true.)
+
+    end subroutine test_slice_string
+
 end module test_string_functions
 
 
@@ -64,5 +105,6 @@ program tester
     call test_to_title_string
     call test_to_sentence_string
     call test_reverse_string
+    call test_slice_string
 
 end program tester