ParaMonte Fortran 2.0.0
Parallel Monte Carlo and Machine Learning Library
See the latest version documentation.
pm_io::getFormat Interface Reference

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,
  1. type character of kind any supported by the processor (e.g., SK, SKA, SKD , or SKU),
  2. type integer of kind any supported by the processor (e.g., IK, IK8, IK16, IK32, or IK64),
  3. type logical of kind any supported by the processor (e.g., LK),
  4. type complex of kind any supported by the processor (e.g., CK, CK32, CK64, or CK128),
  5. 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,
  1. 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})\).
  2. 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,
  1. 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})\).
  2. 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,
  1. 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})\).
  2. 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,
  1. If the goal is to print 7 scalar integer numbers on screen, count can be set to 7.
  2. 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.
  1. If the (sub)field is of type real or complex, then ndigit represents the number of digits after the decimal point.
  2. 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.
  3. 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.
  1. If .true., then the output format will print all positive numeric values with their signs.
  2. 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 &
)
Generate and return a generic or type/kind-specific IO format with the requested specifications that ...
Definition: pm_io.F90:18485
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
This is a generic method of the derived type display_type with pass attribute.
Definition: pm_io.F90:11726
This is a generic method of the derived type display_type with pass attribute.
Definition: pm_io.F90:11508
type(display_type) disp
This is a scalar module variable an object of type display_type for general display.
Definition: pm_io.F90:11393
This module defines the relevant Fortran kind type-parameters frequently used in the ParaMonte librar...
Definition: pm_kind.F90:268
integer, parameter LK
The default logical kind in the ParaMonte library: kind(.true.) in Fortran, kind(....
Definition: pm_kind.F90:541
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
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
integer, parameter RKH
The scalar integer constant of intrinsic default kind, representing the highest-precision real kind t...
Definition: pm_kind.F90:858
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
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.

  1. 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.
  2. 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.

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: