Home
ObjexxFCL 4.2
 

Global I/O

Overview

The ObjexxFCL global i/o system emulates Fortran's unit-based i/o. As in Fortran, i/o is tied to unit numbers that are global in the sense that i/o can be done to a unit from any function without passing a file handle object around.

The global i/o system provides, open, read, write, inquire, backspace, rewind, and close functions. Read and write use Fortran compatible formats with C++ stream i/o item syntax.

The global i/o system is layered on top of the formatted i/o system.

gio Namespace

The global i/o system lives in a gio namespace within the ObjexxFCL namespace. This is done to avoid ambiguity with C++ functions such as open and close.

The gio functions are described below. See the gio.hh source for the full set of function overloads.

open

Overloads are provided for open that accept file names in various string types and both with and without a specified unit. Opening without a unit causes an available unit number to be selected and returned by the open call.

Open modes (read, write, append, etc.) can be specified with C++ openmode or ObjexxFCL IOFlags arguments.

Here are some examples of open calls:

gio::open( 44, "MyFile.txt" ); // Open MyFile.txt on unit 44

int unit = gio::get_unit(); // Get an available unit number
gio::open( unit, "InFile.txt", std::ios_base::in ); // Open InFile.txt for reading

IOFlags flags;
int unit = gio::open( "MyData.dat", flags ); // Open MyData.dat and return the unit number
// Can check flags.ios() for status or flags.err() for error

read

Reads are done using a Fortran-compatible format specification. An IOFlags argument can be optionally used to control certain read behavior, such as setting non-advancing reads, and to return status/error flags.

If a string argument is used instead of a unit number the read is done from the string, as in a Fortran internal read.

gio::read( 52, "(2I3)" ) >> i >> j; // Reads 2 integers into i and j from unit 52

write

Writes are done using a Fortran-compatible format specification. An IOFlags argument can be optionally used to control certain write behavior, such as setting non-advancing writes, and to return status/error flags.

If a string argument is used instead of a unit number the write is done to the string, as in a Fortran internal write.

gio::write( 53, "(2I3)" ) << i << j; // Writes i and j as 2 integers to unit 53

print

Although print output does not go to a specified global unit number a print function is provided in gio that uses the same format support as write.

gio::print( "(2I3)" ) << i << j; // Writes i and j as 2 integers to stdout

inquire

The inquire calls support the essential queries of Fortran's INQUIRE statement. As in Fortran, you can inquire by unit number or file name.

An IOFlags argument is used to return information about the unit or named file: after running inquire the flags object can be queried for information such as whether the file exists or is open, the file size, and so forth.

IOFlags flags;
gio::inquire( 22, flags );
// flags.name() gives the file name
// flags.open() tells you if the file is currently open
// flags.write() tells you if the file is open for writing

backspace

The backspace call moves the i/o position in the file associated with the specified unit back by one record (line). An IOFlags argument can be added to get status/error information about the backspace call.

gio::backspace( 66 ); // Back up by one line on unit 66

rewind

The rewind call moves the i/o position in the file associated with the specified unit to the beginning of the file. An IOFlags argument can be added to get status/error information about the rewind call.

gio::rewind( 66 ); // Rewind back to the beginning on unit 66

close

A file opened on a global unit can be closed, with an optional IOFlags argument to set controls, such as delete, and to return status/error flags.

gio::close( 77 );
IOFlags flags;
gio::close( 88, flags );