pm_io Module Reference

This module contains classes and procedures for input/output (IO) or generic display operations on standard displays or internal/external files. More...

Data Types
type	csv_type
	This is a concrete derived type whose instances are exclusively used to signify the CSV file form within an interface of a procedure of the ParaMonte library. More...
type	display_type
	Generate and return an object of type display_type. More...
type	field_type
	The derived type that can be used for constructing containers of format or left and right delimiters for the (five) intrinsic Fortran field types. More...
type	filext_type
	This is the derived type for generating objects containing the source file extensions used by different programming language environments. More...
type	fld_type
	This is a concrete derived type whose instances are exclusively used to signify the Fortran-list-directed file form within an interface of a procedure of the ParaMonte library. More...
type	form_type
	This is an abstract derived type for constructing concrete derived types to distinguish various procedure signatures that require different file forms (e.g., csv, binary, ...). More...
type	formatted_type
	This is a concrete derived type whose instances are exclusively used to signify the formatted file form within an interface of a procedure of the ParaMonte library. More...
interface	getAction
	Generate and return the action attribute of the input file or unit. More...
interface	getContentsFrom
	Generate and return the entire contents of the input unconnected file or the (remaining) contents of an already-connected file associated with the input unit. More...
interface	getCountRecord
	Generate and return the number of records in the entire record-oriented input file. More...
interface	getCountRecordLeft
	Generate and return the number of records left (starting immediately after the last accessed record) in the record-oriented input file. More...
interface	getErrTableRead
	Generate and return the iostat code resulting from reading the contents of the specified file or unit into an output table. More...
interface	getErrTableWrite
	Generate and return the iostat code resulting from writing the input table of rank 1 or 2 to the specified output. More...
interface	getFieldSep
	Generate and return the best-guess field separator of a (sequential-access) file stored in the input file. More...
interface	getFormat
	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...
interface	getRecordFrom
	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...
interface	isOpen
	Generate and return .true. if the input file (or unit) is connected to a unit (or file), and .false. otherwise. More...
interface	openArg_type
	This is the openArg_type class containing arguments that can be passed to the open() intrinsic Fortran statement. More...
interface	setContentsFrom
	Return the entire contents of the input unconnected file or the (remaining) contents of an already-connected file associated with the input unit. More...
interface	setContentsTo
	Write the input string contents to the input unconnected file. More...
interface	setFileClosed
	Open the given input file, fetch the entire contents return it as a single allocatable string, and close the file. More...
interface	setRecordFrom
	Read 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...
interface	show
	This is a generic method of the derived type display_type with pass attribute. More...
interface	skip
	This is a generic method of the derived type display_type with pass attribute. More...
type	unformatted_type
	This is a concrete derived type whose instances are exclusively used to signify the unformatted (binary) file form within an interface of a procedure of the ParaMonte library. More...
type	unknown_type
	This is a concrete derived type whose instances are exclusively used to signify the unknown file form within an interface of a procedure of the ParaMonte library. More...
interface	wrap
	This is a generic method of the derived type display_type with pass attribute. More...
type	wrap_type
	This is the derived type for constructing objects that contain the specifications of the getStrWrapped dynamic method of objects of derived type wrap_type. More...

Functions/Subroutines
pure logical(LK) function	isValidAccess (value)
pure logical(LK) function	isValidAction (value)
pure logical(LK) function	isValidAsynchronous (value)
pure logical(LK) function	isValidBlank (value)
pure logical(LK) function	isValidDecimal (value)
pure logical(LK) function	isValidDelim (value)
pure logical(LK) function	isValidEncoding (value)
pure logical(LK) function	isValidForm (value)
pure logical(LK) function	isValidPad (value)
pure logical(LK) function	isValidPosition (value)
pure logical(LK) function	isValidRecl (value)
pure logical(LK) function	isValidRound (value)
pure logical(LK) function	isValidSign (value)
pure logical(LK) function	isValidStatus (value)
pure elemental logical(LK) function	isPreconnected (unit)
	Generate and return .true. if the input unit corresponds to one of the processor preconnected units: output_unit, input_unit, error_unit, otherwise return .false.. More...
impure elemental integer(IK) function	getFileUnit (file)
	Generate and return a random new unconnected file unit number that could be assigned to the unit specifier of the Fortran intrinsic open statement. Optionally, return the unit number of a file whose path is given by the input argument file. More...

Variables
character(*, SK), parameter	MODULE_NAME = "@pm_io"
type(filext_type), parameter	filext = filext_type()
	The scalar constant object of type filext_type containing file extensions used by different programming language environments. More...
character(*, SK), parameter	MFILL = SK_"%"
	The scalar character of default kind SK of len = 1 representing the default string that is used for filling the margins of the display or wrapped texts. More...
character(1, SK), parameter	TAB = achar(9, SK)
	The scalar character of default kind SK of len = 4 representing representing ASCII character: Horizontal Tab, which is frequently used in external files as column or field separators. More...
