added documentation for clear, constructor and fidx/bidx

Author: aman-godara

doc/specs/stdlib_stringlist.md

@@ -37,12 +37,126 @@ An instance is independent of the stringlist it is used with and hence, an index
 Experimental
 
 
+<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
+### fidx/bidx
+
+#### Description
+
+`fidx`: Returns an instance which represents forward index `idx`.  
+`bidx`: Returns an instance which represents backward index `idx`.
+
+#### Syntax
+
+For fidx: `res = [[stdlib_stringlist(module):fidx()]] (idx)`  
+For bidx: `res = [[stdlib_stringlist(module):bidx()]] (idx)`
+
+#### Status
+
+Experimental.
+
+#### Class
+
+Pure function.
+
+#### Argument
+
+- `idx`: integer.
+  This argument is intent(in).
+
+#### Result value
+
+The result is of type `stringlist_index_type`.
+
+#### Example
+
+```fortran
+program demo_fidx_bidx
+  use stdlib_stringlist, only: stringlist_type, stringlist_index_type, fidx, bidx
+  implicit none
+
+  type(stringlist_type) :: stringlist
+  type(stringlist_index_type) :: index
+
+  index = fidx(1)
+
+  !> inserting 2 elements to the stringlist
+  call stringlist%insert_at( fidx(1), "Element No. one" )
+  call stringlist%insert_at( index, "Element No. two" )
+    ! stringlist <-- {"Element No. two", "Element No. one"}
+
+  index = bidx(3)
+
+  !> inserting 2 elements to the stringlist
+  call stringlist%insert_at( bidx(1), "Element No. three" )
+  call stringlist%insert_at( index, "Element No. four" )
+    ! stringlist <-- {"Element No. two", "Element No. four", 
+    "Element No. one", "Element No. three"}
+
+end program demo_fidx_bidx
+```
+
+<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
+### Constructor for stringlist
+
+#### Description
+
+No arguments given: Initializes an empty stringlist(a list containing no elements in it).
+
+With argument: Initializes a stringlist equivalent to the input array `array` i.e. a stringlist containing all elements of the input array `array` in the same order.
+
+#### Syntax
+
+No arguments given: `res = [[stdlib_stringlist(module):stringlist_type(interface)]] ()`
+With argument: `res = [[stdlib_stringlist(module):stringlist_type(interface)]] (array)`
+
+#### Status
+
+Experimental
+
+#### Class
+
+Pure function.
+
+#### Argument
+
+No arguments.
+
+With argument: - `array`: array of Character scalar or array of [[stdlib_string_type(module):string_type(type)]].  
+                This argument is intent(in).
+
+#### Result value
+
+The result is an instance of type `stringlist_type`.
+
+#### Example
+
+```fortran
+program demo_constructor
+  use stdlib_stringlist, only: stringlist_type
+  use stdlib_string_type, only: string_type
+  implicit none
+
+  type(stringlist_type) :: stringlist
+
+  stringlist = stringlist_type()
+    ! stringlist <-- { } (empty stringlist)
+
+  stringlist = stringlist_type(["#1", "#2", "#3"])
+    ! stringlist <-- {"#1", "#2", "#3"}
+
+  stringlist = stringlist_type([string_type("#1"), string_type("#2")])
+    ! stringlist <-- {"#1", "#2"}
+
+end program demo_constructor
+```
+
+
 <!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
 ### insert_at
 
 #### Description
 
-Inserts the string `string` at the index `idx` such that after insertion is done the newly added element is at index `idx`.
+Inserts the string `string` _AT_ the index `idx`, so that the newly added element is present at index `idx` after insertion. Inserting an element _AT_ index beyond `length + 1` inserts the element _AT_ `list_tail`, and likewise inserting _AT_ a non-positive index inserts the element _AT_ `list_head`.
 
 #### Syntax
 
@@ -72,7 +186,7 @@ No result.
 
 ```fortran
 program demo_insert_at
-  use stdlib_stringlist, only: stringlist_type, insert_at, stringlist_index_type, fidx, bidx
+  use stdlib_stringlist, only: stringlist_type, stringlist_index_type, fidx, bidx
   use stdlib_string_type, only: string_type
   implicit none
 
@@ -102,7 +216,7 @@ end program demo_insert_at
 
 #### Description
 
-Returns the string present currently at the index `idx` in the given stringlist. If `idx` is out of bounds an empty string is returned.
+Returns the string present currently at the index `idx` in a stringlist. If index `idx` is out of bounds, then an empty string is returned.
 
 #### Syntax
 
@@ -129,14 +243,14 @@ The result is a string of type `string_type`.
 
 ```fortran
 program demo_get
-  use stdlib_stringlist, only: stringlist_type, insert_at, fidx, get
+  use stdlib_stringlist, only: stringlist_type, fidx, bidx
   use stdlib_string_type, only: string_type
   implicit none
 
   type(stringlist_type) :: stringlist
   type(string_type)     :: output
 
