Generate and return a generic or type/kind-specific IO format with the requested specifications that can be use to read or write individual records in IO actions. More...

Detailed Description

Generate and return a generic or type/kind-specific IO format with the requested specifications that can be use to read or write individual records in IO actions.

Parameters

[in]	mold	: The input vector of arbitrary size `(:)` of, type `character` of kind any supported by the processor (e.g., SK, SKA, SKD , or SKU), type `integer` of kind any supported by the processor (e.g., IK, IK8, IK16, IK32, or IK64), type `logical` of kind any supported by the processor (e.g., LK), type `complex` of kind any supported by the processor (e.g., CK, CK32, CK64, or CK128), type `real` of kind any supported by the processor (e.g., RK, RK32, RK64, or RK128), whose kind type parameter determines the characteristics of the record fields for which the format is being constructed. This argument offers an easy way of defining `format` for fields of specific intrinsic type in a record, particularly, fields of type `character` or `complex`. For example, specifying a `complex` scalar for `mold` will automatically use the default left/right Fortran delimiters `()` for `complex` fields in the output `format`. If any other input argument is also present, its value will override the default behavior dictated by the presence of the input argument `mold`. The specific value and size of `mold` is completely ignored within the procedure. For more possibilities, see the examples below. (optional. If missing, the output `format` will be constructed for as generic as possible field records.)
[in]	prefix	: The input scalar of type `character` of default kind SK, containing the prefix to be added to the output `format`. The prefix appears at the beginning of the record to be written via the output `format`. (optional, default = `""`)
[in]	ed	: The input scalar of type `character` of default kind SK, containing the edit descriptor to be used for formatting each (sub)field. Possible values include but are not limited to `A`, `I`, `E`, `EN`, `ES`, `F`, `G`. (optional, default = `G`)
[in]	sep	: The input scalar of type `character` of default kind SK, containing the repeat field separator to be used in the output `format`. (optional, default = `", "`)
[in]	deliml	: The input scalar of type `character` of default kind SK, containing the set of characters that serve as the left-delimiter for a group of subfields (for example, the real and imaginary components of fields of type `complex`). For example, The input arguments `deliml = "(", subsep = ",", delimr = ")"` corresponds to the common Fortran format for displaying complex values with \(\ms{x}\) and \(\ms{y}\) components: \((\ms{x}, \ms{y})\). The input arguments `deliml = "", subsep = "", delimr = "i", signed = .true._LK` corresponds to the common mathematical format for displaying complex values with \(\ms{x}\) and \(\ms{y}\) components: \(\ms{x} + \ms{y}i\). (optional, default = `"("` if `mold` is of type `complex`, \(\ms{"}\) if `mold` is of type `character`, and nothing otherwise.)
[in]	subsep	: The input scalar of type `character` of default kind SK, containing the sub-field separator to be used in the output `format`. An example of subfields are the two real and imaginary components of `complex` fields. For example, The input arguments `deliml = "(", subsep = ",", delimr = ")"` corresponds to the common Fortran format for displaying complex values with \(\ms{x}\) and \(\ms{y}\) components: \((\ms{x}, \ms{y})\). The input arguments `deliml = "", subsep = "", delimr = "i", signed = .true._LK` corresponds to the common mathematical format for displaying complex values with \(\ms{x}\) and \(\ms{y}\) components: \(\ms{x} + \ms{y}i\). However, the use of subfields is not necessarily limited to `complex` values and can be applied to any fixed-size group of fields in a record. It is however, important to specify the number of subfields within a field of a record by setting the value of the input argument `subcount`. (optional, default = the value of the input argument `sep`.)
[in]	delimr	: The input scalar of type `character` of default kind SK, containing the set of characters that serve as the right-delimiter for a group of subfields (for example, the real and imaginary components of fields of type `complex`). For example, The input arguments `deliml = "(", subsep = ",", delimr = ")"` corresponds to the common Fortran format for displaying complex values with \(\ms{x}\) and \(\ms{y}\) components: \((\ms{x}, \ms{y})\). The input arguments `deliml = "", subsep = "", delimr = "i", signed = .true._LK` corresponds to the common mathematical format for displaying complex values with \(\ms{x}\) and \(\ms{y}\) components: \(\ms{x} + \ms{y}i\). (optional, default = `")"` if `mold` is of type `complex`, \(\ms{"}\) if `mold` is of type `character`, and nothing otherwise.)
[in]	count	: The input scalar positive `integer` of default kind IK containing the repeat count of groups of subfields in the record. For example, If the goal is to print `7` scalar `integer` numbers on screen, `count` can be set to `7`. If the goal is to print `7` scalar `complex` numbers on screen, `count` can be set to `7` if `subcount` is set to `2`, or to `14` if `subcount` is missing. See the Fortran standard for the definition of and more information about repeat count. If the number of entries is larger than the specified repeat count, the rest of entries will be transferred to the next record when performing IO via the output `format` from this generic interface. (optional, default = `*`, that is, as many as needed.)
[in]	subcount	: The input scalar positive `integer` of default kind IK containing the subfield count within a single field of the record. The input `subcount` is essentially the number of times the input `subsep` appears between subfields plus `1`. For example, if the `format` is to be used for `complex` values, `subcount` can be set to `2` along with other appropriate arguments to construct Fortran-style `complex` formats. (optional, default = `2` if `mold` is of type `complex` and `0` otherwise.)
[in]	width	: The input scalar positive `integer` of default kind IK containing the width of each each subfield (or if none exists, each field) in the record formatted via the output `format`. (optional. The default value is computed based on the input arguments such that any field value can be read or written with a fixed field length. Use `0` to request dynamic minimum width for each (sub)field that is automatically specified by the processor.)
[in]	ndigit	: The input scalar positive `integer` of default kind IK containing the precision of the subfields or fields. If the (sub)field is of type `real` or `complex`, then `ndigit` represents the number of digits after the decimal point. If the (sub)field is of type `integer`, then `ndigit` represents the minimum number of digits to display. This means that if an `integer` value has fewer digits than `ndigit`, the left side of the value will be padded with leading zeros. This form of padding with leading zeros is particularly useful for creating a numbered list of file names. Beware that `ndigit` can be zero, in which case, if the field value is `0`, it will not be displayed on screen and blank will be printed. Note that `ndigit` takes effect only when the input argument `mold` is of type `integer` or if the edit descriptor argument `ed` is set to `I` or `i`. Set `ndigit = range(int(1, kind(mold)))` to create an output `format` that pads `integer` fields with maximum possible number of leading zeros for the specified `integer` kind `mold`. For all other field types (e.g., `character`, `logical`, etc) the value of this argument is irrelevant and is ignored. (optional, default is `precision(mold)` for `real` and `complex` and `1` for `integer`. In all other cases or if `mold` is missing, the default is processor dependent.)
[in]	lenexp	: The input scalar `integer` of default kind IK containing the minimum width of the exponent for real-valued entries in the records formatted via the output `format`. Note that when the input argument `ndigit` is specified, the Fortran default exponent field length becomes `3`. As such, if `ndigit` is present, then it is recommended to also explicitly specify `lenexp` must be explicitly set for output formats that are supposed to handle numbers with kind type parameter numbers that have exponent range that occupies more than 3 digits, e.g., RK128, CK128. (optional, default = `0` corresponding to the minimum number of digits required to represent the exponent value, that is, without leading zeros. If present, `ndigit` must be also present.)
[in]	signed	: The input scalar `logical` of default kind LK. If `.true.`, then the output `format` will print all positive numeric values with their signs. If `.false.`, then the output `format` will not print all positive numeric values with their signs. (optional, default = `.false.`)

Returns: format : The output scalar allocatable of type character of default kind SK containing the requested IO format.

Possible calling interfaces ⛓

: use pm_io, only: getFormat

character(:), allocatable :: format

! generic fields format.

format = getFormat( prefix = prefix &

, ed = ed &

, sep = sep &

, deliml = deliml &

, subsep = subsep &

, delimr = delimr &

, count = count &

, subcount = subcount &

, width = width &

, ndigit = ndigit &

, lenexp = lenexp &

, signed = signed &

)

! type-specific fields format.

format = getFormat( mold(:) &

, prefix = prefix &

, ed = ed &

, sep = sep &

, deliml = deliml &

, subsep = subsep &

, delimr = delimr &

, count = count &

, subcount = subcount &

, width = width &

, ndigit = ndigit &

, lenexp = lenexp &

, signed = signed &

)

pm_io::getFormat
Generate and return a generic or type/kind-specific IO format with the requested specifications that ...
Definition: pm_io.F90:18485

pm_io
This module contains classes and procedures for input/output (IO) or generic display operations on st...
Definition: pm_io.F90:252

Warning: The condition present(lenexp) .and. present(ndigit) .or. .not. present(lenexp) must hold for the corresponding input argument.
The Fortran standard requires the precision field to be present when the exponent field is present.
The condition present(lenexp) .and. width /= 0 .or. .not. present(lenexp) must hold for the corresponding input argument.
The Fortran standard requires the specified width be non-zero in the presence of the lenexp field.
The condition ed == "g" .or. ed == "G" .or. width > 0 must hold for the corresponding input arguments.
The Fortran standard requires a non-zero width (preferably, width >= 5 + ndigit + lenexp).
The condition (ed /= SKG_"f" .and. ed /= SKG_"F") .or. .not.present(lenexp) must hold for the corresponding input arguments.
These conditions are verified only if the library is built with the preprocessor macro CHECK_ENABLED=1.

Remarks: The procedures under discussion are pure.

See also: display_type

Example usage ⛓

: 1program example

2

3 use pm_kind, only: SK, IK, LK, RKS, RKH

4 use pm_io, only: display_type

5 use pm_io, only: getFormat

6

7 implicit none

8

9 character(:, SK), allocatable :: format

10

11 type(display_type) :: disp

12 disp = display_type(file = "main.out.F90")

13

14 call disp%skip

15 call disp%show("format = getFormat()")

16 format = getFormat()

17 call disp%show("format")

18 call disp%show( format , deliml = '''' )

19 call disp%show("format = getFormat([''])")

20 format = getFormat([''])

21 call disp%show("format")

22 call disp%show( format , deliml = '''' )

23 call disp%show("format = getFormat([1])")

24 format = getFormat([1])

25 call disp%show("format")

26 call disp%show( format , deliml = '''' )

27 call disp%show("format = getFormat([.false.])")

28 format = getFormat([.false.])

29 call disp%show("format")

30 call disp%show( format , deliml = '''' )

31 call disp%show("format = getFormat([cmplx(0, kind = RKS)])")

32 format = getFormat([cmplx(0, kind = RKS)])

33 call disp%show("format")

34 call disp%show( format , deliml = '''' )

35 call disp%show("write(disp%unit, format) cmplx(3.1415926535897932384626433832795028841971_RKH, kind = RKH)")

36 write(disp%unit, format) cmplx(3.1415926535897932384626433832795028841971_RKH, kind = RKH)

37 call disp%show("format = getFormat([cmplx(0, kind = RKH)])")

38 format = getFormat([cmplx(0, kind = RKH)])

39 call disp%show("format")

40 call disp%show( format , deliml = '''' )

41 call disp%show("write(disp%unit, format) cmplx(3.1415926535897932384626433832795028841971_RKH)")

42 write(disp%unit, format) cmplx(3.1415926535897932384626433832795028841971_RKH)

43 call disp%show("format = getFormat(deliml = '', subsep = SK_'', delimr = 'i', subcount = 2_IK, ndigit = 1_IK, signed = .true._LK) ! math-style complex value.")

44 format = getFormat(deliml = '', subsep = SK_'', delimr = 'i', subcount = 2_IK, ndigit = 1_IK, signed = .true._LK)

45 call disp%show("format")

46 call disp%show( format , deliml = '''' )

47 call disp%show("write(disp%unit, format) cmplx(3.1415926535897932384626433832795028841971_RKH)")

48 write(disp%unit, format) cmplx(3.1415926535897932384626433832795028841971_RKH)

49 call disp%show("format = getFormat([real(0, kind = RKS)])")

50 format = getFormat([real(0, kind = RKS)])

51 call disp%show("format")

52 call disp%show( format , deliml = '''' )

53 call disp%show("write(disp%unit, format) 'pi', 3.1415926535897932384626433832795028841971_RKH")

54 write(disp%unit, format) 'pi', 3.1415926535897932384626433832795028841971_RKH

55 call disp%show("format = getFormat([real(0, kind = RKH)])")

56 format = getFormat([real(0, kind = RKH)])

57 call disp%show("format")

58 call disp%show( format , deliml = '''' )

59 call disp%show("write(disp%unit, format) 'pi', 3.1415926535897932384626433832795028841971_RKH")

60 write(disp%unit, format) 'pi', 3.1415926535897932384626433832795028841971_RKH

61 call disp%skip

62

63 call disp%skip

64 call disp%show("format = getFormat(prefix = SK_'ParaMonte: ', sep = SK_' = ', ndigit = 8_IK, signed = .true._LK)")

65 format = getFormat(prefix = SK_'ParaMonte: ', sep = SK_' = ', ndigit = 8_IK, signed = .true._LK)

66 call disp%show("format")

67 call disp%show( format , deliml = '''' )

68 call disp%show("write(disp%unit, format) 'huge(0._RKH)', huge(0._RKH)")

69 call disp%skip

70

71 call disp%skip

72 call disp%show("format = getFormat(mold = [0._RKH], prefix = SK_'ParaMonte: ', sep = SK_' = ')")

73 format = getFormat(mold = [0._RKH], prefix = SK_'ParaMonte: ', sep = SK_' = ')

74 call disp%show("format")

75 call disp%show( format , deliml = '''' )

76 call disp%show("write(disp%unit, format) 'huge(0._RKH)', huge(0._RKH)")

77 write(disp%unit, format) 'huge(0._RKH)', huge(0._RKH)

78 call disp%skip

79

80 call disp%skip

81 call disp%show("format = getFormat()")

82 format = getFormat()

83 call disp%show("format")

84 call disp%show( format , deliml = '''' )

85 call disp%skip

86

87 call disp%skip

88 call disp%show("format = getFormat(mold = [SK_''], prefix = SK_'ParaMonte: ', subcount = 2, deliml = SK_'''', subsep = SK_' ') ! string format with delimited subfields")

89 format = getFormat(mold = [SK_''], prefix = SK_'ParaMonte: ', subcount = 2, deliml = SK_'''', subsep = SK_' ')

90 call disp%show("format")

91 call disp%show( format , deliml = '''' )

92 call disp%show("write(disp%unit, format) 'monte', 'carlo', 'machine', 'learning', 'parallel', 'library'")

93 write(disp%unit, format) 'monte', 'carlo', 'machine', 'learning', 'parallel', 'library'

94 call disp%skip

95

96end program example

pm_io::show
This is a generic method of the derived type display_type with pass attribute.
Definition: pm_io.F90:11726

pm_io::skip
This is a generic method of the derived type display_type with pass attribute.
Definition: pm_io.F90:11508

pm_io::disp
type(display_type) disp
This is a scalar module variable an object of type display_type for general display.
Definition: pm_io.F90:11393

pm_kind
This module defines the relevant Fortran kind type-parameters frequently used in the ParaMonte librar...
Definition: pm_kind.F90:268

pm_kind::LK
integer, parameter LK
The default logical kind in the ParaMonte library: kind(.true.) in Fortran, kind(....
Definition: pm_kind.F90:541

pm_kind::IK
integer, parameter IK
The default integer kind in the ParaMonte library: int32 in Fortran, c_int32_t in C-Fortran Interoper...
Definition: pm_kind.F90:540

pm_kind::SK
integer, parameter SK
The default character kind in the ParaMonte library: kind("a") in Fortran, c_char in C-Fortran Intero...
Definition: pm_kind.F90:539

pm_kind::RKH
integer, parameter RKH
The scalar integer constant of intrinsic default kind, representing the highest-precision real kind t...
Definition: pm_kind.F90:858

pm_kind::RKS
integer, parameter RKS
The single-precision real kind in Fortran mode. On most platforms, this is an 32-bit real kind.
Definition: pm_kind.F90:567

pm_io::display_type
Generate and return an object of type display_type.
Definition: pm_io.F90:10282

Example Unix compile command via Intel ifort compiler ⛓
1#!/usr/bin/env sh

2rm main.exe

3ifort -fpp -standard-semantics -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe

4./main.exe

Example Windows Batch compile command via Intel ifort compiler ⛓
1del main.exe

2set PATH=..\..\..\lib;%PATH%

3ifort /fpp /standard-semantics /O3 /I:..\..\..\include main.F90 ..\..\..\lib\libparamonte*.lib /exe:main.exe

4main.exe

Example Unix / MinGW compile command via GNU gfortran compiler ⛓
1#!/usr/bin/env sh

2rm main.exe

3gfortran -cpp -ffree-line-length-none -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe

4./main.exe

Example output ⛓
1

2format = getFormat()

3format

4'(*(g0,:,", "))'

5format = getFormat([''])

6format

7'(*("""",g0,"""",:,", "))'

8format = getFormat([1])

9format

10'(*(i1,:,", "))'

11format = getFormat([.false.])

12format

13'(*(g0,:,", "))'

14format = getFormat([cmplx(0, kind = RKS)])

15format

16'(*("(",g13.6e2,", ",g13.6e2,")",:,", "))'

17write(disp%unit, format) cmplx(3.1415926535897932384626433832795028841971_RKH, kind = RKH)

18( 3.14159 , 0.00000 )

19format = getFormat([cmplx(0, kind = RKH)])

20format

21'(*("(",g42.33e4,", ",g42.33e4,")",:,", "))'

22write(disp%unit, format) cmplx(3.1415926535897932384626433832795028841971_RKH)

23( 3.14159274101257324218750000000000 , 0.00000000000000000000000000000000 )

24format = getFormat(deliml = '', subsep = SK_'', delimr = 'i', subcount = 2_IK, ndigit = 1_IK, signed = .true._LK) ! math-style complex value.

25format

26'(sp,*("",g0.1,"",g0.1,"i",:,", "))'

27write(disp%unit, format) cmplx(3.1415926535897932384626433832795028841971_RKH)

28+3.+0.i

29format = getFormat([real(0, kind = RKS)])

30format

31'(*(g13.6e2,:,", "))'

32write(disp%unit, format) 'pi', 3.1415926535897932384626433832795028841971_RKH

33 pi, 3.14159

34format = getFormat([real(0, kind = RKH)])

35format

36'(*(g42.33e4,:,", "))'

37write(disp%unit, format) 'pi', 3.1415926535897932384626433832795028841971_RKH

38 pi, 3.14159265358979323846264338327950

39

40

41format = getFormat(prefix = SK_'ParaMonte: ', sep = SK_' = ', ndigit = 8_IK, signed = .true._LK)

42format

43'("ParaMonte: ",sp,*(g0.8,:," = "))'

44write(disp%unit, format) 'huge(0._RKH)', huge(0._RKH)

45

46

47format = getFormat(mold = [0._RKH], prefix = SK_'ParaMonte: ', sep = SK_' = ')

48format

49'("ParaMonte: ",*(g42.33e4,:," = "))'

50write(disp%unit, format) 'huge(0._RKH)', huge(0._RKH)

51ParaMonte: huge(0._RKH) = 0.118973149535723176508575932662801E+4933

52

53

54format = getFormat()

55format

56'(*(g0,:,", "))'

57

58

59format = getFormat(mold = [SK_''], prefix = SK_'ParaMonte: ', subcount = 2, deliml = SK_'''', subsep = SK_' ') ! string format with delimited subfields

60format

61'("ParaMonte: ",*("'",g0," ",g0,"'",:,", "))'

62write(disp%unit, format) 'monte', 'carlo', 'machine', 'learning', 'parallel', 'library'

63ParaMonte: 'monte carlo', 'machine learning', 'parallel library'

64

65

Test:: test_pm_io

Bug:: Status: Unresolved
Source: Intel Classic Fortran Compiler ifort version 2021.8.0 20221119
Description: The Intel Classic Fortran Compiler ifort version 2021.8.0 20221119 cannot run the following function call within the implementation of the procedures,

getCountDigit(range(mold))

yielding the following error,

forrtl: severe (174): SIGSEGV, segmentation fault occurred
image              PC                Routine            Line        Source
libpthread-2.33.s  00001550E3A9C1F0  Unknown               Unknown  Unknown
libparamonte_fort  00001550E810D8B4  pm_mathnumsys_MP_         137  pm_mathNumSys@routines.inc.F90
libparamonte_fort  00001550E764778D  pm_io_MP_get               83  pm_io@routines.inc.F90
main.exe           000000000040CBE9  MAIN__                     83  main.F90
main.exe           000000000040938D  Unknown               Unknown  Unknown
libc-2.33.so       00001550E38BD565  __libc_start_main     Unknown  Unknown
main.exe           00000000004092AE  Unknown               Unknown  Unknown

Remedy (as of ParaMonte Library version 2.0.0): For now, the value attribute of the input argument of function getCountDigit was converted to intent(in).

Final Remarks ⛓

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright: Computational Data Science Lab

Author:: Amir Shahmoradi, Oct 16, 2009, 2:47 AM, Michigan

Definition at line 18485 of file pm_io.F90.

The documentation for this interface was generated from the following file:

src/fortran/main/pm_io.F90