character(*, SK), parameter	TABEQV = repeat(SK_" ", 4)
	The scalar character of default kind SK of len = 4 representing the default string that is used in place of the tab character in the display. More...
character(*, SK), parameter	INDENT = TABEQV
	The scalar character of default kind SK of the same value as TABEQV representing the default indentation of text in the display, when indentation is needed. More...
character(*, SK), parameter	FORMAT_GENERIC_BLANK = SK_"(*(g0,:,' '))"
	The scalar character of default kind SK containing the generic IO whitespace-separated IO format. More...
character(*, SK), parameter	FORMAT_GENERIC_BLANK_TABBED = SK_"('"//INDENT//SK_"',*(g0,:,' '))"
	The scalar character of default kind SK containing the generic IO whitespace-separated IO format with in an initial INDENT. More...
character(*, SK), parameter	FORMAT_GENERIC_DISPLAY = SK_"(sp,*(g0,:,', '))"
	The scalar character of default kind SK containing the generic signed comma-space-separated format used as the default within objects of display_type. More...
character(*, SK), parameter	FORMAT_GENERIC_DISPLAY_COMPLEX_MATH = SK_"(sp,*(2g0,'i',:,', '))"
	The scalar character of default kind SK containing the generic signed comma-space-separated format that can be used as the math-style complex formatting when constructing objects of display_type. More...
character(*, SK), parameter	FORMAT_GENERIC_DISPLAY_COMPLEX_FORTRAN = SK_"(sp,*('(',g0,', ',g0,')',:,', '))"
	The scalar character of default kind SK containing the generic signed comma-space-separated format that can be used as the Fortran-style complex formatting when constructing objects of display_type. More...
