[stdlib_io] disp(display your data)

doc/specs/stdlib_io.md

@@ -131,3 +131,121 @@ program demo_savetxt
     call savetxt('example.dat', x) 
 end program demo_savetxt
 ```
+
+## `disp` - display your data to the screen (or another output unit)
+
+### Status
+
+Experimental
+
+### Description
+Display any type of scalar, vector or matrix.
+
+Make good use of similar to the following usage, can help you understand the data information in the `array`.
+```fortran
+call disp( A(i, j, 2, :, 1:10) [, unit, header, brief] )    !! `i, j, ...` can be determined by `do` loop.
+```
+
+Generally, except for `complex` type, any other type of scalar or single element of the `array` will be printed out with a width of 12 characters and a space separator.  
+For `complex` type, scalar or single element of the `array` will be printed out with a width of 25 characters and a space separator.
+
+### Syntax
+
+General API:
+`call [[stdlib_io(module):disp(interface)]](value [, unit, header, brief])`
+
+For null:
+`call [[stdlib_io(module):disp(interface)]]()`  
+
+### Arguments
+
+`value`: Shall be any type of scalar, vector or matrix.
+    This is an `intent(in)` argument.
+
+`unit`: Shall be an `integer` scalar link to an IO stream.
+    This is an `intent(in)` and `optional` argument.
+
+`header`: Shall be a scalar of type `character` with any length (usually used to comment data information).
+    This is an `intent(in)` and `optional` argument.
+
+`brief`: Shall be an `logical` scalar, controlling an abridged version of the `value` object is printed.
+    This is an `intent(in)` and `optional` argument.
+
+### Output
+
+The result is to print `header` and `value` on the screen (or another output unit) in this order.  
+If `value` is a `array` type, the dimension length information of the `array` will also be outputted.
+
+### Example
+
+```fortran
+program test_io_disp
+
+    use :: stdlib_io, only: disp
+    implicit none
+    real(8) :: 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.
+    r(1, 1) = -1.e-11
+    r(1, 2) = -1.e10
+    c(2, 2) = (-1.e10,-1.e10)
+    c_3d(1,3,1) = (1000, 0.001)
+    c_3d(1,3,2) = (1.e4, 100.)
+    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,:))')
+    call disp(c, header='disp(c):')
+    call disp(i, header='disp(i):')
+    call disp(l, header='disp(l):', brief=.true.)
+
+    call disp(c_3d(:,:,3), header='disp(c_3d(:,:,3)):', brief=.true.)
+    call disp(c_3d(2,:,:), header='disp(c_3d(2,:,:)):', brief=.true.)
+
+end program test_io_disp
+```
+**Result:**
+```fortran
+ disp(string):
+ string
+ It is a note.
+
+ disp(r):
+ [matrix size: 2×3]
+ -0.1000E-10  -0.1000E+11    1.000
+   1.000        1.000        1.000
+ disp(r(1,:))
+ [vector size: 3]
+ -0.1000E-10  -0.1000E+11    1.000
+ disp(c):
+ [matrix size: 2×3]
+            (1.000,0.000)             (1.000,0.000)             (1.000,0.000)
+            (1.000,0.000) (-0.1000E+11,-0.1000E+11)             (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)):
+ [matrix size: 2×100]
+            (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) 
+```

doc/specs/stdlib_strings.md

@@ -384,6 +384,114 @@ end program demo_replace_all
 ```
 
 
