TimeCoordinate Class

1. Description

2. Module Interface

3. Subroutines and Functions

4. Examples

Description

The TimeCoordinate class represents a time axis of a (time-dependent) data field grid. The length of the time axis can be increased at will. This class is a specialization of the Coordinate class.

Module Interface

MODULE TimeCoordinate_Class

TYPE TimeCoordinate

INTERFACE isValid
INTERFACE initialize
INTERFACE finalize
INTERFACE equal
INTERFACE unequal
INTERFACE get
INTERFACE set
INTERFACE read
INTERFACE write
INTERFACE print
INTERFACE arrayFor
INTERFACE getCurrentTime
INTERFACE getDescription
INTERFACE getIndex
INTERFACE getLength
INTERFACE getName
INTERFACE getUnit
INTERFACE getValue
INTERFACE getValues
INTERFACE getValueAt
INTERFACE matches
INTERFACE setIndex
INTERFACE setValueAt
INTERFACE ASSIGNMENT (=)
INTERFACE OPERATOR (==)
INTERFACE OPERATOR (/=)
INTERFACE OPERATOR (.matches.)

END MODULE TimeCoordinate_Class

Functions and Subroutines

FUNCTION isValid(this) RESULT(result)
    LOGICAL :: result
    TYPE(TimeCoordinate), INTENT(in) :: this

This function checks whether the parameter this contains a valid TimeCoordinate object. It may be applied to any TimeCoordinate object at any time. A valid TimeCoordinate object has a name and a unit, and has an index value that is greater than or equal to one.

SUBROUTINE initialize(this,description,index,initial_length,name,unit,values)
    TYPE(TimeCoordinate), INTENT(out)          :: this
    CHARACTER(len=*),     INTENT(in), OPTIONAL :: description
    INTEGER,              INTENT(in), OPTIONAL :: index
    INTEGER,              INTENT(in), OPTIONAL :: initial_length
    CHARACTER(len=*),     INTENT(in), OPTIONAL :: name
    CHARACTER(len=*),     INTENT(in), OPTIONAL :: unit
    REAL, DIMENSION(:),   INTENT(in), OPTIONAL :: values

This subroutine initializes an (invalid) TimeCoordinate object. This subroutine should be invoked on an object before any other function or subroutine except isValid. After initialization, the parameter this contains a valid TimeCoordinate object.
The following parameters can optionally be specified:

description

A text that gives a more detailed description of this time axis than its name.

index

The time index. This should be a value in the range from one to initial_length. The default value is one.

initial_length

The number of time values that are initially specified. Note that when the values parameter is also specified, the value of this parameter should be equal to the size of values.

name

The name of this coordinate axis. This name should not be the empty string.

unit

The unit in which the values of this coordinate axis are expressed. This unit should not be the empty string.

values

The values of this time axis. Note that when the length parameter is also specified, the size of this parameter should be equal to the value of length.

A TimeCoordinate object can also be initialized by duplicating an existing object using the assignment operator.

SUBROUTINE finalize(this)
    TYPE(TimeCoordinate), INTENT(inout) :: this

This subroutine finalizes the (valid) TimeCoordinate object, this. This object should have been initialized earlier in the program. After finalization, the object is invalid and should not be used anymore.

FUNCTION equal(left,right) RESULT(result)
    LOGICAL :: result
    TYPE(TimeCoordinate), INTENT(in) :: left
    TYPE(TimeCoordinate), INTENT(in) :: right

This function compares two TimeCoordinate objects. When the two objects are equal, the value .TRUE. is returned. Otherwise, the return value is .FALSE.. Two TimeCoordinate object are equal when their names, descriptions, indexes, units, lengths, and values are equal.
This function can also be invoked via the binary operator == .

FUNCTION unequal(left,right) RESULT(result)
    LOGICAL :: result
    TYPE(TimeCoordinate), INTENT(in) :: left
    TYPE(TimeCoordinate), INTENT(in) :: right

This function checks whether two TimeCoordinate objects are different.
This function can also be invoked via the binary operator /=.