character(1, SK), dimension(4), parameter	SPINNER = [ "|" , "/" , "-" , "\" ]
	The scalar character(1, SK) of default kind SK of size 4, containing the four characters used to display a spinning command line cursor. More...
integer(IK), parameter	LEN_IOMSG = 511_IK
	The scalar integer of default kind IK representing the maximum length of an IO error message returned by the Fortran intrinsic routines. Note that this an arbitrary length defined globally for consistency. More...
integer(IK), parameter	LEN_RECORD = 8191_IK
	The scalar integer of default kind IK representing the effective maximum length of a record in a record-oriented file. Note that this is an arbitrary length defined globally for consistency. More...
type(unknown_type), parameter	unknown = unknown_type()
	This is a scalar parameter object of type unknown_type that is exclusively used to signify the unknown file form within an interface of a procedure of the ParaMonte library. More...
type(unformatted_type), parameter	unformatted = unformatted_type()
	This is a scalar parameter object of type unformatted_type that is exclusively used to signify the unformatted (binary) file form within an interface of a procedure of the ParaMonte library. More...
type(formatted_type), parameter	formatted = formatted_type()
	This is a scalar parameter object of type formatted_type that is exclusively used to signify the formatted file form within an interface of a procedure of the ParaMonte library. More...
type(csv_type), parameter	csv = csv_type()
	This is a scalar parameter object of type csv_type that is exclusively used to signify the CSV file form within an interface of a procedure of the ParaMonte library. More...
type(fld_type), parameter	fld = fld_type()
	This is a scalar parameter object of type fld_type that is exclusively used to signify the Fortran-list-directed file form within an interface of a procedure of the ParaMonte library. More...
type(display_type)	disp
	This is a scalar module variable an object of type display_type for general display. More...

Detailed Description

This module contains classes and procedures for input/output (IO) or generic display operations on standard displays or internal/external files.

Quick start

The following is a (non-exhaustive) list of the most useful functionalities in this module:

1. display_type is a derived type for creating objects whose methods (show, wrap, skip, ...) can display all sorts of scalar and array objects of intrinsic type and kind as well as containers of various intrinsic types and kinds.
   
2. getContentsFrom and setContentsFrom are functional and subroutine interfaces for reading the entire contents of a given file or connect unit into a scalar string.
   
3. getErrTableWrite writes a data matrix as a csv, list-directed or other arbitrarily-delimited table of data to a specified file or unit.
   
4. getErrTableRead reads a csv, list-directed or other arbitrarily-delimited table of data from a specified file or unit.
   
5. getCountRecord counts the number of records (optionally matching a user-specified pattern) in a sequential access file or unit.
   
6. getCountRecordLeft counts the number of records left, optionally matching a user-specified pattern, in a sequential access connected-file unit.
   
7. getRecordFrom and setRecordFrom read a single line from a specified sequential access file or unit into an allocatable string.
   
8. getFieldSep identifies the most likely separator used in a file to separate fields of a record-oriented file from a list of possible separators of arbitrary length.
   
9. getFormat seamlessly creates a suitable format for outputting a record of fields of arbitrary type and kind, each field of which can be delimited and optionally contain multiple subfields.
   
10. setContentsTo outputs a scalar string to an unconnected file as a binary stream.
    
11. isOpen checks if a file or unit is already connected (opened).
    

12. etc.
    

IO terminology

The following is a collection of terms and phrases frequently used in the documentation of this module.

1. A file is a logical unit of information created by processes and are managed by the operating system.
   
2. The part of the operating system that deals with files is known as the file system.
   
3. An I/O record is a collection of characters or values that are logically related and are frequently processed together.
   Three common types of records are:
   
   1. formatted
      1. A formatted record consists of a sequence of ASCII characters that can print in a readable format.
      2. Reading a formatted record converts the data values from readable characters into an internal representation.
      3. Writing a formatted record converts the data from the internal representation into characters.
   2. unformatted
      1. An unformatted record contains a sequence of values in an internal representation that can contain both character and noncharacter data.
      2. Reading or writing an unformatted record does not convert any data the record contains from the internal representation.
      3. An unformatted record can also contain no data.
   3. endfile
      1. If it exists, an endfile record is the last record of a file.
      2. The endfile record has no length.
      3. The endfile record can be written explicitly by the endfile() Fortran intrinsic statement.
      4. The endfile record can be written implicitly to a file connected for sequential access when,
         1. the last data transfer statement was a write() statement,
         2. no intervening file positioning statement referring to the file has been executed,
         3. and the following is true:
            1. A rewind() or backspace() statement references the unit to which the file is connected; or
            2. The file is closed, either
               
               1. explicitly by a close() statement, or
                  
               2. implicitly by a program termination not caused by an error condition, or
                  
               3. implicitly by another open() statement for the same unit.
                  
4. File organization refers to the way records are physically arranged on a storage device.
   
   1. The main types of file organization in Fortran are the following,
      
      1. Sequential
         
         1. A sequentially organized file consists of records arranged in the sequence in which they are written to the file.
         2. As a result, records can be added only at the end of the file.
         3. Attempting to add records at some place other than the end of the file will result in the file begin truncated at the end of the record just written.
         4. Sequential files can be stored on magnetic tape or disk devices.
            
         5. Other peripheral devices, such as terminals, pipes, and line printers as sequential files.
         6. Sequential files are usually read sequentially, starting with the first record in the file.
         7. Sequential files with a fixed-length record-type stored on disk can also be accessed by relative record number (direct access).
      2. Relative (direct access)
         
         1. Relative files are just like arrays [of structures], but instead of residing in the main memory, they are recorded on a disk device.
         2. Relative files can only be stored on a disk device (e.g., not on magnetic tapes).
         3. Within a relative file are numbered positions, called cells.
         4. These cells are of fixed equal length and are consecutively numbered from 1 to n, corresponding to the first and last cells in the file.
         5. Each cell either contains either a single record or is empty.
         6. Records in a relative file are accessed according to the cell number.
         7. The cell number is the record number relative to the beginning of the file.
         8. By specifying relative record numbers, one can directly retrieve, add, or delete records regardless of their locations.
         9. When creating a relative file, the RECL can be inquired to determine the size of the fixed-length cells.
         10. Within the cells, one can store records of varying length, as long as their size does not exceed the cell size.
      3. Indexed (not in the Fortran standard)
         
         1. An indexed file is made of "data cells", not necessarily of the same size, and contain indexes, lists of pointers to these cells arranged by some order.
         2. The Fortran Standard does not require support for indexed files (although some compilers do).
            
5. The two major types of file systems are the following:
   
   1. A stream of bytes (byte Sequence) known as the stream access in Fortran.
      
   2. A stream of records (record sequence).
      Depending on the lengths of individual record in the file, two separate internal structures are commonly used.
      
      1. A stream of equal-length records, also known as the direct access files in Fortran.
         The position in the direct access file in Fortran is specified in terms of records.
         All records have the same length (specified by the RECL= specifier in call to open() statement).
         For example, if a file contains 20 records and has record length equal to 30, then
         
         1. the total size of data the program can access from the file is 600 bytes and,
            
         2. every read or write operation will access a record containing 30 bytes.
            
      2. A stream of arbitrary-length records, also known as the sequental access files in Fortran.
         
6. The record-type refers to the convention used for storing fields in records.
   The record-type of the data within a file is not maintained as an attribute of the file.
   The results of using a record type other than the one used to create the file are indeterminate.
   
7. The record overhead is the number of bytes associated with each record used internally by the file system and are not available when a record is read or written.
8. The following table list the commonly available record types.

   Record Type	Available File Organizations and Portability Considerations	Record Overhead
   Fixed-length	Relative or sequential file organizations.	None for sequential.
   Variable-length	Sequential file organization only.	Eight bytes per record. The most portable record type.
   Stream	Sequential file organization only. No record terminator needed.	zero.
   Stream_CR	Sequential file organization only. It uses CR (carriage return) as record terminator.	One byte per record.
   Stream_LF	Sequential file organization only. It uses LF (line feed) as record terminator).	One byte per record.
   Stream_CRLF	Sequential file organization only. It uses both CR and LF as record terminator.	Two bytes per record.

   Given the above record overheads, stream record type yields the smallest possible file sizes.
