FU_Files Module

  1. Files_M.F90
  2. FU_Files

Useful tools to manipulate files in Fortran programs.


Uses


Contents

Variables

Interfaces

Functions


Variables

Type Visibility Attributes Name Initial
character, public, parameter :: filesep = '/'

Path separator: '\' for Windows and '/' for Linux, MacOS and other OS.

Interfaces

public interface readMatrix

Reads a matrix from a file. The file must have the proper format:

First line includes the number of rows, the number of columns and a logical indicating if the second line is a header line to be skipped. Example: 5 9 T.

The second row can be a header or not.

Then the matrix comes. The different columns must be separated using blanks.

The file is then opened, read and closed. The return variable must have ALLOCATABLE attribute, and must not be allocated (the subroutine takes care of allocation but not about deallocation).

Syntax

 call readMatrix(filename, matrix)

Where:

  • filename: string of any length with the path to the file to read. If the file does not exist or it is empty a Fortran runtime error is raised. If the file does not have the proper format the behaviour is undefined.
  • matrix: an allocatable array of rank 2 of any of the integer or real kinds supported. It will be allocated automatically in the subroutine, but the user must deallocate matrix manually after use.

Example

The following example program loads values from a file named matrix.txt:

 PROGRAM readMatrixExample
    USE FU_Files, ONLY: readMatrix
    USE FU_Prec, ONLY: dp
    IMPLICIT NONE
    CHARACTER(LEN=:), ALLOCATABLE :: matrixFileName
    REAL(KIND=dp), DIMENSION(:,:), ALLOCATABLE :: matrix
    matrixFileName = 'matrix.txt'
    CALL readMatrix(matrixFileName, matrix)
    WRITE(*,*) matrix
    DEALLOCATE(matrix)
 END PROGRAM readMatrixExample

