stdlib_io: add print_array function to print arrays to output units

[zoziha]

Description

Add print_array subroutine, which is used to print two-dimensional arrays of integer and floating-point types. These two types are more commonly used in Fortran. It supports arguments such as delimiter, output unit, output format, and whether to print briefly.

In the non-brief output mode, the print_array function can produce an output result style similar to that of savetxt in stdlib_io. The print_array function is mainly convenient for users to output to the screen (standard output) and is likely to be mostly used for code debugging.

Prior Art:

• disp in Matlab;
• The default print of Python and Julia;
• brief_print in Armadillo.

This PR will replace #520, and is related to #40, but is not sufficient to close #40.

Remaining to be discussed

• Is it necessary to support delimiters of any length, not just those with a length of 1? In addition to the print_array, it also includes the savetxt routine in stdlib_io.
• Currently, print_array is designed to assist users in program debugging and does not provide file write error reports like savetxt does.

[Copilot]

Pull Request Overview

This pull request adds a new subroutine specification, print_array, to the stdlib_io module for printing 2D arrays to an output unit.

• Introduces detailed documentation covering the subroutine’s syntax, argument descriptions, and an example.
• Specifies default behaviors for output unit, delimiter, format, and brief mode.

Files not reviewed (7)

• example/io/CMakeLists.txt: Language not supported
• example/io/example_print_array.f90: Language not supported
• src/CMakeLists.txt: Language not supported
• src/stdlib_io.fypp: Language not supported
• src/stdlib_io_print_array.fypp: Language not supported
• test/io/CMakeLists.txt: Language not supported
• test/io/test_print_array.f90: Language not supported

[jvdp1]

Thank you @zoziha . Here are some minor comments.

[jvdp1]

what is a "brief" format? Could you maybe provide a short definition?

[zoziha]

Okay. Details of the "brief" format were added, and an example was deliberately provided to illustrate the usage of the "brief" format.

[jvdp1]

Minor comment: the name could be discussed with the community. Personally, I would prefer disp.

[Mahmood-Sinan]

Hi,
I noticed that complex arrays are printed as separate real and imaginary parts, rather than (a,b) or a + bi.

complex, dimension(2, 2) :: a = reshape([cmplx(1,2), cmplx(3,4), cmplx(5,6), cmplx(7,8)], [2,2])
print *, a

print "(a)", "=== print_array 1 ==="
call print_array(a, unit=6, fmt='(f7.1)', delimiter='|', brief=.false.)

The above code displayed

             (1.00000000,2.00000000)             (3.00000000,4.00000000)             (5.00000000,6.00000000)             (7.00000000,8.00000000)
=== print_array 1 ===
    1.0|    2.0|    5.0|    6.0
    3.0|    4.0|    7.0|    8.0

For readability, it might be nicer to display them as in brackets or in a+bi form. One idea could be to add an optional complex_format flag (or similar) that controls whether complex numbers are printed as (a,b) or a + bi.

[Mahmood-Sinan]

Thank you @zoziha. One suggestion:
Can each entry of complex type array be printed as (a,b) form instead of using a delimiter between the real and imaginary parts. For example, for an array
complex, dimension(2, 2) :: a = reshape([cmplx(1,2), cmplx(3,4), cmplx(5,6), cmplx(7,8)], [2,2])
can the output be displayed as:

(1.0,2.0) | (5.0,6.0)
(3.0,4.0) | (7.0,8.0)

instead of

    1.0|    2.0|    5.0|    6.0
    3.0|    4.0|    7.0|    8.0

where delimiter is |.