9. Fixed-Length Records require that all records in the file contain the same number of bytes.
   When a file is opened to contain fixed-length records, the record size must be specified using the RECL specified of the open() statement.
   A sequentially-organized opened file for direct access must contain fixed-length records to allow the record position in the file to be computed correctly.
10. Variable-Length Records can contain any number of bytes up to a specified maximum record length and apply only to sequential files.
    Variable-length records are prefixed and suffixed by 4 bytes of control information containing length fields.
    The trailing length field allows a backspace() request to skip back over records efficiently.
    The 4-byte integer value stored in each length field indicates the number of data bytes (excluding overhead bytes) in that particular variable-length record.
    For a record length greater than 2,147,483,639 bytes, the record is divided into subrecords. The subrecord can be of any length from 1 to 2,147,483,639, inclusive.
    The sign bit of the leading length field indicates whether the record is continued or not.
    The sign bit of the trailing length field indicates the presence of a preceding subrecord.
    The position of the sign bit is determined by the endian format of the file.
    The following rules describe sign bit values:
    1. A subrecord that is continued has a leading length field with a sign bit value of 1.
    2. The last subrecord that makes up a record has a leading length field with a sign bit value of 0.
    3. A subrecord that has a preceding subrecord has a trailing length field with a sign bit value of 1.
    4. The first subrecord that makes up a record has a trailing length field with a sign bit value of 0.
    5. If the value of the sign bit is 1, the length of the record is stored in twos-complement notation.
11. Stream files contain no control information and their contents is not grouped into records.
    
    1. Stream-access I/O is a method of accessing a file without reference to a record structure.
       
    2. With stream access, a file is seen as a continuous sequence of bytes and is addressed by a positive integer starting from 1.
       
    3. To enable stream access, one should specify access = "stream" in the open() statement for the file.
       
    4. A file enabled for stream access is positioned by file storage units (normally bytes) starting at position 1.
       
    5. To determine the current position, one must use the pos specifier in an inquire() statement for the unit.
       
    6. One can also indicate a required position in a read or write statement with a pos specifier.
       
    7. Stream files can contain character or binary data that is read or written only to the extent of the variables specified on the input or output statement.
    8. Stream files can be connected to external files for stream access as either formatted or unformatted.
    9. Both formatted and unformatted forms use external stream files composed of one byte file storage units.
    10. A file connected for unformatted stream access has only a stream structure.
    11. By contrast, files connected for formatted stream access have both a record and a stream structure.
    12. These dual structure files have the following characteristics:
        1. Some file storage units represent record markers.
        2. The record structure is inferred from the record markers stored in the file.
        3. There is no theoretical limit on record length.
        4. Writing an empty record without a record marker has no effect.
        5. If there is no record marker at the end of a file, the final record is incomplete but not empty.
        6. The endfile record in a file previously connected for sequential access is not considered part of the file when you connect that file for stream access.
    13. When connected for formatted stream access, an external file has the following characteristics:
        1. The first file storage unit in the file is at position 1.
        2. The relationship between positions of successive file storage units is processor dependent; not all positive integers need to correspond to valid positions.
        3. Some file storage units may contain record markers that impose a record structure on the file in addition to its stream structure.
        4. If there is no record marker at the end of the file, the final record is incomplete. Writing an empty record with no record marker has no effect.
    14. When connected for unformatted stream access, an external file has the following characteristics:
        1. The first file storage unit in the file is at position 1.
        2. The position of each subsequent file storage unit is one greater than the position of the preceding file storage unit.
        3. If it is possible to position the file, the file storage units do not need to be read or written in order of their position.
        4. For example, you may be able to write the file storage unit at position 2, even though the file storage unit at position 1 has not been written.
        5. Any file storage unit can be read from the file while it is connected to a unit, if the file storage unit has been written since the file was created, and a read() statement for this connection is allowed.
        6. One cannot use backspace() in an unformatted stream.
12. Sequential-access files can be either internal and external files.
    1. Internal files
       1. An internal file always has sequential access.
       2. An internal file is a character variable that is not an array section with a vector subscript.
       3. If an internal file is a scalar character variable, the file consists of one record with a length equal to that of the scalar variable.
       4. If an internal file is a character array, each element of the array is a record of the file, with each record having the same length.
       5. An internal file must contain only formatted records. read() and write() are the only statements that can specify an internal file.
       6. If a write() statement writes less than an entire record, blanks fill the remainder of that record.
    2. External files
       1. A file connected for sequential access contains records in the order they were written.
       2. The records must be either all formatted or all unformatted.
       3. The last record of the file must be an endfile record.
       4. The records must not be read or written by direct or stream access I/O statements as long as the file is connected for sequential access.