File matrix.txt contains the following information:

 2 3 F 
 1.1 1.2 1.3 
 2.1 2.2 2.3

  • private subroutine readMatrix_i8(filename, res)

    Reads a matrix from a file. The file must have the proper format:

    First line includes the number of rows, the number of columns and a logical indicating if the second line is a header line to be skipped. Example: 5 9 T.

    The second row can be a header or not.

    Then the matrix comes. The different columns must be separated using blanks.

    The file is then opened, read and closed.

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in) :: filename

    Filename of the file to read the matrix from.
    integer(kind=i8), intent(out), DIMENSION(:,:), ALLOCATABLE :: res

    Values read from the matrix. This output variable must be allocatable but must not be allocated prior to call readMatrix as it is allocated here. However deallocation must be done manually by the user when finishes using the information.

  • private subroutine readMatrix_i16(filename, res)

    Reads a matrix from a file. The file must have the proper format:

    First line includes the number of rows, the number of columns and a logical indicating if the second line is a header line to be skipped. Example: 5 9 T.

    The second row can be a header or not.

    Then the matrix comes. The different columns must be separated using blanks.

    The file is then opened, read and closed.

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in) :: filename

    Filename of the file to read the matrix from.
    integer(kind=i16), intent(out), DIMENSION(:,:), ALLOCATABLE :: res

    Values read from the matrix. This output variable must be allocatable but must not be allocated prior to call readMatrix as it is allocated here. However deallocation must be done manually by the user when finishes using the information.

  • private subroutine readMatrix_i32(filename, res)

    Reads a matrix from a file. The file must have the proper format:

    First line includes the number of rows, the number of columns and a logical indicating if the second line is a header line to be skipped. Example: 5 9 T.

    The second row can be a header or not.

    Then the matrix comes. The different columns must be separated using blanks.

    The file is then opened, read and closed.

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in) :: filename

    Filename of the file to read the matrix from.
    integer(kind=i32), intent(out), DIMENSION(:,:), ALLOCATABLE :: res

    Values read from the matrix. This output variable must be allocatable but must not be allocated prior to call readMatrix as it is allocated here. However deallocation must be done manually by the user when finishes using the information.

  • private subroutine readMatrix_i64(filename, res)

    Reads a matrix from a file. The file must have the proper format:

    First line includes the number of rows, the number of columns and a logical indicating if the second line is a header line to be skipped. Example: 5 9 T.

    The second row can be a header or not.

    Then the matrix comes. The different columns must be separated using blanks.

    The file is then opened, read and closed.

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in) :: filename

    Filename of the file to read the matrix from.
    integer(kind=i64), intent(out), DIMENSION(:,:), ALLOCATABLE :: res

    Values read from the matrix. This output variable must be allocatable but must not be allocated prior to call readMatrix as it is allocated here. However deallocation must be done manually by the user when finishes using the information.

  • private subroutine readMatrix_sp(filename, res)

    Reads a matrix from a file. The file must have the proper format:

    First line includes the number of rows, the number of columns and a logical indicating if the second line is a header line to be skipped. Example: 5 9 T.

    The second row can be a header or not.

    Then the matrix comes. The different columns must be separated using blanks.

    The file is then opened, read and closed.

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in) :: filename

    Filename of the file to read the matrix from.
    real(kind=sp), intent(out), DIMENSION(:,:), ALLOCATABLE :: res

    Values read from the matrix. This output variable must be allocatable but must not be allocated prior to call readMatrix as it is allocated here. However deallocation must be done manually by the user when finishes using the information.

  • private subroutine readMatrix_dp(filename, res)

    Reads a matrix from a file. The file must have the proper format:

    First line includes the number of rows, the number of columns and a logical indicating if the second line is a header line to be skipped. Example: 5 9 T.

    The second row can be a header or not.

    Then the matrix comes. The different columns must be separated using blanks.

    The file is then opened, read and closed.

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in) :: filename

    Filename of the file to read the matrix from.
    real(kind=dp), intent(out), DIMENSION(:,:), ALLOCATABLE :: res

    Values read from the matrix. This output variable must be allocatable but must not be allocated prior to call readMatrix as it is allocated here. However deallocation must be done manually by the user when finishes using the information.

  • private subroutine readMatrix_qp(filename, res)

    Reads a matrix from a file. The file must have the proper format:

    First line includes the number of rows, the number of columns and a logical indicating if the second line is a header line to be skipped. Example: 5 9 T.

    The second row can be a header or not.

    Then the matrix comes. The different columns must be separated using blanks.

    The file is then opened, read and closed.

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in) :: filename

    Filename of the file to read the matrix from.
    real(kind=qp), intent(out), DIMENSION(:,:), ALLOCATABLE :: res

    Values read from the matrix. This output variable must be allocatable but must not be allocated prior to call readMatrix as it is allocated here. However deallocation must be done manually by the user when finishes using the information.

public interface writeMatrix

Writes a matrix to a file. The file will have the following format:

First line includes the number of rows, the number of columns and a logical indicating if the second line is a header line to be skipped. Example: 5 9 T.

The second row can be a header or not.

Then the matrix comes. The different columns are separated using blanks.

The file is then opened, written and closed.

Syntax

 call writeMatrix(filename, matrix, header, formato)