SUBROUTINE get(this,description,index,length,name,unit,values)
    TYPE(TimeCoordinate), INTENT(in)            :: this
    CHARACTER(len=*),     INTENT(out), OPTIONAL :: description
    INTEGER,              INTENT(out), OPTIONAL :: index
    INTEGER,              INTENT(out), OPTIONAL :: length
    CHARACTER(len=*),     INTENT(out), OPTIONAL :: name
    CHARACTER(len=*),     INTENT(out), OPTIONAL :: unit
    REAL, DIMENSION(:),   INTENT(out), OPTIONAL :: values

This subroutine retrieves information from the TimeCoordinate object, this. The object itself is not modified. The optional parameters determine which information will be retrieved. This subroutine can be invoked without any parameters. In this case, the subroutine is as a no-op.

SUBROUTINE set(this,description,index,length,name,unit,values)
    TYPE(TimeCoordinate), INTENT(inout)        :: this
    CHARACTER(len=*),     INTENT(in), OPTIONAL :: description
    INTEGER,              INTENT(in), OPTIONAL :: index
    INTEGER,              INTENT(in), OPTIONAL :: length
    CHARACTER(len=*),     INTENT(in), OPTIONAL :: name
    CHARACTER(len=*),     INTENT(in), OPTIONAL :: unit
    REAL, DIMENSION(:),   INTENT(in), OPTIONAL :: values

This subroutine modifies the TimeCoordinate object, this. The optional parameters determine which information is modified. This subroutine can be invoked without any parameters. In this case, the subroutine is as a no-op. Note that the name and unit parameters may not be set to the empty string.

SUBROUTINE read(this,file,err)
    TYPE(TimeCoordinate), INTENT(inout)           :: this
    TYPE(DataFile),       INTENT(in)              :: file
    TYPE(Error),          INTENT(inout), OPTIONAL :: err

This subroutine reads this TimeCoordinate object using a file. The object can be read successfully when a one-dimensional variable with the name of the TimeCoordinate object is present in the data file. The old contents of the object is destroyed. The time index is set to one.

An Error object can be passed to this subroutine to catch run-time errors that would otherwise cause the execution of the program to be aborted. The errors that can occur are the same as for reading a Coordinate object.
(See also the Coordinate, DataFile and Error classes.)

SUBROUTINE write(this,file,err)
    TYPE(TimeCoordinate), INTENT(in)              :: this
    TYPE(DataFile),       INTENT(in)              :: file
    TYPE(Error),          INTENT(inout), OPTIONAL :: err

This subroutine writes the contents of this TimeCoordinate object to a file. When the object was written to the same file before, the new contents replaces the old. An Error object can be passed to this subroutine to catch run-time errors that would otherwise cause the execution of the program to be aborted. The errors that can be returned are the same as for writing a Coordinate object.

(See also the Coordinate, DataFile and Error classes.)

SUBROUTINE print(this)
    TYPE(TimeCoordinate), INTENT(in) :: this

This subroutine is the equivalent of the Fortran PRINT statement. It prints the TimeCoordinate object, this, to the standard output unit in standardized format. The object is not modified.

FUNCTION arrayFor(this) RESULT(result)
    REAL, DIMENSION(:), POINTER :: result
    TYPE(TimeCoordinate), INTENT(in) :: this

This function allocates a one dimensional array with a shape matching this TimeCoordinate object and returns a pointer to this array.

FUNCTION getCurrentTime(this) RESULT(result)
    REAL :: result
    TYPE(TimeCoordinate), INTENT(in) :: this

This function retrieves the current time of this TimeCoordinate object. The current time is the time value at the index of this object.

FUNCTION getDescription(this) RESULT(result)
    CHARACTER(len=*) :: result
    TYPE(TimeCoordinate), INTENT(in) :: this

This function retrieves the description of this TimeCoordinate object.

FUNCTION getIndex(this) RESULT(result)
    INTEGER :: result
    TYPE(TimeCoordinate), INTENT(in) :: this

This function returns the time index of this TimeCoordinate object. The return value greater than or equal to one and less than or equal to the length of this object, unless the length is zero. In that case, the return value is always one.