13. Direct-access files allow the records of an external file to be read or written in any order.
    1. The records must be either all formatted or all unformatted.
    2. The records must not be read or written using sequential or stream access, list-directed or namelist formatting, or a nonadvancing input/output statement.
    3. If the file was previously connected for sequential access, the last record of the file is an endfile record.
    4. The endfile record is not considered a part of the file connected for direct access.
    5. Each record in a file connected for direct access has a record number that identifies its order in the file.
    6. The record number is an integer value that must be specified when the record is read or written.
    7. Records are numbered sequentially. The first record is number 1.
    8. Records need not be read or written in the order of their record numbers. For example, records 9, 5, and 11 can be written in that order without writing the intermediate records.
    9. All records in a file connected for direct access must have the same length, which is specified in the open() statement when the file is connected.
    10. Records in a file connected for direct access cannot be deleted, but they can be rewritten with a new value.
    11. A record cannot be read unless it has first been written.

Note

There are a number of other points to note with respect to files.

1. The set of allowed names for a file is processor dependent.
2. Both sequential and direct access may be available for some files, but normally a file is limited to sequential, direct, or stream access.
3. A file never contains both formatted and unformatted records.

Typical file operations that are also partly covered in this module and partly in pm_sysPath are,

1. Create
2. Delete
3. Open
4. Close
5. Read
6. Write
7. Append (This call is a restricted form of write. It can add data only to the end of the file.)
8. Seek (Repositions the file pointer to a specific place in the file.)
9. Get Attributes (Processes often need to read file attributes to do their work.)
10. Set Attributes (Some of the attributes are user settable and can be changed after the file has been created.)
11. Rename (changes the name of the file.)

Previous versions of this modules contained functions for inquiring various attributes of files via the intrinsic inquire() statement.
The current version has deprecated and deleted all such functions as their maintenance is more costly than any potential benefits they may offer.
Such functions cannot be pure due to the call to the inquire() statement. As such, they are unlikely to be inlined by the compiler.
Furthermore, any call to such functions from outside their parent module requires a use statement, followed by the function call, which effectively yields the same amount of verbosity caused by directly calling the inquire() statement.
Additionally, a single call to the Fortran inquire() statement can return multiple attributes of a file or unit, which makes this statement much more concise and efficient as opposed to any user-defined function.

See also

IBM documentation of Fortran File access methods
Intel documentation of Fortran File access methods
Intel Fortran compiler documentation for OPEN - RECL Specifier
Metcalf et al., Modern Fortran Explained - Incorporating Fortran 2018
Files and records

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.

Copyright

Computational Data Science Lab

Author:

Amir Shahmoradi, Tuesday March 7, 2017, 3:50 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas at Austin

Function/Subroutine Documentation

getFileUnit()

impure elemental integer(IK) function pm_io::getFileUnit

(

character(*, SK), intent(in), optional

file

)

Generate and return a random new unconnected file unit number that could be assigned to the unit specifier of the Fortran intrinsic open statement. Optionally, return the unit number of a file whose path is given by the input argument file.

The behavior of this generic interface is fully dictated by the Fortran intrinsic inquire() when the optional argument file is present.
For example, if the optional argument is present but no unit is connected to the file or the file does not exists, the unit returned is -1.

Parameters

[in]

file

: The input scalar of type character of default kind SK representing the path of the file whose unit is to be returned, if it is already opened. (optional, if missing, a new unit number, that is not connected to any file, will be returned.)

Returns

unit : The output scalar of type integer of default kind IK containing

1. the unit number of the input file if it exists and is already connected.
   
2. the value -1 if the input argument file is present but does not exist or is not already connected.
   
3. a valid random unit number that is not connected to any existing file, if the input argument file is missing.
   

Possible calling interfaces ⛓

use pm_io, only: getFileUnit
 
unit = getFileUnit()
unit = getFileUnit(file)

Warning

As per the Fortran standard, if no unit is connected to the input file, a value of -1 will be returned.

Remarks

The procedures under discussion are impure.

The procedures under discussion are elemental.

This procedure is primarily useful for bypassing the existing bug in the Intel Fortran compiler with the newunit specifier of the open statement.

See also

isPreconnected

Example usage ⛓

program example
 
    use pm_kind, only: SK, IK, LK
    use pm_io, only: display_type
    use pm_io, only: getFileUnit
 
    implicit none
 
    type(display_type) :: disp
 
    disp = display_type(file = "main.out.F90")
 
    call disp%skip
    call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
    call disp%show("!Get the unit of a file that is already opened.")
    call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
    call disp%skip
 
    call disp%skip
    call disp%show("open(unit = 11, file = 'temp.tmp')")
                    open(unit = 11, file = 'temp.tmp')
    call disp%show("getFileUnit('temp.tmp')")
    call disp%show( getFileUnit('temp.tmp') )
    call disp%show("close(unit = 11)")
                    close(unit = 11)
    call disp%skip
 
    call disp%skip
    call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
    call disp%show("!Get the units of multiple files.")
    call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
    call disp%skip
 
    call disp%skip
    call disp%show("open(unit = 11, file = 'temp.tmp')")
                    open(unit = 11, file = 'temp.tmp')
    call disp%show("getFileUnit(['temp.tmp', 'tmp.temp']) ! The second file is not connected., yielding a unit of `-1`.")
    call disp%show( getFileUnit(['temp.tmp', 'tmp.temp']) )
    call disp%show("close(unit = 11)")
                    close(unit = 11)
    call disp%skip
 
    call disp%skip
    call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
    call disp%show("!Get a new unique unit number for use in an `open()` statement.")
    call disp%show("!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%")
    call disp%skip
 
    call disp%skip
    call disp%show("getFileUnit()")
    call disp%show( getFileUnit() )
    call disp%skip
 