-  !> adding 4 elements to the stringlist
+  !> inserting 4 elements to the stringlist
   call stringlist%insert_at( fidx(1), "Element No. one" )
   call stringlist%insert_at( fidx(1), "Element No. two" )
   call stringlist%insert_at( fidx(1), "Element No. three" )
@@ -164,7 +278,7 @@ end program demo_get
 
 #### Description
 
-Returns the number of elements present in the stringlist.
+Returns the number of elements present currently in the stringlist.
 
 #### Syntax
 
@@ -190,7 +304,7 @@ The result is of type `integer`.
 
 ```fortran
 program demo_len
-  use stdlib_stringlist, only: stringlist_type, insert_at, bidx, len
+  use stdlib_stringlist, only: stringlist_type, bidx
   implicit none
 
   type(stringlist_type) :: stringlist
@@ -199,13 +313,65 @@ program demo_len
   output = stringlist%len()
     ! output <-- 0
 
-  !> adding 2 elements to the stringlist
+  !> inserting 2 elements to the stringlist
   call stringlist%insert_at( bidx(1), "Element No. one" )
   call stringlist%insert_at( bidx(1), "Element No. two" )
     ! stringlist <-- {"Element No. one", "Element No. two"}
 
-  output = stringlist%len()
-    ! output <-- 2
+  print'(a)', stringlist%len()
+    ! 2
 
 end program demo_len
 ```
+
+
+<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
+### clear
+
+#### Description
+
+Removes all elements from a stringlist.
+
+#### Syntax
+
+`call [[stdlib_stringlist(module):stringlist_type(type)]]%[[stdlib_stringlist(module):clear()]] ()`
+
+#### Status
+
+Experimental.
+
+#### Class
+
+Pure subroutine.
+
+#### Argument
+
+No arguments.
+
+#### Result value
+
+No result.
+
+#### Example
+
+```fortran
+program demo_clear
+  use stdlib_stringlist, only: stringlist_type, fidx
+  implicit none
+
+  type(stringlist_type) :: stringlist
+
+  !> inserting 2 elements to the stringlist
+  call stringlist%insert_at( fidx(1), "Element No. one" )
+  call stringlist%insert_at( fidx(1), "Element No. two" )
+    ! stringlist <-- {"Element No. two", "Element No. one"}
+
+  call stringlist%clear()
+    ! stringlist <-- { } (empty stringlist)
+
+  !> inserting 1 element to the stringlist
+  call stringlist%insert_at( fidx(1), "Element No. one" )
+    ! stringlist <-- {"Element No. one"}
+
+end program demo_clear
+```

src/stdlib_stringlist.f90

@@ -3,7 +3,7 @@
 !     The strings may have arbitrary lengths, not necessarily the same
 !
 !     insert AT:      Inserts an element BEFORE the element present currently at the asked index
-!                       for forward indexes, otherwise
+!                       for forward indexes
 !                     Inserts an element AFTER the element present currently at the asked index
 !                       for backward indexes
 !                     In other words, after insertion the element will be present at the asked index
@@ -17,7 +17,6 @@
 module stdlib_stringlist
     use stdlib_string_type, only: string_type, operator(/=) !, move
     use stdlib_math, only: clip
-    ! use stdlib_optval, only: optval
     implicit none
     private
 
@@ -163,14 +162,14 @@ end function new_stringlist
 
     !> Constructor to convert chararray to stringlist
     !> Returns a new instance of type stringlist
-    pure function new_stringlist_carray( carray )
-        character(len=*), dimension(:), intent(in)      :: carray
+    pure function new_stringlist_carray( array )
+        character(len=*), dimension(:), intent(in)      :: array
         type(stringlist_type)                           :: new_stringlist_carray
-        type(string_type), dimension( size(carray) )    :: sarray
+        type(string_type), dimension( size(array) )     :: sarray
         integer                                         :: i
 
-        do i = 1, size(carray)
-            sarray(i) = string_type( carray(i) )
+        do i = 1, size(array)
+            sarray(i) = string_type( array(i) )
         end do
 
         new_stringlist_carray = stringlist_type( sarray )
@@ -179,11 +178,11 @@ end function new_stringlist_carray
 
     !> Constructor to convert stringarray to stringlist
     !> Returns a new instance of type stringlist
-    pure function new_stringlist_sarray( sarray )
-        type(string_type), dimension(:), intent(in)     :: sarray
+    pure function new_stringlist_sarray( array )
+        type(string_type), dimension(:), intent(in)     :: array
         type(stringlist_type)                           :: new_stringlist_sarray
 
-        new_stringlist_sarray = stringlist_type( size(sarray), sarray )
+        new_stringlist_sarray = stringlist_type( size(array), array )
 
     end function new_stringlist_sarray
 
@@ -612,7 +611,6 @@ subroutine insert_before_empty_positions( list, idxn, positions )
         if (positions > 0) then
 
             idxn    = clip( idxn, 1, list%len() + 1 )
-            ! Matlab's infinitely expandable list (Ivan's comment)??
             old_len = list%len()
             new_len = old_len + positions