Where:

  • filename: string of any length with the path to the file to write.
  • matrix: an array of rank 2 of any of the integer or real kinds supported.
  • header: optional character variable of any length to write in the second line of the file.
  • formato: optional character variable with the format to use for the numbers (without parenthesis.

Example

The following example program writes values to a file named matrix.txt:

 PROGRAM writeMatrixExample
    USE FU_Files, ONLY: writeMatrix
    USE FU_Prec, ONLY: dp
    IMPLICIT NONE
    CHARACTER(LEN=:), ALLOCATABLE :: matrixFileName
    REAL(KIND=dp), DIMENSION(2,3) :: matrix
    matrixFileName = 'matrix.txt'
    matrix(1,1) = 1.1 
    matrix(1,2) = 1.2 
    matrix(1,3) = 1.3 
    matrix(2,1) = 2.1 
    matrix(2,2) = 2.2 
    matrix(2,3) = 2.3 
    CALL writeMatrix(matrixFileName, matrix, formato='F3.1')
 END PROGRAM writeMatrixExample

After execution file matrix.txt contains the following information:

        2           3 F
 1.1 1.2 1.3
 2.1 2.2 2.3

  • private subroutine writeMatrix_i8(filename, matrix, header, formato)

    Writes a matrix to a file. The file will have the following format:

    First line includes the number of rows, the number of columns and a logical indicating if the second line is a header line to be skipped. Example: 5 9 T.

    The second row can be a header or not.

    Then the matrix comes. The different columns are separated using blanks.

    The file is then opened, written and closed.

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in) :: filename

    Filename of the file to write the matrix to.
    integer(kind=i8), intent(in), DIMENSION(:,:) :: matrix

    Values of the matrix to write to the file.
    character(len=*), intent(in), optional :: header

    Header to be writen in the second line.
    character(len=*), intent(in), optional :: formato

    Format to use for the numbers without parenthesis. Example: I3

  • private subroutine writeMatrix_i16(filename, matrix, header, formato)

    Writes a matrix to a file. The file will have the following format:

    First line includes the number of rows, the number of columns and a logical indicating if the second line is a header line to be skipped. Example: 5 9 T.

    The second row can be a header or not.

    Then the matrix comes. The different columns are separated using blanks.

    The file is then opened, written and closed.

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in) :: filename

    Filename of the file to write the matrix to.
    integer(kind=i16), intent(in), DIMENSION(:,:) :: matrix

    Values of the matrix to write to the file.
    character(len=*), intent(in), optional :: header

    Header to be writen in the second line.
    character(len=*), intent(in), optional :: formato

    Format to use for the numbers without parenthesis. Example: I3

  • private subroutine writeMatrix_i32(filename, matrix, header, formato)

    Writes a matrix to a file. The file will have the following format:

    First line includes the number of rows, the number of columns and a logical indicating if the second line is a header line to be skipped. Example: 5 9 T.

    The second row can be a header or not.

    Then the matrix comes. The different columns are separated using blanks.

    The file is then opened, written and closed.

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in) :: filename

    Filename of the file to write the matrix to.
    integer(kind=i32), intent(in), DIMENSION(:,:) :: matrix

    Values of the matrix to write to the file.
    character(len=*), intent(in), optional :: header

    Header to be writen in the second line.
    character(len=*), intent(in), optional :: formato

    Format to use for the numbers without parenthesis. Example: I3

  • private subroutine writeMatrix_i64(filename, matrix, header, formato)

    Writes a matrix to a file. The file will have the following format:

    First line includes the number of rows, the number of columns and a logical indicating if the second line is a header line to be skipped. Example: 5 9 T.

    The second row can be a header or not.

    Then the matrix comes. The different columns are separated using blanks.

    The file is then opened, written and closed.

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in) :: filename

    Filename of the file to write the matrix to.
    integer(kind=i64), intent(in), DIMENSION(:,:) :: matrix

    Values of the matrix to write to the file.
    character(len=*), intent(in), optional :: header

    Header to be writen in the second line.
    character(len=*), intent(in), optional :: formato

    Format to use for the numbers without parenthesis. Example: I3

  • private subroutine writeMatrix_sp(filename, matrix, header, formato)

    Writes a matrix to a file. The file will have the following format:

    First line includes the number of rows, the number of columns and a logical indicating if the second line is a header line to be skipped. Example: 5 9 T.

    The second row can be a header or not.

    Then the matrix comes. The different columns are separated using blanks.

    The file is then opened, written and closed.

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in) :: filename

    Filename of the file to write the matrix to.
    real(kind=sp), intent(in), DIMENSION(:,:) :: matrix

    Values of the matrix to write to the file.
    character(len=*), intent(in), optional :: header

    Header to be writen in the second line.
    character(len=*), intent(in), optional :: formato

    Format to use for the numbers without parenthesis. Example: F8.3

  • private subroutine writeMatrix_dp(filename, matrix, header, formato)

    Writes a matrix to a file. The file will have the following format:

    First line includes the number of rows, the number of columns and a logical indicating if the second line is a header line to be skipped. Example: 5 9 T.

    The second row can be a header or not.

    Then the matrix comes. The different columns are separated using blanks.

    The file is then opened, written and closed.

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in) :: filename

    Filename of the file to write the matrix to.
    real(kind=dp), intent(in), DIMENSION(:,:) :: matrix

    Values of the matrix to write to the file.
    character(len=*), intent(in), optional :: header

    Header to be writen in the second line.
    character(len=*), intent(in), optional :: formato

    Format to use for the numbers without parenthesis. Example: F8.3

  • private subroutine writeMatrix_qp(filename, matrix, header, formato)

    Writes a matrix to a file. The file will have the following format:

    First line includes the number of rows, the number of columns and a logical indicating if the second line is a header line to be skipped. Example: 5 9 T.

    The second row can be a header or not.

    Then the matrix comes. The different columns are separated using blanks.

    The file is then opened, written and closed.

    Arguments

    Type IntentOptional Attributes Name
    character(len=*), intent(in) :: filename

    Filename of the file to write the matrix to.
    real(kind=qp), intent(in), DIMENSION(:,:) :: matrix

    Values of the matrix to write to the file.
    character(len=*), intent(in), optional :: header

    Header to be writen in the second line.
    character(len=*), intent(in), optional :: formato

    Format to use for the numbers without parenthesis. Example: F8.3