+<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
+### `padl`
+
+#### Description
+
+Returns a string of length `output_length` left padded with `pad_with` character if it is provided, otherwise with `" "` (1 whitespace).  
+If `output_length` is less than or equal to the length of `string`, padding is not performed.
+
+#### Syntax
+
+`string = [[stdlib_strings(module):padl(interface)]] (string, output_length [, pad_with])`
+
+#### Status
+
+Experimental
+
+#### Class
+
+Pure function
+
+#### Argument
+
+- `string`: Character scalar or [[stdlib_string_type(module):string_type(type)]].
+  This argument is intent(in).
+- `output_length`: integer.
+  This argument is intent(in).
+- `pad_with`: Character scalar of length 1.
+  This argument is intent(in) and optional.
+
+#### Result value
+
+The result is of the same type as `string`.
+
+#### Example
+
+```fortran
+program demo_padl
+  use stdlib_string_type, only: string_type, assignment(=)
+  use stdlib_strings, only : padl
+  implicit none
+  string_type :: string
+
+  string = "left pad this string"
+  ! string <-- "left pad this string"
+
+  print *, padl(string, 25, "$") ! "$$$$$left pad this string"
+
+  string = padl(string, 25)
+  ! string <-- "     left pad this string"
+
+end program demo_padl
+```
+
+
+<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
+### `padr`
+
+#### Description
+
+Returns a string of length `output_length` right padded with `pad_with` character if it is provided, otherwise with `" "` (1 whitespace).  
+If `output_length` is less than or equal to the length of `string`, padding is not performed.
+
+#### Syntax
+
+`string = [[stdlib_strings(module):padr(interface)]] (string, output_length [, pad_with])`
+
+#### Status
+
+Experimental
+
+#### Class
+
+Pure function
+
+#### Argument
+
+- `string`: Character scalar or [[stdlib_string_type(module):string_type(type)]].
+  This argument is intent(in).
+- `output_length`: integer.
+  This argument is intent(in).
+- `pad_with`: Character scalar of length 1.
+  This argument is intent(in) and optional.
+
+#### Result value
+
+The result is of the same type as `string`.
+
+#### Example
+
+```fortran
+program demo_padr
+  use stdlib_string_type, only: string_type, assignment(=)
+  use stdlib_strings, only : padr
+  implicit none
+  string_type :: string
+
+  string = "right pad this string"
+  ! string <-- "right pad this string"
+
+  print *, padr(string, 25, "$") ! "right pad this string$$$$"
+
+  string = padr(string, 25)
+  ! string <-- "right pad this string    "
+
+end program demo_padr
+```
+
+
 <!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
 ### `count`
 

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

@@ -28,7 +28,8 @@ SRCFYPP =\
         stdlib_stats_distribution_PRNG.fypp \
         stdlib_string_type.fypp \
         stdlib_strings.fypp \
-        stdlib_string_format_to_string.fypp
+        stdlib_string_format_to_string.fypp \
+        stdlib_io_disp.fypp
 
 SRC = f18estop.f90 \
       stdlib_error.f90 \
@@ -77,7 +78,8 @@ stdlib_io.o: \
 	stdlib_error.o \
 	stdlib_optval.o \
 	stdlib_kinds.o \
-    stdlib_ascii.o
+    stdlib_ascii.o \
+    stdlib_string_type.o
 stdlib_linalg.o: \
 	stdlib_kinds.o
 stdlib_linalg_diag.o: \
@@ -135,14 +137,19 @@ stdlib_stats_var.o: \
 	stdlib_kinds.o \
 	stdlib_stats.o
 stdlib_stats_distribution_PRNG.o: \
-        stdlib_kinds.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_optval.o \
+    stdlib_optval.o \
     stdlib_kinds.o
 stdlib_math.o: stdlib_kinds.o
 stdlib_string_format_to_string.o: stdlib_strings.o
 stdlib_linalg_outer_product.o: stdlib_linalg.o
+stdlib_io_disp.o: stdlib_error.o \
+    stdlib_strings.o \
+    stdlib_string_type.o \
+    stdlib_io.o \
+    stdlib_ascii.o

src/stdlib_io.fypp

@@ -7,18 +7,51 @@ 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
   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
 
+  interface disp
+    !! version: experimental
+    !!
+    !! Display any type of scalar, vector and matrix.
+    !! ([Specification](../page/specs/stdlib_io.html#disp-display-your-data-to-the-screen-or-another-output-unit))
+    #:set DISP_KINDS_TYPES = REAL_KINDS_TYPES + INT_KINDS_TYPES &
+        & + CMPLX_KINDS_TYPES + LOG_KINDS_TYPES
+    #:set DISP_RANKS = range(0, 3)
+    #:for kind, type in DISP_KINDS_TYPES
+    #:for rank in DISP_RANKS
+    module subroutine disp_${rank}$_${type[0]}$${kind}$(value, unit, header, brief)
+        ${type}$, intent(in) :: value${ranksuffix(rank)}$
+        integer, intent(in), optional :: unit
+        character(len=*), intent(in), optional :: header
+        logical, intent(in), optional :: brief
+    end subroutine disp_${rank}$_${type[0]}$${kind}$
+    #:endfor
+    #:endfor
+    module subroutine disp_character(value, unit, header, brief)
+        character(len=*), intent(in), optional :: value
+        integer, intent(in), optional :: unit
+        character(len=*), intent(in), optional :: header
+        logical, intent(in), optional :: brief
+    end subroutine disp_character
+    module subroutine disp_string_type(value, unit, header, brief)
+        use stdlib_string_type, only: string_type
+        type(string_type), intent(in) :: value
+        integer, intent(in), optional :: unit
+        character(len=*), intent(in), optional :: header
+        logical, intent(in), optional :: brief
+    end subroutine disp_string_type
+  end interface disp
+
   interface loadtxt
     !! version: experimental
     !!