IntegerValue Class

1. Description

2. Module Interface

3. Subroutines and Functions

4. Examples

Description

The IntegerValue class represents a single integer value.

Module Interface

MODULE IntegerValue_Class

TYPE IntegerValue

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 :: IntegerValue_InvalidDimensions
INTEGER, PARAMEGER :: IntegerValue_InvalidAttrType
INTEGER, PARAMETER :: IntegerValue_InvalidAttrSize
INTEGER, PARAMETER :: IntegerValue_DefinitionFailed
INTEGER, PARAMETER :: IntegerValue_NonExistingVar

END MODULE IntegerValue_Class

Functions and Subroutines

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

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

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

This subroutine initializes an (invalid) IntegerValue 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 IntegerValue 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 integer 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 IntegerValue object.

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

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

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

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

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

These functions compare an IntegerValue object with another IntegerObject or with an integer. When the two arguments are equal, the value .TRUE. is returned. Otherwise, the return value is .FALSE.. Two IntegerValue 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(IntegerValue), INTENT(in) :: left
    TYPE(IntegerValue), INTENT(in) :: right

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

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

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

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

This subroutine retrieves information from the IntegerValue 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(IntegerValue), INTENT(inout)        :: this
    CHARACTER(len=*),   INTENT(in), OPTIONAL :: description
    CHARACTER(len=*),   INTENT(in), OPTIONAL :: name
    CHARACTER(len=*),   INTENT(in), OPTIONAL :: unit
    INTEGER,            INTENT(in), OPTIONAL :: value

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

This subroutine reads this IntegerValue object using a file. The object can be read successfully when a one-dimensional variable with the name of the IntegerValue 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:

IntegerValue_InvalidDimensions
The file contains a variable with the given name but this variable does not have one dimension of length one.
IntegerValue_InvalidAttrType
An attribute required by the COARDS conventions  for NetCDF file was found but this attribute was of the wrong type.
IntegerValue_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(IntegerValue), INTENT(in)              :: this
    TYPE(DataFile),     INTENT(in)              :: file
    TYPE(Error),        INTENT(inout), OPTIONAL :: err

This subroutine writes the contents of this IntegerValue 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:

IntegerValue_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(IntegerValue), INTENT(in) :: this

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

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

This function retrieves the description of this IntegerValue object.

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

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

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

FUNCTION getValue(this) RESULT(result)
    INTEGER :: result
    TYPE(IntegerValue), INTENT(in) :: this

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

SUBROUTINE setValue(this,value)
    TYPE(IntegerValue), INTENT(inout) :: this
    INTEGER,            INTENT(in)    :: value

This subroutine sets the value of this IntegerValue 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 IntegerValue object or an integer.

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

This operator compares two IntegerValue objects or an IntegerValue object and an integer for equality. It is an alternative for using the equal function.

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

This operator compares two IntegerValue objects or an IntegerValue object and an integer for inequality. It is an alternative for using the unequal function.

Examples

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

PROGRAM IntegerValue_Class_Example
  USE IntegerValue_Class
  USE DataFile_Class
  USE Error_Class
  IMPLICIT NONE

  CHARACTER(len=*), PARAMETER :: filename    = "data.nc"
  CHARACTER(len=*), PARAMETER :: description = "A sample integer value"
  CHARACTER(len=*), PARAMETER :: name        = "ival"
  CHARACTER(len=*), PARAMETER :: unit        = "meter"
  INTEGER,          PARAMETER :: value       = 1

  TYPE(IntegerValue) :: 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 IntegerValue 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 IntegerValue 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 IntegerValue_Class_Example