Functions

public function mkdir(dir, ignoreErrors) result(res)

Author
Emilio Castro.
Date
16/06/2020.
License
MIT.
Version
1.0.

Creates a directory.

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: dir

Path and name of the directory to be created.
logical, intent(in), optional :: ignoreErrors

False to print a detailed description of the error message. Optional parameter. Default is False.

Return Value logical

True if the process has been succesful. False in case of error.

public function cp(src, dest, ignoreErrors) result(res)

Author
Emilio Castro.
Date
16/06/2020.
License
MIT.
Version
1.0.

Copies a file or directory.

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: src

Name of the file to be copied.

character(len=*), intent(in) :: dest

Name of the destination file.
logical, intent(in), optional :: ignoreErrors

False to print a detailed description of the error message. Optional parameter. Default is False.

Return Value logical

True if the process has been succesful. False in case of error.

public function mv(src, dest, ignoreErrors) result(res)

Author
Emilio Castro.
Date
16/06/2020.
License
MIT.
Version
1.0.

Moves or renames a file or directory.

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: src

Name of the file to be moved.

character(len=*), intent(in) :: dest

Name of the destination file.
logical, intent(in), optional :: ignoreErrors

False to print a detailed description of the error message. Optional parameter. Default is False.

Return Value logical

True if the process has been succesful. False in case of error.

public function rm(fname, ignoreErrors) result(res)

Author
Emilio Castro.
Date
16/06/2020.
License
MIT.
Version
1.0.

Removes a file or directory.

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: fname

Name of the file or directory to be removed.
logical, intent(in), optional :: ignoreErrors

False to print a detailed description of the error message. Optional parameter. Default is False.

Return Value logical

True if the process has been succesful. False in case of error.

public function exists(fname) result(res)

Author
Emilio Castro.
Date
16/06/2020.
License
MIT.
Version
1.0.

Checks if a file or directory exists.

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: fname

Name of the file to be check for existence.

Return Value logical

True if the file exists. False otherwise.

public function is_directory(fname, ignoreErrors) result(res)

Author
Emilio Castro.
Date
16/06/2020.
License
MIT.
Version
1.0.

Checks if a directory exists.

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: fname

