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

Generate and return a full record (line) of arbitrary length as a string from the current position of the record-oriented and formatted file connected to the specified input unit. More...

Detailed Description

Generate and return a full record (line) of arbitrary length as a string from the current position of the record-oriented and formatted file connected to the specified input unit.

Parameters
[in]unit: The input scalar integer of default kind IK representing the unit of the connected file to read the line from.
[out]iostat: The output scalar integer of default kind IK.
  1. If present and no error occurs, it is set to 0 on output.
  2. If present and an end-of-file condition occurs, it is set to iostat_end from Fortran intrinsic module iso_fortran_env.
  3. If present and an error occurs (e.g., if the input argument values are wrong or inconsistent), it is set to a positive non-zero value.
  4. If missing and an error occurs (including end-of-file condition), then the program halts by calling error stop followed by the relevant error message.
(optional.)
[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. Its presence is relevant only if iostat is also present.)
[in]linefed: The input scalar logical of default kind LK.
If .true., then the output record will end with the new line character(s) as specified by the Fortran intrinsic new_line("a").
If .false., then the output record will not end with the new line character(s).
In either case, only one record will be read from the specified unit, but will or will not end with a new line character if linefed is .true. or .false. respectively.
This behavior is extremely useful for,
  1. reading records from a CSV file potentially containing new line characters in its fields.
  2. consecutively reading a series of lines of a unit into a single string by repeated calls to this generic interface while preserving the linefeed characters as record separators.
(optional, default = .false.)
Returns
record : The output allocatable scalar character of default kind SK that will contain the requested line in full.
If you suspect an end-of-file condition may occur, always specify and check the output value of iostat before using the contents of record.


Possible calling interfaces

use pm_io, only: getRecordFrom
character(:, SK), allocatable :: record
record = getRecordFrom(unit, iostat = iostat, iomsg = iomsg, linefed = linefed)
Generate and return a full record (line) of arbitrary length as a string from the current position of...
Definition: pm_io.F90:1971
This module contains classes and procedures for input/output (IO) or generic display operations on st...
Definition: pm_io.F90:252
Warning
All warnings associated with setRecordFrom also apply to the procedures under this generic interface.
Remarks
The procedures under discussion are impure.
See also
setRecordFrom
getContentsFrom
setContentsFrom
isPreconnected
getFileUnit


Example usage