end program example

Example Unix compile command via Intel ifort compiler ⛓

#!/usr/bin/env sh
rm main.exe
ifort -fpp -standard-semantics -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe
./main.exe

Example Windows Batch compile command via Intel ifort compiler ⛓

del main.exe
set PATH=..\..\..\lib;%PATH%
ifort /fpp /standard-semantics /O3 /I:..\..\..\include main.F90 ..\..\..\lib\libparamonte*.lib /exe:main.exe
main.exe

Example Unix / MinGW compile command via GNU gfortran compiler ⛓

#!/usr/bin/env sh
rm main.exe
gfortran -cpp -ffree-line-length-none -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe
./main.exe

Example output ⛓

 
!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
!Get the unit of a file that is already opened.
!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 
open(unit = 11, file = 'temp.tmp')
getFileUnit('temp.tmp')
+11
close(unit = 11)
 
 
!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
!Get the units of multiple files.
!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 
open(unit = 11, file = 'temp.tmp')
getFileUnit(['temp.tmp', 'tmp.temp']) ! The second file is not connected., yielding a unit of `-1`.
+11, -1
close(unit = 11)
 
 
!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
!Get a new unique unit number for use in an `open()` statement.
!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 
getFileUnit()
+100
 
 

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.

Copyright

Computational Data Science Lab

Author:

Amir Shahmoradi, Tuesday March 7, 2017, 3:50 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas at Austin

Definition at line 19434 of file pm_io.F90.

isPreconnected()

pure elemental logical(LK) function pm_io::isPreconnected

(

integer(IK), intent(in)

unit

)

Generate and return .true. if the input unit corresponds to one of the processor preconnected units: output_unit, input_unit, error_unit, otherwise return .false..

Parameters

[in]

unit

: The input scalar of type integer of default kind IK representing the unit number to be tested.

Returns

preconnected : The output scalar of type logical of default kind LK representing that is .true. if and only if the input unit corresponds to one of the preconnected units by the processor.

Possible calling interfaces ⛓

use pm_kind, only: IK
use pm_io, only: isPreconnected
logical(LK) :: preconnected
integer(IK) :: unit
 
preconnected = isPreconnected(unit)

Remarks

The procedures under discussion are pure.

The procedures under discussion are elemental.

If no unit is connected to the input file, a value of -1 will be returned.

This procedure is primarily useful for bypassing the existing bug in Intel Fortran compiler with the newunit specifier of the open statement.

See also

getFileUnit

Example usage ⛓

program example
 
    use pm_kind, only: SK, IK, LK
    use pm_io, only: display_type
    use iso_fortran_env, only: input_unit, output_unit, error_unit
    use pm_io, only: isPreconnected
 
    implicit none
 
    type(display_type) :: disp
 
    disp = display_type(file = "main.out.F90")
 
    call disp%skip
    call disp%show("open(unit = 11, file = 'temp.tmp')")
                    open(unit = 11, file = 'temp.tmp')
    call disp%show("isPreconnected(11_IK)")
    call disp%show( isPreconnected(11_IK) )
    call disp%show("close(unit = 11)")
                    close(unit = 11)
    call disp%skip
 
    call disp%skip
    call disp%show("isPreconnected([integer(IK) :: input_unit, output_unit, error_unit])")
    call disp%show( isPreconnected([integer(IK) :: input_unit, output_unit, error_unit]) )
    call disp%skip
 
end program example

Example Unix compile command via Intel ifort compiler ⛓

#!/usr/bin/env sh
rm main.exe
ifort -fpp -standard-semantics -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe
./main.exe

Example Windows Batch compile command via Intel ifort compiler ⛓

del main.exe
set PATH=..\..\..\lib;%PATH%
ifort /fpp /standard-semantics /O3 /I:..\..\..\include main.F90 ..\..\..\lib\libparamonte*.lib /exe:main.exe
main.exe

Example Unix / MinGW compile command via GNU gfortran compiler ⛓

#!/usr/bin/env sh
rm main.exe
gfortran -cpp -ffree-line-length-none -O3 -Wl,-rpath,../../../lib -I../../../inc main.F90 ../../../lib/libparamonte* -o main.exe
./main.exe