Name of the directory to be checked.

logical, intent(in), optional :: ignoreErrors

False to print a detailed description of the error message. Optional parameter. Default is False.

Return Value logical

True if fname is a directory. False otherwise.

public function is_empty(fname, ignoreErrors) result(res)

Author
Emilio Castro.
Date
16/06/2020.
License
MIT.
Version
1.0.

Checks if a file is empty.

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: fname

Name of the file to be checked.

logical, intent(in), optional :: ignoreErrors

False to print a detailed description of the error message. Optional parameter. Default is False.

Return Value logical

True if fname is an empty file. False otherwise.

public function is_regular_file(fname, ignoreErrors) result(res)

Author
Emilio Castro.
Date
16/06/2020.
License
MIT.
Version
1.0.

Checks if a regular file exists and it is not a directory, etc.

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: fname

Name of the file to be checked.

logical, intent(in), optional :: ignoreErrors

False to print a detailed description of the error message. Optional parameter. Default is False.

Return Value logical

True if fname is a regular file. False otherwise.

public function is_path_absolute(fname) result(res)

Author
Emilio Castro.
Date
27/07/2020.
License
MIT.
Version
1.0.

Determines if a path is absolute or not

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: fname

Path to a file.

Return Value logical

True if the path is absolute and false if the path is relative.

public function is_path_relative(fname) result(res)

Author
Emilio Castro.
Date
27/07/2020.
License
MIT.
Version
1.0.

Determines if a path is relative or not

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: fname

Path to a file.

Return Value logical

True if the path is relative and false if the path is absolute.

public function extension(fname) result(res)

Author
Emilio Castro.
Date
27/07/2020.
License
MIT.
Version
1.0.

Determines the extension of a file.

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: fname

Filename or path to a file.

Return Value character(len=:), ALLOCATABLE

Extension of the file including the "dot". Empty path is returned if no extension is found.

public function replace_extension(fname, ext) result(res)

Author
Emilio Castro.
Date
21/01/2021.
License
MIT.
Version
1.0.

Changes the extension of a filename.

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: fname

Filename or path to a file.
character(len=*), intent(in) :: ext

New extension for the fname.

Return Value character(len=:), ALLOCATABLE

The fname value with the modified extension.

public function stem(fname) result(res)

Author
Emilio Castro.
Date
06/08/2020.
License
MIT.
Version
1.0.

Determines the filename without the path and without the final extension given a path.

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: fname

Filename or path to a file.

Return Value character(len=:), ALLOCATABLE

Filename without the final extension and without the path. If filename consists of an extension only, the extension is returned.

public function filename(fname) result(res)

Author
Emilio Castro.
Date
06/08/2020.
License
MIT.
Version
1.0.

Determines the full filename given a path.

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: fname

Filename or path to a file.

Return Value character(len=:), ALLOCATABLE

Full filename given in the path.

public function replace_filename(fname, newname) result(res)

Author
Emilio Castro.
Date
21/01/2021.
License
MIT.
Version
1.0.

Changes the filename of a path (keeping the path).

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: fname

Filename or path to a file.
character(len=*), intent(in) :: newname

New filename for the fname (including extension).

Return Value character(len=:), ALLOCATABLE

The fname value with the modified filename.

public function remove_filename(fname) result(res)

Author
Emilio Castro.
Date
21/01/2021.
License
MIT.
Version
1.0.

Removes the filename from a path.

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: fname

Filename or path to a file.

Return Value character(len=:), ALLOCATABLE

The fname value with the filename removed.

public function parent_path(fname) result(res)

Author
Emilio Castro.
Date
06/08/2020.
License
MIT.
Version
1.0.

Determines the path to the parent directory given the path to a file.

Read more…

Arguments

Type IntentOptional Attributes Name
character(len=*), intent(in) :: fname

Filename or path to a file.

Return Value character(len=:), ALLOCATABLE

Path of the parent directory without final slash.