RealValue Class

Description
Module Interface
Subroutines and Functions
Examples

Description

The RealValue class represents a single real value.

Module Interface

MODULE RealValue_Class

TYPE RealValue

INTERFACE isValid
INTERFACE initialize
INTERFACE finalize
INTERFACE equal
INTERFACE unequal
INTERFACE get
INTERFACE set
INTERFACE read
INTERFACE write
INTERFACE print
INTERFACE getDescription
INTERFACE getName
INTERFACE getUnit
INTERFACE getValue
INTERFACE setValue
INTERFACE ASSIGNMENT (=)
INTERFACE OPERATOR (==)
INTERFACE OPERATOR (/=)

INTEGER, PARAMETER :: RealValue_InvalidDimensions
INTEGER, PARAMEGER :: RealValue_InvalidAttrType
INTEGER, PARAMETER :: RealValue_InvalidAttrSize
INTEGER, PARAMETER :: RealValue_DefinitionFailed
INTEGER, PARAMETER :: RealValue_NonExistingVar

END MODULE RealValue_Class

Functions and Subroutines

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

This function checks whether the parameter this contains a valid RealValue object. It may be applied to any RealValue object at any time. A valid RealValue object has a name and unit.

SUBROUTINE initialize(this,description,name,unit,value)
    TYPE(RealValue), INTENT(out)          :: this
    CHARACTER(len=*), INTENT(in), OPTIONAL :: description
    CHARACTER(len=*), INTENT(in), OPTIONAL :: name
    CHARACTER(len=*), INTENT(in), OPTIONAL :: unit
    REAL,             INTENT(in), OPTIONAL :: value

This subroutine initializes an (invalid) RealValue 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 RealValue object.
The following parameters can optionally be specified:

description: A text that gives a more detailed description of this value than its name.
name: The name of this real value. This name should not be the empty string.
unit: The unit in which the value is expressed. This unit should not be the empty string.
value: The initial value of this RealValue object.

An RealValue object can also be initialized using the assignment operator.

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

This subroutine finalizes the (valid) RealValue 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(RealValue), INTENT(in) :: left
    TYPE(RealValue), INTENT(in) :: right

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

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

These functions compare an RealValue object with another RealValue object or with a real number. When the two arguments are equal, the value .TRUE. is returned. Otherwise, the return value is .FALSE.. Two RealValue objects are equal when their names, descriptions, units, and value are equal.
This function can also be invoked via the binary operator ==.

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

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

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

These functions check whether an RealValue objects differs from another object or from a real.
This function can also be invoked via the binary operator /=.

SUBROUTINE get(this,description,name,unit,value)
    TYPE(RealValue), INTENT(in)            :: this
    CHARACTER(len=*), INTENT(out), OPTIONAL :: description
    CHARACTER(len=*), INTENT(out), OPTIONAL :: name
    CHARACTER(len=*), INTENT(out), OPTIONAL :: unit
    REAL,             INTENT(out), OPTIONAL :: value

This subroutine retrieves information from the RealValue object, this. The object 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,name,unit,value)
    TYPE(RealValue), INTENT(inout)        :: this
    CHARACTER(len=*), INTENT(in), OPTIONAL :: description
    CHARACTER(len=*), INTENT(in), OPTIONAL :: name
    CHARACTER(len=*), INTENT(in), OPTIONAL :: unit
    REAL,             INTENT(in), OPTIONAL :: value

This subroutine modifies the RealValue 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(RealValue), INTENT(inout)           :: this
    TYPE(DataFile), INTENT(in)              :: file
    TYPE(Error),     INTENT(inout), OPTIONAL :: err

This subroutine reads this RealValue object using a file. The object can be read successfully when a one-dimensional variable with the name of the RealValue object is present in the data file. The old contents of the object is destroyed. 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 following error codes can be set:

RealValue_InvalidDimensions

The file contains a variable with the given name but this variable does not have one dimension of length one.

RealValue_InvalidAttrType

An attribute required by the COARDS conventions for NetCDF file was found but this attribute was of the wrong type.

RealValue_InvalidAttrSize

An attribute required by the COARDS conventions for NetCDF file was found but this attribute had the wrong size.

(See also the DataFile and Error classes.)

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

This subroutine writes the contents of this RealValue 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 following error codes can be set:

RealValue_DefinitionFailed

The object was not written to the file before. Therefore, it must be defined first. However, when attempting to do this, an error occured.

(See also the DataFile and Error classes.)

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

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

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

This function retrieves the description of this RealValue object.

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

This function retrieves the name of this RealValue 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(RealValue), INTENT(in) :: this

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

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

This function retrieves the value of this RealValue object.
This function can also be invoked via the binary assignment=.

SUBROUTINE setValue(this,value)
TYPE(RealValue), INTENT(inout) :: this
REAL, INTENT(in) :: value

This subroutine sets the value of this RealValue object.
This function can also be invoked via the binary assignment=.

ASSIGNMENT (=) <left> = <right>

This operator copies the content of the right operand to the left one. The latter object can invalid before the assignment. After the assignment it is valid. Either of the operands can be an RealValue object or a real number.

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

This operator compares two RealValue objects or an RealValue object and a real number for equality. It is an alternative for using the equal function.

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

This operator compares two RealValue objects or an RealValue object and a real number for inequality. It is an alternative for using the unequal function.

Examples

The following example program shows how a RealValue object can be written to and read from a file.

PROGRAM RealValue_Class_Example
USE RealValue_Class
USE DataFile_Class
USE Error_Class
IMPLICIT NONE

CHARACTER(len=*), PARAMETER :: filename    = "data.nc"
CHARACTER(len=*), PARAMETER :: description = "A sample real value"
CHARACTER(len=*), PARAMETER :: name        = "rval"
CHARACTER(len=*), PARAMETER :: unit        = "meter"
REAL,             PARAMETER :: value       = 1.0

TYPE(RealValue) :: val
TYPE(DataFile) :: file
TYPE(Error) :: err

CALL initialize(err)
CALL initialize(file,name=filename,type=NetCDFFile,err=err)
IF (isSet(err)) THEN
CALL print(err)
STOP "initialize(file)"
END IF

IF (isWriteable(file)) THEN
    CALL initialize(val,name=name,unit=unit, &
       & description=description)
    val = value
    CALL write(val,file,err)
    IF (isSet(err)) THEN
      CALL print(err)
      STOP "write(val)"
    END IF
    PRINT*,"Wrote the following RealValue object:"
    CALL print(val)
    PRINT*,"Execute this program again"// &
        & " to read this object from the file"
ELSE
    CALL initialize(val,name=name)
    CALL read(val,file,err)
    IF (isSet(err)) THEN
      CALL print(err)
      STOP "read(val)"
    END IF
    PRINT*,"Read the following RealValue object:"
    CALL print(val)
END IF

CALL finalize(val)
CALL finalize(file,err=err)
IF (isSet(err)) THEN
CALL print(err)
STOP "finalize(file)"
END IF
CALL finalize(err)
END PROGRAM RealValue_Class_Example