Example output ⛓

 
open(unit = 11, file = 'temp.tmp')
isPreconnected(11_IK)
F
close(unit = 11)
 
 
isPreconnected([integer(IK) :: input_unit, output_unit, error_unit])
T, T, T
 
 

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.

Copyright

Computational Data Science Lab

Author:

Amir Shahmoradi, Tuesday March 7, 2017, 3:50 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas at Austin

Definition at line 19364 of file pm_io.F90.

isValidAccess()

pure logical(LK) function pm_io::isValidAccess

(

character(*, SK), intent(in)

value

)

Definition at line 19203 of file pm_io.F90.

isValidAction()

pure logical(LK) function pm_io::isValidAction

(

character(*, SK), intent(in)

value

)

Definition at line 19211 of file pm_io.F90.

isValidAsynchronous()

pure logical(LK) function pm_io::isValidAsynchronous

(

character(*, SK), intent(in)

value

)

Definition at line 19219 of file pm_io.F90.

isValidBlank()

pure logical(LK) function pm_io::isValidBlank

(

character(*, SK), intent(in)

value

)

Definition at line 19227 of file pm_io.F90.

isValidDecimal()

pure logical(LK) function pm_io::isValidDecimal

(

character(*, SK), intent(in)

value

)

Definition at line 19235 of file pm_io.F90.

isValidDelim()

pure logical(LK) function pm_io::isValidDelim

(

character(*, SK), intent(in)

value

)

Definition at line 19243 of file pm_io.F90.

isValidEncoding()

pure logical(LK) function pm_io::isValidEncoding

(

character(*, SK), intent(in)

value

)

Definition at line 19251 of file pm_io.F90.

isValidForm()

pure logical(LK) function pm_io::isValidForm

(

character(*, SK), intent(in)

value

)

Definition at line 19259 of file pm_io.F90.

isValidPad()

pure logical(LK) function pm_io::isValidPad

(

character(*, SK), intent(in)

value

)

Definition at line 19267 of file pm_io.F90.

isValidPosition()

pure logical(LK) function pm_io::isValidPosition

(

character(*, SK), intent(in)

value

)

Definition at line 19275 of file pm_io.F90.

isValidRecl()

pure logical(LK) function pm_io::isValidRecl

(

integer(IK), intent(in)

value

)

Definition at line 19283 of file pm_io.F90.

isValidRound()

pure logical(LK) function pm_io::isValidRound

(

character(*, SK), intent(in)

value

)

Definition at line 19291 of file pm_io.F90.

isValidSign()

pure logical(LK) function pm_io::isValidSign

(

character(*, SK), intent(in)

value

)

Definition at line 19299 of file pm_io.F90.

isValidStatus()

pure logical(LK) function pm_io::isValidStatus

(

character(*, SK), intent(in)

value

)

Definition at line 19307 of file pm_io.F90.

Variable Documentation

csv

type(csv_type), parameter pm_io::csv = csv_type()

This is a scalar parameter object of type csv_type that is exclusively used to signify the CSV file form within an interface of a procedure of the ParaMonte library.

For example usage, see the documentation of the target procedure requiring this object.

See also

csv
fld
unknown
csv_type
fld_type
form_type
formatted
unformatted
unknown_type
formatted_type
unformatted_type

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.

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 787 of file pm_io.F90.

disp

type(display_type) pm_io::disp

This is a scalar module variable an object of type display_type for general display.

The existence of this object is to merely facilitate quick tests and displays of items on the default stdout.
Given the global nature of this object, its usage is not recommended beyond simple tests and debugging tasks.

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.

Copyright

Computational Data Science Lab

Author:

Amir Shahmoradi, Tuesday March 7, 2017, 3:50 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas at Austin

Definition at line 11393 of file pm_io.F90.

filext

type(filext_type), parameter pm_io::filext = filext_type()

The scalar constant object of type filext_type containing file extensions used by different programming language environments.

See also

filext_type

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.

Copyright

Computational Data Science Lab

Author:

Amir Shahmoradi, September 1, 2017, 11:35 PM, Institute for Computational Engineering and Sciences (ICES), The University of Texas at Austin

Definition at line 316 of file pm_io.F90.

fld

type(fld_type), parameter pm_io::fld = fld_type()

This is a scalar parameter object of type fld_type that is exclusively used to signify the Fortran-list-directed file form within an interface of a procedure of the ParaMonte library.

For example usage, see the documentation of the target procedure requiring this object.

See also

csv
fld
unknown
csv_type
fld_type
form_type
formatted
unformatted
unknown_type
formatted_type
unformatted_type

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.

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 852 of file pm_io.F90.

FORMAT_GENERIC_BLANK

character(*, SK), parameter pm_io::FORMAT_GENERIC_BLANK = SK_"(*(g0,:,' '))"

The scalar character of default kind SK containing the generic IO whitespace-separated IO format.

Definition at line 357 of file pm_io.F90.

FORMAT_GENERIC_BLANK_TABBED