FUNCTION getLength(this) RESULT(result)
    INTEGER :: result
    TYPE(TimeCoordinate), INTENT(in) :: this

This function returns the length of this TimeCoordinate object. The return value zero indicates that the length of the object has not been set.

FUNCTION getName(this) RESULT(result)
    CHARACTER(len=*) :: result
    TYPE(TimeCoordinate), INTENT(in) :: this

This function retrieves the name of this TimeCoordinate object. This is the name that is used to identify the object in a data file.

FUNCTION getUnit(this) RESULT(result)
    CHARACTER(len=*) :: result
    TYPE(TimeCoordinate), INTENT(in) :: this

This function retrieves the unit in which the values of this TimeCoordinate object are expressed.

FUNCTION getValue(this) RESULT(result)
    REAL :: result
    TYPE(TimeCoordinate), INTENT(in) :: this

This function retrieves the time value at the current time index of this TimeCoordinate object. This function has as an alias the function getCurrentTime.

FUNCTION getValues(this) RESULT(result)
    REAL, DIMENSION(1:getLength(this)) :: result
    TYPE(TimeCoordinate), INTENT(in) :: this

This function retrieves an array containing all values of this TimeCoordinate object.

FUNCTION getValueAt(this,index) RESULT(result)
    REAL :: result
    TYPE(TimeCoordinate), INTENT(in) :: this
    INTEGER,              INTENT(in) :: index

This function retrieves the time at the given index. The value of the index parameter should be in the range from 1 to getLength(this).

FUNCTION matches(left,right) RESULT(result)
    LOGICAL :: result
    TYPE(TimeCoordinate), INTENT(in) :: left,right

This function checks whether two TimeCoordinate objects match and returns the result. Two time coordinates match when they only differ in their index value. This function can also be invoked using the operator .matches..

SUBROUTINE setIndex(this,index)
    TYPE(TimeCoordinate), INTENT(inout) :: this
    INTEGER,              INTENT(in)    :: index

This subroutine sets the time value at the given index. The value of the index parameter should be in the range from 1 to getLength(this).

SUBROUTINE setValueAt(this,index,value)
    TYPE(TimeCoordinate), INTENT(inout) :: this
    INTEGER,              INTENT(in)    :: index
    REAL,                 INTENT(in)    :: value

This subroutine sets the time index of this TimeCoordinate object. The value of the index parameter should be in the range from 1 to getLength(this).

ASSIGNMENT (=)   <left> = <right>

This operator copies the content of the TimeCoordinate object at the right of the assignment operator to the one at the left. The latter object can invalid before the assignment. After the assignment it is valid.

OPERATOR (==)    <left> == <right>

This operator compares two Coordinate objects for equality. It is an alternative for using the equal function.

OPERATOR (/=)    <left> /= <right>

This operator compares two Coordinate objects for inequality. It is an alternative for using the unequal function.

OPERATOR (.matches.)    <left> .matches. <right>

This operator compares two Coordinate objects for inequality. It is an alternative for using the matches function.

Examples

The following program shows how you can create a TimeCoordinate object and modify it later.

PROGRAM TimeCoordinate_Class_Example
  USE TimeCoordinate_Class
  IMPLICIT NONE

  CHARACTER(len=*), PARAMETER :: description = "The time measured in days"
  CHARACTER(len=*), PARAMETER :: name        = "time"
  CHARACTER(len=*), PARAMETER :: unit        = "days"
  REAL, DIMENSION(1:4), &
       &            PARAMETER :: values      = (/ 1.0,2.0,4.0,8.0 /)

  TYPE(TimeCoordinate) :: t
  INTEGER :: i

  CALL initialize(t)
  CALL set(t,name=name,unit=unit,values=values)
  CALL print(t)

  DO i=1,5
    CALL setValueAt(t,i,2.0*i)
  END DO
  CALL print(t)

  CALL finalize(t)
END PROGRAM TimeCoordinate_Class_Example

Note that the program adds a fifth time value to the TimeCoordinate object, t. The object automatically increases its internal storage for time values. Also note that the time values don't have to be equidistant.