Merge branch 'master' into revival_string_list

Author: aman-godara

CONTRIBUTORS.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019 Fortran stdlib developers
+Copyright (c) 2019-2021 stdlib contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

LICENSE

@@ -98,7 +98,7 @@ The following combinations are known to work, but they are not tested in the CI:
 
 Name | Version | Platform | Architecture
 --- | --- | --- | ---
-GCC Fortran (MinGW) | 8.4.0, 9.3.0, 10.2.0 | Windows 10 | x86_64, i686
+GCC Fortran (MinGW) | 9.3.0, 10.2.0, 11.2.0 | Windows 10 | x86_64, i686
 
 We try to test as many available compilers and platforms as possible.
 A list of tested compilers which are currently not working and the respective issue are listed below.

README.md

@@ -212,42 +212,4 @@ program demo_reverse
     implicit none
     print'(a)', reverse("Hello, World!") ! returns "!dlroW ,olleH"
 end program demo_reverse
-```
-
-### `to_string`
-
-#### Status
-
-Experimental
-
-#### Description
-
-Create a character string representing the value of the provided variable.
-
-#### Syntax
-
-`res = [[stdlib_ascii(module):to_string(interface)]] (string)`
-
-#### Class
-
-Pure function.
-
-#### Argument
-
-`val`: shall be an intrinsic integer or logical type. It is an `intent(in)` argument.
-
-#### Result value
-
-The result is an intrinsic character type.
-
-#### Example
-
-```fortran
-program demo_string_value
-    use stdlib_ascii, only : to_string
-    implicit none
-    print'(a)', to_string(-3) ! returns "-3"
-    print'(a)', to_string(.true.) ! returns "T"
-    print'(a)', to_string(42) ! returns "42"
-end program demo_string_value
-```
+```

doc/specs/stdlib_ascii.md

@@ -101,30 +101,58 @@ end program demo_diag5
 
 Experimental
 
+### Class
+
+Pure function.
+
 ### Description
 
-Construct the identity matrix
+Construct the identity matrix.
 
 ### Syntax
 
-`I = [[stdlib_linalg(module):eye(function)]](n)`
+`I = [[stdlib_linalg(module):eye(function)]](dim1 [, dim2])`
 
 ### Arguments
 
-`n`: Shall be a scalar of default type `integer`. 
+`dim1`: Shall be a scalar of default type `integer`.
+This is an `intent(in)` argument. 
+
+`dim2`: Shall be a scalar of default type `integer`.
+This is an `intent(in)` and `optional` argument. 
 
 ### Return value
 
-Returns the identity matrix, i.e. a square matrix with ones on the main diagonal and zeros elsewhere. The return value is of type `integer(int8)`.
+Return the identity matrix, i.e. a matrix with ones on the main diagonal and zeros elsewhere. The return value is of type `integer(int8)`.
+The use of `int8` was suggested to save storage.
+
+#### Warning
+
+Since the result of `eye` is of `integer(int8)` type, one should be careful about using it in arithmetic expressions. For example:
+```fortran
+real :: A(:,:)
+!> Be careful
+A = eye(2,2)/2     !! A == 0.0
+!> Recommend
+A = eye(2,2)/2.0   !! A == diag([0.5, 0.5])
+```
 
 ### Example
 
 ```fortran
 program demo_eye1
     use stdlib_linalg, only: eye
     implicit none
+    integer :: i(2,2)
     real :: a(3,3)
-    A = eye(3)
+    real :: b(2,3)  !! Matrix is non-square.
+    complex :: c(2,2)
+    I = eye(2)              !! [1,0; 0,1]
+    A = eye(3)              !! [1.0,0.0,0.0; 0.0,1.0,0.0; 0.0,0.0,1.0]
+    A = eye(3,3)            !! [1.0,0.0,0.0; 0.0,1.0,0.0; 0.0,0.0,1.0]
+    B = eye(2,3)            !! [1.0,0.0,0.0; 0.0,1.0,0.0]
+    C = eye(2,2)            !! [(1.0,0.0),(0.0,0.0); (0.0,0.0),(1.0,0.0)]
+    C = (1.0,1.0)*eye(2,2)  !! [(1.0,1.0),(0.0,0.0); (0.0,0.0),(1.0,1.0)]
 end program demo_eye1
 ```
 

doc/specs/stdlib_linalg.md

