Merge branch 'master' into add_close

Author: zoziha

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

@@ -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

@@ -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

@@ -35,6 +35,9 @@ set(fppFiles
     stdlib_math_arange.fypp
     stdlib_math_is_close.fypp
     stdlib_string_type.fypp
+    stdlib_string_type_constructor.fypp
+    stdlib_strings_to_string.fypp
+    stdlib_strings.fypp
 )
 
 
@@ -53,7 +56,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

src/CMakeLists.txt

@@ -1,4 +1,4 @@
-SRCFYPP =\
+SRCFYPP = \
         stdlib_ascii.fypp \
         stdlib_bitsets_64.fypp \
         stdlib_bitsets_large.fypp \
@@ -27,11 +27,14 @@ SRCFYPP =\
         stdlib_stats_moment_scalar.fypp \
         stdlib_stats_var.fypp \
         stdlib_math.fypp \
-		stdlib_math_linspace.fypp \
-		stdlib_math_logspace.fypp \
+        stdlib_math_linspace.fypp \
+        stdlib_math_logspace.fypp \
         stdlib_math_is_close.fypp \
         stdlib_stats_distribution_PRNG.fypp \
-        stdlib_string_type.fypp
+        stdlib_string_type.fypp \
+        stdlib_string_type_constructor.fypp \
+        stdlib_strings.fypp \
+        stdlib_strings_to_string.fypp
 
 SRC = f18estop.f90 \
       stdlib_error.f90 \
@@ -41,7 +44,6 @@ SRC = f18estop.f90 \
       stdlib_kinds.f90 \
       stdlib_logger.f90 \
       stdlib_quadrature_gauss.f90 \
-      stdlib_strings.f90 \
       $(SRCGEN)
 
 LIB = libstdlib.a
@@ -78,85 +80,89 @@ stdlib_error.o: stdlib_optval.o
 stdlib_specialfunctions.o: stdlib_kinds.o
 stdlib_specialfunctions_legendre.o: stdlib_kinds.o stdlib_specialfunctions.o
 stdlib_io.o: \
-	stdlib_ascii.o \
-	stdlib_error.o \
-	stdlib_optval.o \
-	stdlib_kinds.o
+    stdlib_ascii.o \
+    stdlib_error.o \
+    stdlib_optval.o \
+    stdlib_kinds.o \
+    stdlib_ascii.o
 stdlib_linalg.o: \
-	stdlib_kinds.o
+    stdlib_kinds.o
 stdlib_linalg_diag.o: \
-	stdlib_linalg.o \
-	stdlib_kinds.o
+    stdlib_linalg.o \
+    stdlib_kinds.o
 stdlib_logger.o: stdlib_ascii.o stdlib_optval.o
 stdlib_optval.o: stdlib_kinds.o
 stdlib_quadrature.o: stdlib_kinds.o
-
 stdlib_quadrature_gauss.o: stdlib_kinds.o stdlib_quadrature.o
-
 stdlib_quadrature_simps.o: \
-	stdlib_quadrature.o \
-	stdlib_error.o \
-	stdlib_kinds.o
+    stdlib_quadrature.o \
+    stdlib_error.o \
+    stdlib_kinds.o
 stdlib_quadrature_trapz.o: \
-	stdlib_quadrature.o \
-	stdlib_error.o \
-	stdlib_kinds.o
+    stdlib_quadrature.o \
+    stdlib_error.o \
+    stdlib_kinds.o
 stdlib_sorting.o: \
-	stdlib_kinds.o \
-	stdlib_string_type.o
+    stdlib_kinds.o \
+    stdlib_string_type.o
 stdlib_sorting_ord_sort.o: \
-	stdlib_sorting.o
+    stdlib_sorting.o
 stdlib_sorting_sort.o: \
-	stdlib_sorting.o
+    stdlib_sorting.o
 stdlib_sorting_sort_index.o: \
-	stdlib_sorting.o
+    stdlib_sorting.o
 stdlib_stats.o: \
-	stdlib_kinds.o
+    stdlib_kinds.o
 stdlib_stats_corr.o: \
-	stdlib_optval.o \
-	stdlib_kinds.o \
-	stdlib_stats.o
+    stdlib_optval.o \
+    stdlib_kinds.o \
+    stdlib_stats.o
 stdlib_stats_cov.o: \
-	stdlib_optval.o \
-	stdlib_kinds.o \
-	stdlib_stats.o
+    stdlib_optval.o \
+    stdlib_kinds.o \
+    stdlib_stats.o
 stdlib_stats_mean.o: \
-	stdlib_optval.o \
-	stdlib_kinds.o \
-	stdlib_stats.o
+    stdlib_optval.o \
+    stdlib_kinds.o \
+    stdlib_stats.o
 stdlib_stats_median.o: \
-	stdlib_optval.o \
-	stdlib_kinds.o \
-	stdlib_sorting.o \
-	stdlib_stats.o
+    stdlib_optval.o \
+    stdlib_kinds.o \
+    stdlib_sorting.o \
+    stdlib_stats.o
 stdlib_stats_moment.o: \
-	stdlib_optval.o \
-	stdlib_kinds.o \
-	stdlib_stats.o
+    stdlib_optval.o \
+    stdlib_kinds.o \
+    stdlib_stats.o
 stdlib_stats_moment_all.o: \
-	stdlib_stats_moment.o
+    stdlib_stats_moment.o
 stdlib_stats_moment_mask.o: \
-	stdlib_stats_moment.o
+    stdlib_stats_moment.o
 stdlib_stats_moment_scalar.o: \
-	stdlib_stats_moment.o
+    stdlib_stats_moment.o
 stdlib_stats_var.o: \
-	stdlib_optval.o \
-	stdlib_kinds.o \
-	stdlib_stats.o
+    stdlib_optval.o \
+    stdlib_kinds.o \
+    stdlib_stats.o
 stdlib_stats_distribution_PRNG.o: \
-        stdlib_kinds.o \
-	stdlib_error.o
+    stdlib_kinds.o \
+    stdlib_error.o
 stdlib_string_type.o: stdlib_ascii.o \
     stdlib_kinds.o
+stdlib_string_type_constructor.o: stdlib_string_type.o \
+    stdlib_strings_to_string.o \
+    stdlib_strings.o
 stdlib_strings.o: stdlib_ascii.o \
     stdlib_string_type.o \
-	stdlib_optval.o
+    stdlib_optval.o \
+    stdlib_kinds.o
+stdlib_strings_to_string.o: stdlib_strings.o
 stdlib_math.o: stdlib_kinds.o \
     stdlib_optval.o
 stdlib_math_linspace.o: \
-	stdlib_math.o
+    stdlib_math.o
 stdlib_math_logspace.o: \
-	stdlib_math_linspace.o
+    stdlib_math_linspace.o
 stdlib_math_arange.o: \
     stdlib_math.o
 stdlib_linalg_outer_product.o: stdlib_linalg.o