1program example
2
3 use pm_kind, only: SK, IK, LK
4 use pm_io, only: getRecordFrom
5 use pm_io, only: display_type
6 use iso_fortran_env, only: iostat_end
7
8 implicit none
9
10 integer(IK) :: ub
11 integer(IK) :: unit
12 integer(IK) :: iostat
13 character(255, SK) :: iomsg
14 character( :, SK), allocatable :: record
15
16 type(display_type) :: disp
17
18 disp = display_type(file = "main.out.F90")
19
20 call disp%skip
21 call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
22 call disp%show("!Read the record-oriented (sequential access) `main.F90` file, line by line to the end.")
23 call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
24 call disp%skip
25
26 iomsg = repeat(" ", len(iomsg))
27
28 call disp%show('open(newunit = unit, file = "main.F90", status = "old")')
29 open(newunit = unit, file = "main.F90", status = "old")
30 do
31 call disp%skip
32 call disp%show("record = getRecordFrom(unit, iostat = iostat)")
33 record = getRecordFrom(unit, iostat = iostat)
34 if (iostat == 0_IK) then
35 call disp%show("record")
36 call disp%show( record , deliml = SK_"""" )
37 else
38 call disp%show("[iostat, iostat_end]")
39 call disp%show( [iostat, iostat_end] )
40 exit
41 end if
42 call disp%skip
43 end do
44
45 close(unit)
46
47end 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
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
2!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3!Read the record-oriented (sequential access) `main.F90` file, line by line to the end.
4!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
5
6open(newunit = unit, file = "main.F90", status = "old")
7
8record = getRecordFrom(unit, iostat = iostat)
9record
10"program example"
11
12
13record = getRecordFrom(unit, iostat = iostat)
14record
15""
16
17
18record = getRecordFrom(unit, iostat = iostat)
19record
20" use pm_kind, only: SK, IK, LK"
21
22
23record = getRecordFrom(unit, iostat = iostat)
24record
25" use pm_io, only: getRecordFrom"
26
27
28record = getRecordFrom(unit, iostat = iostat)
29record
30" use pm_io, only: display_type"
31
32
33record = getRecordFrom(unit, iostat = iostat)
34record
35" use iso_fortran_env, only: iostat_end"
36
37
38record = getRecordFrom(unit, iostat = iostat)
39record
40""
41
42
43record = getRecordFrom(unit, iostat = iostat)
44record
45" implicit none"
46
47
48record = getRecordFrom(unit, iostat = iostat)
49record
50""
51
52
53record = getRecordFrom(unit, iostat = iostat)
54record
55" integer(IK) :: ub"
56
57
58record = getRecordFrom(unit, iostat = iostat)
59record
60" integer(IK) :: unit"
61
62
63record = getRecordFrom(unit, iostat = iostat)
64record
65" integer(IK) :: iostat"
66
67
68record = getRecordFrom(unit, iostat = iostat)
69record
70" character(255, SK) :: iomsg"
71
72
73record = getRecordFrom(unit, iostat = iostat)
74record
75" character( :, SK), allocatable :: record"
76
77
78record = getRecordFrom(unit, iostat = iostat)
79record
80""
81
82
83record = getRecordFrom(unit, iostat = iostat)
84record
85" type(display_type) :: disp"
86
87
88record = getRecordFrom(unit, iostat = iostat)
89record
90""
91
92
93record = getRecordFrom(unit, iostat = iostat)
94record
95" disp = display_type(file = "main.out.F90")"
96
97
98record = getRecordFrom(unit, iostat = iostat)
99record
100""
101
102
103record = getRecordFrom(unit, iostat = iostat)
104record
105" call disp%skip"
106
107
108record = getRecordFrom(unit, iostat = iostat)
109record
110" call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")"
111
112
113record = getRecordFrom(unit, iostat = iostat)
114record
115" call disp%show("!Read the record-oriented (sequential access) `main.F90` file, line by line to the end.")"
116
117
118record = getRecordFrom(unit, iostat = iostat)
119record
120" call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")"
121
122
123record = getRecordFrom(unit, iostat = iostat)
124record
125" call disp%skip"
126
127
128record = getRecordFrom(unit, iostat = iostat)
129record
130""
131
132
133record = getRecordFrom(unit, iostat = iostat)
134record
135" iomsg = repeat(" ", len(iomsg))"
136
137
138record = getRecordFrom(unit, iostat = iostat)
139record
140""
141
142
143record = getRecordFrom(unit, iostat = iostat)
144record
145" call disp%show('open(newunit = unit, file = "main.F90", status = "old")')"
146
147
148record = getRecordFrom(unit, iostat = iostat)
149record
150" open(newunit = unit, file = "main.F90", status = "old")"
151
152
153record = getRecordFrom(unit, iostat = iostat)
154record
155" do"
156
157
158record = getRecordFrom(unit, iostat = iostat)
159record
160" call disp%skip"
161
162
163record = getRecordFrom(unit, iostat = iostat)
164record
165" call disp%show("record = getRecordFrom(unit, iostat = iostat)")"
166
167
168record = getRecordFrom(unit, iostat = iostat)
169record
170" record = getRecordFrom(unit, iostat = iostat)"
171
172
173record = getRecordFrom(unit, iostat = iostat)
174record
175" if (iostat == 0_IK) then"
176
177
178record = getRecordFrom(unit, iostat = iostat)
179record
180" call disp%show("record")"
181
182
183record = getRecordFrom(unit, iostat = iostat)
184record
185" call disp%show( record , deliml = SK_"""" )"
186
187
188record = getRecordFrom(unit, iostat = iostat)
189record
190" else"
191
192
193record = getRecordFrom(unit, iostat = iostat)
194record
195" call disp%show("[iostat, iostat_end]")"
196
197
198record = getRecordFrom(unit, iostat = iostat)
199record
200" call disp%show( [iostat, iostat_end] )"
201
202
203record = getRecordFrom(unit, iostat = iostat)
204record
205" exit"
206
207
208record = getRecordFrom(unit, iostat = iostat)
209record
210" end if"
211
212
213record = getRecordFrom(unit, iostat = iostat)
214record
215" call disp%skip"
216
217
218record = getRecordFrom(unit, iostat = iostat)
219record
220" end do"
221
222
223record = getRecordFrom(unit, iostat = iostat)
224record
225""
226
227
228record = getRecordFrom(unit, iostat = iostat)
229record
230" close(unit)"
231
232
233record = getRecordFrom(unit, iostat = iostat)
234record
235""
236
237
238record = getRecordFrom(unit, iostat = iostat)
239record
240"end program example"
241
242
243record = getRecordFrom(unit, iostat = iostat)
244[iostat, iostat_end]
245-1, -1
246
program main
This is main entry to the tests of the ParaMonte kernel library.
Definition: main.F90:27
Test:
test_pm_io


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, Tuesday March 7, 2017, 3:50 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas Austin

Definition at line 1971 of file pm_io.F90.


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