character(*, SK), parameter pm_io::FORMAT_GENERIC_BLANK_TABBED = SK_"('"//INDENT//SK_"',*(g0,:,' '))"

The scalar character of default kind SK containing the generic IO whitespace-separated IO format with in an initial INDENT.

Definition at line 364 of file pm_io.F90.

FORMAT_GENERIC_DISPLAY

character(*, SK), parameter pm_io::FORMAT_GENERIC_DISPLAY = SK_"(sp,*(g0,:,', '))"

The scalar character of default kind SK containing the generic signed comma-space-separated format used as the default within objects of display_type.

Definition at line 371 of file pm_io.F90.

FORMAT_GENERIC_DISPLAY_COMPLEX_FORTRAN

character(*, SK), parameter pm_io::FORMAT_GENERIC_DISPLAY_COMPLEX_FORTRAN = SK_"(sp,*('(',g0,', ',g0,')',:,', '))"

The scalar character of default kind SK containing the generic signed comma-space-separated format that can be used as the Fortran-style complex formatting when constructing objects of display_type.

Definition at line 387 of file pm_io.F90.

FORMAT_GENERIC_DISPLAY_COMPLEX_MATH

character(*, SK), parameter pm_io::FORMAT_GENERIC_DISPLAY_COMPLEX_MATH = SK_"(sp,*(2g0,'i',:,', '))"

The scalar character of default kind SK containing the generic signed comma-space-separated format that can be used as the math-style complex formatting when constructing objects of display_type.

Definition at line 379 of file pm_io.F90.

formatted

type(formatted_type), parameter pm_io::formatted = formatted_type()

This is a scalar parameter object of type formatted_type that is exclusively used to signify the formatted file form within an interface of a procedure of the ParaMonte library.

For example usage, see the documentation of the target procedure requiring this object.

See also

csv
fld
unknown
csv_type
fld_type
form_type
formatted
unformatted
unknown_type
formatted_type
unformatted_type

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.

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 722 of file pm_io.F90.

INDENT

character(*, SK), parameter pm_io::INDENT = TABEQV

The scalar character of default kind SK of the same value as TABEQV representing the default indentation of text in the display, when indentation is needed.

Definition at line 350 of file pm_io.F90.

LEN_IOMSG

integer(IK), parameter pm_io::LEN_IOMSG = 511_IK

The scalar integer of default kind IK representing the maximum length of an IO error message returned by the Fortran intrinsic routines. Note that this an arbitrary length defined globally for consistency.

Definition at line 401 of file pm_io.F90.

LEN_RECORD

integer(IK), parameter pm_io::LEN_RECORD = 8191_IK

The scalar integer of default kind IK representing the effective maximum length of a record in a record-oriented file. Note that this is an arbitrary length defined globally for consistency.

Definition at line 408 of file pm_io.F90.

MFILL

character(*, SK), parameter pm_io::MFILL = SK_"%"

The scalar character of default kind SK of len = 1 representing the default string that is used for filling the margins of the display or wrapped texts.

Definition at line 329 of file pm_io.F90.

MODULE_NAME

character(*, SK), parameter pm_io::MODULE_NAME = "@pm_io"

Definition at line 267 of file pm_io.F90.

SPINNER

character(1, SK), dimension(4), parameter pm_io::SPINNER = [ "|" , "/" , "-" , "\" ]

The scalar character(1, SK) of default kind SK of size 4, containing the four characters used to display a spinning command line cursor.

Definition at line 394 of file pm_io.F90.

TAB

character(1, SK), parameter pm_io::TAB = achar(9, SK)

The scalar character of default kind SK of len = 4 representing representing ASCII character: Horizontal Tab, which is frequently used in external files as column or field separators.

Definition at line 336 of file pm_io.F90.

TABEQV

character(*, SK), parameter pm_io::TABEQV = repeat(SK_" ", 4)

The scalar character of default kind SK of len = 4 representing the default string that is used in place of the tab character in the display.

Definition at line 343 of file pm_io.F90.

Referenced by pm_test::setSummary().

unformatted

type(unformatted_type), parameter pm_io::unformatted = unformatted_type()

This is a scalar parameter object of type unformatted_type that is exclusively used to signify the unformatted (binary) file form within an interface of a procedure of the ParaMonte library.

For example usage, see the documentation of the target procedure requiring this object.

See also

csv
fld
unknown
csv_type
fld_type
form_type
formatted
unformatted
unknown_type
formatted_type
unformatted_type

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.

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 657 of file pm_io.F90.

unknown

type(unknown_type), parameter pm_io::unknown = unknown_type()

This is a scalar parameter object of type unknown_type that is exclusively used to signify the unknown file form within an interface of a procedure of the ParaMonte library.

For example usage, see the documentation of the target procedure requiring this object.

See also

csv
fld
unknown
csv_type
fld_type
form_type
formatted
unformatted
unknown_type
formatted_type
unformatted_type

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.

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 592 of file pm_io.F90.