Description: Subroutine for reading an external file of uniform
numeric, logical or text data into an array.
For reading textual data into an array into of rank 1 or 2 and of
type integer:
call from_file(file, into [, header, delim, fmt, stat, errmsg, format, column_names])
file is of type character(len=*)header is optional and of type logicaldelim is optional and of type character(len=*)fmt is optional, may be one of INT_FMTSstat is optional and of type integererrmsg is optional and of type character(len=*)column_names is optional and of type type(String), allocatable, dimension(:)For reading textual data into an array into of rank 1 or 2 and of
type real:
call from_file(file, into [, header, locale, delim, fmt, stat, errmsg, format, column_names])
file is of type character(len=*)header is optional and of type logicallocale is optional, may be one of LOCALESdelim is optional and of type character(len=*)fmt is optional, may be one of REAL_FMTSstat is optional and of type integererrmsg is optional and of type character(len=*)column_names is optional and of type type(String), allocatable, dimension(:)For reading textual data into an array into of rank 1 or 2 and of
type complex:
call from_file(file, into [, header, locale, delim, fmt, im, stat, errmsg, format, &
column_names])
file is of type character(len=*)header is optional and of type logicallocale is optional, may be one of LOCALESdelim is optional and of type character(len=*)fmt is optional, may be one of REAL_FMTSim is optional and of type character(len=*)stat is optional and of type integererrmsg is optional and of type character(len=*)column_names is optional and of type type(String), allocatable, dimension(:)For reading textual data into an array into of rank 1 or 2 and of
type logical:
call from_file(file, into [, header, delim, fmt, stat, errmsg, format, column_names])
file is of type character(len=*)header is optional and of type logicaldelim is optional and of type character(len=*)fmt is optional, and may be "tf" (the default) or "bit"stat is optional and of type integererrmsg is optional and of type character(len=*)column_names is optional and of type type(String), allocatable, dimension(:)With fmt="tf", a cell is read as list-directed input reads a
logical: the value is the first letter, T or F in either case,
after any blanks and an optional period, so T, .true. and False
all read. With fmt="bit", a cell must be 1 or 0. Anything else,
including an empty cell, is an error that gives the cell's row and
column.
For reading textual data into an array into of rank 1 or 2 and of
type String:
call from_file(file, into [, header, delim, stat, errmsg, format, column_names])
file is of type character(len=*)header is optional and of type logicaldelim is optional and of type character(len=*)stat is optional and of type integererrmsg is optional and of type character(len=*)column_names is optional and of type type(String), allocatable, dimension(:)Each cell becomes one element, unquoted as
read_file does. Text data can only be
read from a text file, so read character data into a String array.
For reading binary data into an array into of any rank 1-15 and
of type integer, real, complex:
call from_file(file, into, data_shape [, stat, errmsg, format])
For reading a NumPy .npy file,
which records its own shape, into an array into of any rank 1-15
and of type integer, real, complex or logical:
call from_file(file, into [, stat, errmsg, format])
For reading the array name in a NumPy
.npz archive into an
array into of the same types and ranks:
call from_file(file, into [, name, stat, errmsg, format])
data_shape may also be passed for a .npy or .npz file, and must
then match the array.
file is of type character(len=*)data_shape is of type integer, dimension(:)name is optional and of type character(len=*)stat is optional and of type integererrmsg is optional and of type character(len=*)Note
file may be a relative path, but absolute paths are not
guaranteed to work on every platform.
Warning
In all cases, into must be allocatable, and will lose its
allocation status upon passing into from_file if already allocated.
As a result, from_file does not allow reading into sections of
already allocated arrays.
Note
When reading raw binary data, data_shape must be present and its
size must equal the rank of into.
Header (default is .false.): specifies whether a header line is
present.
Name: the name of the array to read from a .npz archive, as NumPy
gives it: numpy.savez("data.npz", x=x) stores x under "x". A name
ending in .npy also matches, as with numpy.load, and trailing blanks
are ignored. It may be left out when the archive holds one array. It is
an IOFL_ARG_ERR for any other file, or when the archive holds several
arrays and name is absent. npz_names lists the
names in an archive:
real, allocatable :: x(:,:)
call from_file("data.npz", into=x, name="x")
Column names: returns the header line's cells, one per column, with any
quotes around a cell removed, as read_file does. It implies
header=.true., so it may be given without header. Giving it with
header=.false., or for a .npy or .npz file, which has no header,
is an IOFL_ARG_ERR:
type(String), allocatable :: names(:)
real, allocatable :: x(:,:)
call from_file("data.csv", into=x, column_names=names) ! names(j) is the name of column j
Locales (default is "US"):
LOCALES = [ "US", "EU" ]
Delimiter: data separator. Default is a tab for a .tsv file. For
other files, it is "," for integer data and for real/complex
data with "US" locale, and ";" for real/complex data with
"EU" locale. It is always recommended to
omit the delimiter argument for default unless a custom delimiter is
really necessary. If x has rank 1 and the data is ordered down the
rows, then the delim argument is ignored.
Integer formats (default is "i"):
INT_FMTS = [ "i", "z" ]
Real formats (default is "e"):
REAL_FMTS = [ "e", "f", "z" ]
Imaginary unit: im specifies the form of a complex number. If not
present, complex numbers will be assumed to be written as ordered
pairs, e.g. (2.45,3.45).
Empty cells: an empty or blank cell in real or complex data reads as
NaN, including a cell missing from a short row. For integer data, which
has no NaN, it is an error. Any other text that is not a valid number is
an error, and errmsg gives the text with its row and column.
Format: format is optional, and may be "text", "binary", "npy" or "npz". If
it is not present, the format comes from the file extension.