Generate and return the iostat
code resulting from reading the contents of the specified file
or unit
into an output table
.
- Parameters
-
[in] | file | : The input scalar character of default kind SK representing the path to the external file to which the table must be read.
If the specified file does not exist, it will be created.
If it exists or is already connected, it will repositioned before the beginning of its first record.
(optional. It can be present only if the input argument unit is missing.) |
[in] | unit | : The input scalar integer of default kind IK representing the preconnected (opened) file unit to which the table must be read.
The writing will begin from the current file position plus the input roff .
(optional. It can be present only if the input argument file is missing.) |
[out] | table | : The output allocatable array of shape (:) or (:,:) of either
-
type
character of kind any supported by the processor (e.g., SK, SKA, SKD , or SKU) of predefined length type parameter (not deferred-length), or
-
type
integer of kind any supported by the processor (e.g., IK, IK8, IK16, IK32, or IK64), or
-
type
logical of kind any supported by the processor (e.g., LK), or
-
type
complex of kind any supported by the processor (e.g., CK, CK32, CK64, or CK128), or
-
type
real of kind any supported by the processor (e.g., RK, RK32, RK64, or RK128),
representing the data table to be read from the specified input.
By default a table of rank 1 is considered to be a single column unless the input optional argument operation is set to trans in which case table is considered as a row of fields.
See the tips in the note below for reading tables of complex values written in the Fortran list-directed format.
By default, if the input argument operation is missing, each column of table corresponds to each column of data in the file.
|
[in] | operation | : The input scalar constant that can be:
-
the scalar constant trans or a scalar object of type trans_type, implying that the input
table must be transposed before being written to the output file.
This option is particularly useful for inputting rows of table in Fortran column-major storage mode, that is, rows of table occupy the first dimension of the matrix table such that rows of data in the output file are stored contiguously in memory.
Use this option if you intend to work with rows more so than with individual columns.
(optional, default = nothing, implying that the table must be output as is.) |
[out] | header | : The output allocatable scalar character of default kind SK of arbitrary length type parameter containing the table header.
The output table header can be subsequently split into fields by passing header and sep to the generic interface setSplit.
If the table in file contains a header, but header argument is missing, then roff must be set to at least 1 to gracefully skip the header line.
(optional, If missing, no header will be read from the specified input.
The generic interface getStr() can be used to readily join a list of header fields with the appropriate separator.) |
[in] | sep | : The input scalar character of default kind SK of arbitrary length type parameter containing the separator of the fields of each of row of the table in the input file.
An empty input sep implies that there is only a single column in the file.
(optional, default = , or (blank).) |
[in] | roff | : The input scalar integer of default kind IK representing the row offset, that is, the number of rows in the external file or unit to skip before beginning to read the output variables header and table .
(optional. default = 0 ) |
[in,out] | iomsg | : The input/output scalar character of default kind SK containing the error message, if any error occurs.
A length type parameter value of LEN_IOMSG is generally sufficient for iomsg to contain the output error messages.
(optional. If missing, no information other than the output error code err will be returned.) |
- Returns
err
: The output scalar integer
of default kind IK containing the iostat
error code returned by the Fortran intrinsic write()
statement.
On return, err
is set to 0
if and only if the table
is successfully read from the input.
See the Fortran standard and specific compiler documentations for the possible meanings of the output err
.
Possible calling interfaces ⛓
integer(IK) :: err
err = getErrTableRead(unit, table, header
= header, sep
= sep, roff
= roff,
iomsg = iomsg)
err = getErrTableRead(file, table, header
= header, sep
= sep, roff
= roff,
iomsg = iomsg)
err = getErrTableRead(unit, table, operation, header
= header, sep
= sep, roff
= roff,
iomsg = iomsg)
err = getErrTableRead(file, table, operation, header
= header, sep
= sep, roff
= roff,
iomsg = iomsg)
!
Generate and return the iostat code resulting from reading the contents of the specified file or unit...
This module contains classes and procedures for input/output (IO) or generic display operations on st...
This module defines the relevant Fortran kind type-parameters frequently used in the ParaMonte librar...
integer, parameter IK
The default integer kind in the ParaMonte library: int32 in Fortran, c_int32_t in C-Fortran Interoper...
- Note
- For
table
of type complex
, it is best to either
-
have the
complex
table fields in the file in Fortran list-directed format (.,.)
and drop the sep
input argument to activate the default intrinsic [Fortran list-directed parser, or
-
have the
complex
table fields in the file written as if real
and imaginary
components are independent table fields and specify the sep
argument to activate the customized parser to read the table.
Otherwise,
-
if the file is in Fortran list-directed format and
sep
is present or,
-
if the file is in csv format or similar and
sep
is missing,
The table read action will fail.
If so, the algorithm will try to read the table
again by reading it with the alternative parser before completely failing and returning a non-zero code.
- Developer Remark:
- The naming choice
sep
over delim
or similar is deliberate.
While many resources consider separator and delimiter identical, it is more sensible to consider delimiter as a character set that determines what belong to a field, and separator as a character set that separates different fields from each other.
This convention is also consistent with the Fortran standard terminology where delimiters are referred to as delimiters.
- See also
- getRecordFrom
setRecordFrom
getContentsFrom
setContentsFrom
getErrTableRead
getErrTableWrite
Example usage ⛓
3 use iso_fortran_env,
only:
output_unit,
input_unit,
error_unit
14 character(LEN_IOMSG, SK) :: iomsg
15 character(:, SK),
allocatable :: file, header
16 type(display_type) :: disp
22 character(
2,SKG),
allocatable :: table(:,:)
24 call disp%show(
"table = getUnifRand('aa', 'zz', 3_IK, 6_IK)")
27 call disp%show( table , deliml
= SK_
"""" )
30 call disp%show(
"if (0 /= getErrTableWrite(file, table, deliml = SKG_'''')) error stop 'table write failed.'")
31 if (
0 /= getErrTableWrite(file, table, deliml
= SKG_
''''))
error stop 'table write failed.'
34 call disp%show(
"if (0 /= getErrTableRead(file, table)) error stop 'table write failed.'")
37 call disp%show( table , deliml
= SK_
"""" )
43 integer(IKG),
allocatable :: table(:,:)
45 call disp%show(
"table = getUnifRand(-1, 1, 4_IK, 2_IK)")
51 call disp%show(
"if (0 /= getErrTableWrite(file, table, header = 'col1 col2', sep = SK_' ')) error stop 'table write failed.'")
52 if (
0 /= getErrTableWrite(file, table, header
= 'col1 col2', sep
= SK_
' '))
error stop 'table write failed.'
55 call disp%show(
"if (0 /= getErrTableRead(file, table, header = header)) error stop 'table read failed.'")
56 if (
0 /= getErrTableRead(file, table, header
= header))
error stop 'table read failed.'
58 call disp%show( header , deliml
= SK_
"""" )
63 call disp%show(
"if (0 /= getErrTableRead(file, table, header = header, sep = SK_' ')) error stop 'table read failed.'")
64 if (
0 /= getErrTableRead(file, table, header
= header, sep
= SK_
' '))
error stop 'table read failed.'
66 call disp%show( header , deliml
= SK_
"""" )
70 call disp%show(
"if (0 /= getErrTableWrite(file, table, trans, sep = '|', roff = 2_IK)) error stop 'table write failed.'")
71 if (
0 /= getErrTableWrite(file, table, trans, sep
= '|', roff
= 2_IK))
error stop 'table write failed.'
74 call disp%show(
"if (0 /= getErrTableRead(file, table, sep = SK_'|', roff = 2_IK, iomsg = iomsg)) error stop trim(iomsg)")
75 if (
0 /= getErrTableRead(file, table, sep
= SK_
'|', roff
= 2_IK,
iomsg = iomsg))
error stop trim(iomsg)
80 call disp%show(
"if (0 /= getErrTableRead(file, table, trans, sep = SK_'|', roff = 2_IK)) error stop 'table read failed.'")
81 if (
0 /= getErrTableRead(file, table, trans, sep
= SK_
'|', roff
= 2_IK))
error stop 'table read failed.'
83 call disp%show( header , deliml
= SK_
"""" )
91 logical(LKG),
allocatable :: table(:,:)
93 call disp%show(
"table = getUnifRand(.false., .true., 4_IK, 2_IK)")
99 call disp%show(
"if (0 /= getErrTableWrite(file, table, header = 'col1 col2', sep = SK_' ')) error stop 'table write failed.'")
100 if (
0 /= getErrTableWrite(file, table, header
= 'col1 col2', sep
= SK_
' '))
error stop 'table write failed.'
103 call disp%show(
"if (0 /= getErrTableRead(file, table, header = header)) error stop 'table read failed.'")
104 if (
0 /= getErrTableRead(file, table, header
= header))
error stop 'table read failed.'
106 call disp%show( header , deliml
= SK_
"""" )
111 call disp%show(
"if (0 /= getErrTableRead(file, table, header = header, sep = SK_' ')) error stop 'table read failed.'")
112 if (
0 /= getErrTableRead(file, table, header
= header, sep
= SK_
' '))
error stop 'table read failed.'
114 call disp%show( header , deliml
= SK_
"""" )
118 call disp%show(
"if (0 /= getErrTableWrite(file, table, trans, sep = '|', roff = 2_IK)) error stop 'table write failed.'")
119 if (
0 /= getErrTableWrite(file, table, trans, sep
= '|', roff
= 2_IK))
error stop 'table write failed.'
122 call disp%show(
"if (0 /= getErrTableRead(file, table, sep = SK_'|', roff = 2_IK)) error stop 'table read failed.'")
123 if (
0 /= getErrTableRead(file, table, sep
= SK_
'|', roff
= 2_IK))
error stop 'table read failed.'
128 call disp%show(
"if (0 /= getErrTableRead(file, table, trans, sep = SK_'|', roff = 2_IK)) error stop 'table read failed.'")
129 if (
0 /= getErrTableRead(file, table, trans, sep
= SK_
'|', roff
= 2_IK))
error stop 'table read failed.'
131 call disp%show( header , deliml
= SK_
"""" )
139 complex(CKG),
allocatable :: table(:,:)
141 call disp%show(
"table = getUnifRand((-1., -1.), (+1., +1.), 4_IK, 2_IK)")
142 table
= getUnifRand((
-1.,
-1.), (
+1.,
+1.),
4_IK,
2_IK)
145 call disp%show(
"file = 'temp.temp'")
147 call disp%show(
"if (0 /= getErrTableWrite(file, table, header = 'col1 col2', sep = SK_' ')) error stop 'table write failed.'")
148 if (
0 /= getErrTableWrite(file, table, header
= 'col1 col2', sep
= SK_
' '))
error stop 'table write failed.'
151 call disp%show(
"if (0 /= getErrTableRead(file, table, header = header)) error stop 'table read failed.'")
152 if (
0 /= getErrTableRead(file, table, header
= header))
error stop 'table read failed.'
154 call disp%show( header , deliml
= SK_
"""" )
159 call disp%show(
"if (0 /= getErrTableRead(file, table, header = header, sep = SK_' ')) error stop 'table read failed.'")
160 if (
0 /= getErrTableRead(file, table, header
= header, sep
= SK_
' '))
error stop 'table read failed.'
162 call disp%show( header , deliml
= SK_
"""" )
166 call disp%show(
"if (0 /= getErrTableWrite(file, table, trans, sep = '|', roff = 2_IK)) error stop 'table write failed.'")
167 if (
0 /= getErrTableWrite(file, table, trans, sep
= '|', roff
= 2_IK))
error stop 'table write failed.'
170 call disp%show(
"if (0 /= getErrTableRead(file, table, sep = SK_'|', roff = 2_IK, iomsg = iomsg)) error stop trim(iomsg)")
171 if (
0 /= getErrTableRead(file, table, sep
= SK_
'|', roff
= 2_IK,
iomsg = iomsg))
error stop trim(iomsg)
176 call disp%show(
"if (0 /= getErrTableRead(file, table, trans, sep = SK_'|', roff = 2_IK)) error stop 'table read failed.'")
177 if (
0 /= getErrTableRead(file, table, trans, sep
= SK_
'|', roff
= 2_IK))
error stop 'table read failed.'
179 call disp%show( header , deliml
= SK_
"""" )
187 real(RKG),
allocatable :: table(:,:)
189 call disp%show(
"table = getUnifRand(-1, 1, 4_IK, 2_IK)")
193 call disp%show(
"file = 'temp.temp'")
195 call disp%show(
"if (0 /= getErrTableWrite(file, table, header = 'col1 col2', sep = SK_' ')) error stop 'table write failed.'")
196 if (
0 /= getErrTableWrite(file, table, header
= 'col1 col2', sep
= SK_
' '))
error stop 'table write failed.'
199 call disp%show(
"if (0 /= getErrTableRead(file, table, header = header)) error stop 'table read failed.'")
200 if (
0 /= getErrTableRead(file, table, header
= header))
error stop 'table read failed.'
202 call disp%show( header , deliml
= SK_
"""" )
207 call disp%show(
"if (0 /= getErrTableRead(file, table, header = header, sep = SK_' ')) error stop 'table read failed.'")
208 if (
0 /= getErrTableRead(file, table, header
= header, sep
= SK_
' '))
error stop 'table read failed.'
210 call disp%show( header , deliml
= SK_
"""" )
214 call disp%show(
"if (0 /= getErrTableWrite(file, table, trans, sep = '|', roff = 2_IK)) error stop 'table write failed.'")
215 if (
0 /= getErrTableWrite(file, table, trans, sep
= '|', roff
= 2_IK))
error stop 'table write failed.'
218 call disp%show(
"if (0 /= getErrTableRead(file, table, sep = SK_'|', roff = 2_IK)) error stop 'table read failed.'")
219 if (
0 /= getErrTableRead(file, table, sep
= SK_
'|', roff
= 2_IK))
error stop 'table read failed.'
224 call disp%show(
"if (0 /= getErrTableRead(file, table, trans, sep = SK_'|', roff = 2_IK)) error stop 'table read failed.'")
225 if (
0 /= getErrTableRead(file, table, trans, sep
= SK_
'|', roff
= 2_IK))
error stop 'table read failed.'
227 call disp%show( header , deliml
= SK_
"""" )
Generate and return a scalar or a contiguous array of rank 1 of length s1 of randomly uniformly distr...
Generate and return the entire contents of the input unconnected file or the (remaining) contents of ...
Generate and return the iostat code resulting from writing the input table of rank 1 or 2 to the spec...
This is a generic method of the derived type display_type with pass attribute.
This is a generic method of the derived type display_type with pass attribute.
This module contains classes and procedures for computing various statistical quantities related to t...
integer(IK), parameter LEN_IOMSG
The scalar integer of default kind IK representing the maximum length of an IO error message returned...
type(display_type) disp
This is a scalar module variable an object of type display_type for general display.
integer, parameter LK
The default logical kind in the ParaMonte library: kind(.true.) in Fortran, kind(....
integer, parameter CKS
The single-precision complex kind in Fortran mode. On most platforms, this is a 32-bit real kind.
integer, parameter SK
The default character kind in the ParaMonte library: kind("a") in Fortran, c_char in C-Fortran Intero...
integer, parameter RKS
The single-precision real kind in Fortran mode. On most platforms, this is an 32-bit real kind.
Generate and return an object of type display_type.
Example Unix compile command via Intel ifort
compiler ⛓
3ifort -fpp -standard-semantics -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe
Example Windows Batch compile command via Intel ifort
compiler ⛓
2set PATH=..\..\..\lib;%PATH%
3ifort /fpp /standard-semantics /O3 /I:..\..\..\include main.F90 ..\..\..\lib\libparamonte*.lib /exe:main.exe
Example Unix / MinGW compile command via GNU gfortran
compiler ⛓
3gfortran -cpp -ffree-line-length-none -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe
Example output ⛓
4"mv",
"ue",
"cu",
"md",
"jp",
"qv"
5"el",
"so",
"tp",
"xv",
"fm",
"zn"
6"dj",
"jr",
"wi",
"ya",
"mi",
"oa"
8if (
0 /= getErrTableWrite(file, table, deliml
= SKG_
''''))
error stop 'table write failed.'
12"mv",
"ue",
"cu",
"md",
"jp",
"qv"
13"el",
"so",
"tp",
"xv",
"fm",
"zn"
14"dj",
"jr",
"wi",
"ya",
"mi",
"oa"
24if (
0 /= getErrTableWrite(file, table, header
= 'col1 col2', sep
= SK_
' '))
error stop 'table write failed.'
26if (
0 /= getErrTableRead(file, table, header
= header))
error stop 'table read failed.'
35if (
0 /= getErrTableRead(file, table, header
= header, sep
= SK_
' '))
error stop 'table read failed.'
44if (
0 /= getErrTableWrite(file, table, trans, sep
= '|', roff
= 2_IK))
error stop 'table write failed.'
46if (
0 /= getErrTableRead(file, table, sep
= SK_
'|', roff
= 2_IK,
iomsg = iomsg))
error stop trim(iomsg)
51if (
0 /= getErrTableRead(file, table, trans, sep
= SK_
'|', roff
= 2_IK))
error stop 'table read failed.'
68if (
0 /= getErrTableWrite(file, table, header
= 'col1 col2', sep
= SK_
' '))
error stop 'table write failed.'
70if (
0 /= getErrTableRead(file, table, header
= header))
error stop 'table read failed.'
79if (
0 /= getErrTableRead(file, table, header
= header, sep
= SK_
' '))
error stop 'table read failed.'
88if (
0 /= getErrTableWrite(file, table, trans, sep
= '|', roff
= 2_IK))
error stop 'table write failed.'
90if (
0 /= getErrTableRead(file, table, sep
= SK_
'|', roff
= 2_IK))
error stop 'table read failed.'
95if (
0 /= getErrTableRead(file, table, trans, sep
= SK_
'|', roff
= 2_IK))
error stop 'table read failed.'
105table
= getUnifRand((
-1.,
-1.), (
+1.,
+1.),
4_IK,
2_IK)
107(
-0.258203268,
-0.208388209), (
-0.774918199,
-0.804242373)
108(
+0.511335969,
-0.402538657), (
+0.548754215,
+0.444374800)
109(
+0.272662640,
+0.620592833E-1), (
-0.293776512,
+0.265738964)
110(
+0.778267860,
-0.425108075), (
-0.461422324,
-0.824181318)
112if (
0 /= getErrTableWrite(file, table, header
= 'col1 col2', sep
= SK_
' '))
error stop 'table write failed.'
114if (
0 /= getErrTableRead(file, table, header
= header))
error stop 'table read failed.'
118(
-0.258203268,
-0.208388209), (
-0.774918199,
-0.804242373), (
+0.511335969,
-0.402538657), (
+0.548754215,
+0.444374800)
119(
+0.272662640,
+0.620592833E-1), (
-0.293776512,
+0.265738964), (
+0.778267860,
-0.425108075), (
-0.461422324,
-0.824181318)
121if (
0 /= getErrTableRead(file, table, header
= header, sep
= SK_
' '))
error stop 'table read failed.'
125(
-0.258203268,
-0.208388209), (
-0.774918199,
-0.804242373), (
+0.511335969,
-0.402538657), (
+0.548754215,
+0.444374800)
126(
+0.272662640,
+0.620592833E-1), (
-0.293776512,
+0.265738964), (
+0.778267860,
-0.425108075), (
-0.461422324,
-0.824181318)
128if (
0 /= getErrTableWrite(file, table, trans, sep
= '|', roff
= 2_IK))
error stop 'table write failed.'
130if (
0 /= getErrTableRead(file, table, sep
= SK_
'|', roff
= 2_IK,
iomsg = iomsg))
error stop trim(iomsg)
132(
-0.258203268,
-0.208388209), (
+0.272662640,
+0.620592833E-1)
133(
-0.774918199,
-0.804242373), (
-0.293776512,
+0.265738964)
134(
+0.511335969,
-0.402538657), (
+0.778267860,
-0.425108075)
135(
+0.548754215,
+0.444374800), (
-0.461422324,
-0.824181318)
137if (
0 /= getErrTableRead(file, table, trans, sep
= SK_
'|', roff
= 2_IK))
error stop 'table read failed.'
141(
-0.258203268,
-0.208388209), (
-0.774918199,
-0.804242373), (
+0.511335969,
-0.402538657), (
+0.548754215,
+0.444374800)
142(
+0.272662640,
+0.620592833E-1), (
-0.293776512,
+0.265738964), (
+0.778267860,
-0.425108075), (
-0.461422324,
-0.824181318)
147+1.00000000,
-1.00000000
148+1.00000000,
+0.00000000
149+0.00000000,
+0.00000000
150+0.00000000,
-1.00000000
152if (
0 /= getErrTableWrite(file, table, header
= 'col1 col2', sep
= SK_
' '))
error stop 'table write failed.'
154if (
0 /= getErrTableRead(file, table, header
= header))
error stop 'table read failed.'
158+1.00000000,
-1.00000000
159+1.00000000,
+0.00000000
160+0.00000000,
+0.00000000
161+0.00000000,
-1.00000000
163if (
0 /= getErrTableRead(file, table, header
= header, sep
= SK_
' '))
error stop 'table read failed.'
167+1.00000000,
-1.00000000
168+1.00000000,
+0.00000000
169+0.00000000,
+0.00000000
170+0.00000000,
-1.00000000
172if (
0 /= getErrTableWrite(file, table, trans, sep
= '|', roff
= 2_IK))
error stop 'table write failed.'
174if (
0 /= getErrTableRead(file, table, sep
= SK_
'|', roff
= 2_IK))
error stop 'table read failed.'
176+1.00000000,
+1.00000000,
+0.00000000,
+0.00000000
177-1.00000000,
+0.00000000,
+0.00000000,
-1.00000000
179if (
0 /= getErrTableRead(file, table, trans, sep
= SK_
'|', roff
= 2_IK))
error stop 'table read failed.'
183+1.00000000,
-1.00000000
184+1.00000000,
+0.00000000
185+0.00000000,
+0.00000000
186+0.00000000,
-1.00000000
- Test:
- test_pm_io
- Todo:
- High Priority: When the user-specified
sep
contains a value other than " "
or ,
, the current implementation cannot handle the presence of new line characters within string single or double quote delimited fields in output tables of type character
.
This limitation can be fixed by tracking the delimiters while reading the contents of table
.
- Todo:
- High Priority: The
optional
input arguments deliml
delimr
must be added to allow parsing arbitrarily-delimited fields.
- Todo:
- Normal Priority: The behavior of this generic interface for empty tables is currently undefined, although the
err
code is non-zero.
This should be fixed.
- Todo:
- Normal Priority: The non-intrinsic values for the output error code
err
must be standardized.
Currently, the err
is set to -1
if an error occurs other than what is diagnosed by the compiler.
- Todo:
- Normal Priority: An
optional
input argument del
must be added to optionally delete the input file
or unit
upon successful reading of the table
.
- Todo:
- Critical Priority: In the current implementation, the behavior under an empty
sep
with trans
option present is vague and untested.
This must be clarified via testing and further improvements.
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, September 1, 2017, 12:00 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas at Austin
Definition at line 2390 of file pm_io.F90.