@@ -275,3 +275,71 @@ program demo_logspace_rstart_cbase
 
 end program demo_logspace_rstart_cbase
 ```
+## `arange`
+
+### Status
+
+Experimental
+
+### Class
+
+Pure function.
+
+### Description
+
+Creates a one-dimensional `array` of the `integer/real` type with fixed-spaced values of given spacing, within a given interval.
+
+### Syntax
+
+`result = [[stdlib_math(module):arange(interface)]](start [, end, step])`
+
+### Arguments
+
+All arguments should be the same type and kind.
+
+`start`: Shall be an `integer/real` scalar.
+This is an `intent(in)` argument.  
+The default `start` value is `1`.
+
+`end`: Shall be an `integer/real` scalar.
+This is an `intent(in)` and `optional` argument.  
+The default `end` value is the inputted `start` value.
+
+`step`: Shall be an `integer/real` scalar and large than `0`. 
+This is an `intent(in)` and `optional` argument.   
+The default `step` value is `1`.
+
+#### Warning
+If `step = 0`, the `step` argument will be corrected to `1/1.0` by the internal process of the `arange` function.   
+If `step < 0`, the `step` argument will be corrected to `abs(step)` by the internal process of the `arange` function. 
+
+### Return value
+
+Returns a one-dimensional `array` of fixed-spaced values.
+
+For `integer` type arguments, the length of the result vector is `(end - start)/step + 1`.  
+For `real` type arguments, the length of the result vector is `floor((end - start)/step) + 1`.
+
+### Example
+
+```fortran
+program demo_math_arange
+    use stdlib_math, only: arange
+
+    print *, arange(3)                 !! [1,2,3]
+    print *, arange(-1)                !! [1,0,-1]
+    print *, arange(0,2)               !! [0,1,2]
+    print *, arange(1,-1)              !! [1,0,-1]
+    print *, arange(0, 2, 2)           !! [0,2]
+
+    print *, arange(3.0)               !! [1.0,2.0,3.0]
+    print *, arange(0.0,5.0)           !! [0.0,1.0,2.0,3.0,4.0,5.0]
+    print *, arange(0.0,6.0,2.5)       !! [0.0,2.5,5.0]
+
+    print *, (1.0,1.0)*arange(3)       !! [(1.0,1.0),(2.0,2.0),[3.0,3.0]]
+
+    print *, arange(0.0,2.0,-2.0)      !! [0.0,2.0].     Not recommended: `step` argument is negative!
+    print *, arange(0.0,2.0,0.0)       !! [0.0,1.0,2.0]. Not recommended: `step` argument is zero!
+
+end program demo_math_arange
+```

doc/specs/stdlib_math.md

@@ -538,3 +538,72 @@ program demo_count
 
 end program demo_count
 ```
+
+<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
+### `to_string`
+
+#### Description
+
+Format or transfer a `integer/real/complex/logical` scalar as a string.  
+Input a wrong `format` that cause the internal-IO to fail, the result value is a string of `[*]`.
+
+#### Syntax
+
+`string = [[stdlib_strings(module):to_string(interface)]] (value [, format])`
+
+#### Status
+
+Experimental
+
+#### Class
+
+Pure function.
+
+#### Argument
+
+- `value`: Shall be an `integer/real/complex/logical` scalar.
+  This is an `intent(in)` argument.
+- `format`: Shall be a `character(len=*)` scalar like `'(F6.2)'` or just `'F6.2'`.
+  This is an `intent(in)` and `optional` argument.  
+  Contains the edit descriptor to format `value` into a string, for example `'(F6.2)'` or `'(f6.2)'`. 
+  `to_string` will automatically enclose `format` in a set of parentheses, so passing `F6.2` or `f6.2` as `format` is possible as well.
+  
+#### Result value
+
+The result is an `allocatable` length `character` scalar with up to `128` cached `character` length.
+
+#### Example
+
+```fortran
+program demo_to_string
+    use stdlib_strings, only: to_string
+
+    !> Example for `complex` type
+    print *, to_string((1, 1))              !! "(1.00000000,1.00000000)"
+    print *, to_string((1, 1), '(F6.2)')    !! "(  1.00,  1.00)"
+    print *, to_string((1000, 1), '(ES0.2)'), to_string((1000, 1), '(SP,F6.3)')     
+                    !! "(1.00E+3,1.00)""(******,+1.000)"
+                    !! Too narrow formatter for real number
+                    !! Normal demonstration(`******` from Fortran Standard)
+
+    !> Example for `integer` type
+    print *, to_string(-3)                  !! "-3"
+    print *, to_string(42, '(I4)')          !! "  42"
+    print *, to_string(1, '(I0.4)'), to_string(2, '(B4)')           !! "0001""  10"  
+
+    !> Example for `real` type
+    print *, to_string(1.)                  !! "1.00000000"
+    print *, to_string(1., '(F6.2)')        !! "  1.00" 
+    print *, to_string(1., 'F6.2')          !! "  1.00" 
+    print *, to_string(1., '(SP,ES9.2)'), to_string(1, '(F7.3)')    !! "+1.00E+00""[*]"
+                    !! 1 wrong demonstration (`[*]` from `to_string`)
+
+    !> Example for `logical` type
+    print *, to_string(.true.)              !! "T"
+    print *, to_string(.true., '(L2)')      !! " T"
+    print *, to_string(.true., 'L2')        !! " T"
+    print *, to_string(.false., '(I5)')     !! "[*]"
+                    !! 1 wrong demonstrations(`[*]` from `to_string`)
+
+end program demo_to_string
+```

doc/specs/stdlib_strings.md

@@ -32,7 +32,11 @@ set(fppFiles
     stdlib_math.fypp
     stdlib_math_linspace.fypp
     stdlib_math_logspace.fypp
+    stdlib_math_arange.fypp
     stdlib_string_type.fypp
+    stdlib_string_type_constructor.fypp
+    stdlib_strings_to_string.fypp
+    stdlib_strings.fypp
 )
 
 
@@ -51,7 +55,6 @@ set(SRC
     stdlib_error.f90
     stdlib_kinds.f90
     stdlib_logger.f90
-    stdlib_strings.f90
     stdlib_system.F90
     stdlib_specialfunctions.f90
     stdlib_specialfunctions_legendre.f90