[stdlib_io] add disp(display variable values formatted).

doc/specs/stdlib_io.md

@@ -131,3 +131,126 @@ program demo_savetxt
     call savetxt('example.dat', x) 
 end program demo_savetxt
 ```
+
+## `disp` - display the value of the variable
+
+### Status
+
+Experimental
+
+### Class
+
+Impure subroutine.
+
+### Description
+
+Outputs a `logical/integer/real/complex/character/string_type` scalar,  
+or `logical/integer/real/complex/string_type` and rank-1/rank-2 array to the screen or a file `unit`.
+
+### Syntax
+
+`call [[stdlib_io(module):disp(interface)]]( [x, header, unit, brief, format, width, sep] )`  
+
+### Arguments
+
+- `x`: Shall be a `logical/integer/real/complex/character(len=*)/string_type` scalar or `logical/integer/real/complex/string_type` and rank-1/rank-2 array.
+This argument is `intent(in)` and `optional`.
+
+- `header`: Shall be a `character(len=*)` scalar. 
+This argument is `intent(in)` and `optional`.
+
+- `unit`: Shall be an `integer` scalar, linked to an IO stream.
+This argument is `intent(in)` and `optional`.<br>
+The default value is `output_unit` from `iso_fortran_env` module.
+
+- `brief`: Shall be a `logical` scalar, controls an abridged version of the `x` array to be outputted.
+This argument is `intent(in)` and `optional`.<br>
+The default value is `.false.`
+
+- `format`: Shall be a `character(len=*)` scalar.
+This argument is `intent(in)` and `optional`.<br>
+The default value is `g0.4`.
+
+- `width`: Shall be an `integer` scalar, controls the outputted maximum width (`>=80`).
+This argument is `intent(in)` and `optional`.<br>
+The default value is `80`.
+
+- `sep`: Shall be a `character(len=*)` scalar, separator.
+This argument is `intent(in)` and `optional`.<br>
+The default value is "&ensp;&ensp;", two spaces.
+
+### Output
+
+The result is to print `header` and `x` on the screen (or another output `unit/file`) in this order.<br>
+If `disp` is not passed any arguments, a blank line will be printed.
+
+### Example
+
+```fortran
+program test_io_disp
+
+    use stdlib_io, only: disp
+
+    real    :: r(2, 3)
+    complex :: c(2, 3), c_3d(2, 100, 20)
+    integer :: i(2, 3)
+    logical :: l(10, 10)
+
+    r = 1.; c = 1.; c_3d = 2.; i = 1; l = .true.
+    c_3d(1,3,1) = (1000, 0.001)
+
+    call disp('string', header='disp(string):')
+    call disp('It is a note.')
+    call disp()
+    call disp(r, header='disp(r):')
+    call disp(r(1,:), header='disp(r(1,:))', format="f6.2")
+    call disp(c, header='disp(c):')
+    call disp(i, header='disp(i):', sep=",")
+    call disp(l, header='disp(l):', brief=.true.)
+    call disp(c_3d(:,3,1:10), header='disp(c_3d(:,3,1:10)):', width=100)
+    call disp(c_3d(2,:,:), header='disp(c_3d(2,:,:)):', brief=.true.)
+
+end program test_io_disp
+```
+**Results:**
+```fortran
+disp(string):
+string
+It is a note.
+
+disp(r):
+[matrix size: 2×3]
+1.000  1.000  1.000
+1.000  1.000  1.000
+disp(r(1,:))
+[vector size: 3]
+  1.00    1.00    1.00
+disp(c):
+[matrix size: 2×3]
+(1.000,0.000)  (1.000,0.000)  (1.000,0.000)
+(1.000,0.000)  (1.000,0.000)  (1.000,0.000)
+disp(i):
+[matrix size: 2×3]
+1, 1, 1,
+1, 1, 1,
+disp(l):
+[matrix size: 10×10]  
+T   T   T   ..  T
+T   T   T   ..  T
+T   T   T   ..  T
+:   :   :   :   :
+T   T   T   ..  T
+disp(c_3d(:,3,1:10)):
+[matrix size: 2×10]
+(1000.,0.1000E-2)  (2.000,0.000)      (2.000,0.000)      (2.000,0.000)      (2.000,0.000)           &
+(2.000,0.000)      (2.000,0.000)      (2.000,0.000)      (2.000,0.000)      (2.000,0.000)
+(2.000,0.000)      (2.000,0.000)      (2.000,0.000)      (2.000,0.000)      (2.000,0.000)           &
+(2.000,0.000)      (2.000,0.000)      (2.000,0.000)      (2.000,0.000)      (2.000,0.000)
+disp(c_3d(2,:,:)):
+[matrix size: 100×20]
+(2.000,0.000)  (2.000,0.000)  (2.000,0.000)  ..             (2.000,0.000)    
+(2.000,0.000)  (2.000,0.000)  (2.000,0.000)  ..             (2.000,0.000)    
+(2.000,0.000)  (2.000,0.000)  (2.000,0.000)  ..             (2.000,0.000)
+:              :              :              :              :
+(2.000,0.000)  (2.000,0.000)  (2.000,0.000)  ..             (2.000,0.000)
+```

src/CMakeLists.txt

@@ -7,6 +7,7 @@ set(fppFiles
     stdlib_bitsets_64.fypp
     stdlib_bitsets_large.fypp
     stdlib_io.fypp
+    stdlib_io_disp.fypp
     stdlib_linalg.fypp
     stdlib_linalg_diag.fypp
     stdlib_linalg_outer_product.fypp

src/Makefile.manual

@@ -4,6 +4,7 @@ SRCFYPP = \
         stdlib_bitsets_large.fypp \
         stdlib_bitsets.fypp \
         stdlib_io.fypp \
+        stdlib_io_disp.fypp \
         stdlib_linalg.fypp \
         stdlib_linalg_diag.fypp \
         stdlib_linalg_outer_product.fypp \
@@ -29,8 +30,8 @@ SRCFYPP = \
         stdlib_stats_distribution_uniform.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_string_type.fypp \
         stdlib_string_type_constructor.fypp \
         stdlib_strings.fypp \
@@ -86,7 +87,12 @@ stdlib_io.o: \
     stdlib_error.o \
     stdlib_optval.o \
     stdlib_kinds.o \
-    stdlib_ascii.o
+    stdlib_ascii.o \
+    stdlib_string_type.o
+stdlib_io_disp.o: \
+    stdlib_strings.o \
+    stdlib_string_type.o \
+    stdlib_io.o
 stdlib_linalg.o: \
     stdlib_kinds.o
 stdlib_linalg_diag.o: \

src/stdlib_io.fypp

@@ -7,14 +7,15 @@ module stdlib_io
   !! ([Specification](../page/specs/stdlib_io.html))
 
   use stdlib_kinds, only: sp, dp, qp, &
-      int8, int16, int32, int64
+      int8, int16, int32, int64, lk, c_bool
   use stdlib_error, only: error_stop
   use stdlib_optval, only: optval
   use stdlib_ascii, only: is_blank
+  use stdlib_string_type, only: string_type
   implicit none
   private
   ! Public API
-  public :: loadtxt, savetxt, open
+  public :: loadtxt, savetxt, open, disp
 
   ! Private API that is exposed so that we can test it in tests
   public :: parse_mode
@@ -28,6 +29,36 @@ module stdlib_io
     FMT_COMPLEX_SP = '(*(es15.8e2,1x,es15.8e2))', &
     FMT_COMPLEX_DP = '(*(es24.16e3,1x,es24.16e3))', &
     FMT_COMPLEX_QP = '(*(es44.35e4,1x,es44.35e4))'
+
+  !> version: experimental
+  !>
+  !> Display a scalar, vector or matrix formatted.
+  !> ([Specification](../page/specs/stdlib_io.html#display-the-value-of-the-variable))
+  interface disp
+      #:set ALL_KINDS_TYPES = REAL_KINDS_TYPES + CMPLX_KINDS_TYPES + INT_KINDS_TYPES + LOG_KINDS_TYPES + STRING_KINDS_TYPES
+      module subroutine disp_char(x, header, unit, brief, format, width, sep)
+          character(*), intent(in), optional :: x
+          character(len=*), intent(in), optional :: header
+          integer, intent(in), optional :: unit
+          logical, intent(in), optional :: brief
+          character(len=*), intent(in), optional :: format
+          integer, intent(in), optional :: width
+          character(len=*), intent(in), optional :: sep
+      end subroutine disp_char
+      #:for r1 in range(0, 3)
+      #:for k1, t1 in ALL_KINDS_TYPES
+      module subroutine disp_${r1}$_${t1[0]}$${k1}$(x, header, unit, brief, format, width, sep)
+          ${t1}$, intent(in) :: x${ranksuffix(r1)}$
+          character(len=*), intent(in), optional :: header
+          integer, intent(in), optional :: unit
+          logical, intent(in), optional :: brief
+          character(len=*), intent(in), optional :: format
+          integer, intent(in), optional :: width
+          character(len=*), intent(in), optional :: sep
+      end subroutine disp_${r1}$_${t1[0]}$${k1}$
+      #:endfor
+      #:endfor
+  end interface disp
 
   interface loadtxt
     !! version: experimental