LogicalValue Class

1. Description

2. Module Interface

3. Subroutines and Functions

4. Examples

Description

The LogicalValue class represents a logical value.

Module Interface

MODULE LogicalValue_Class

TYPE LogicalValue

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 getValue
INTERFACE setValue
INTERFACE ASSIGNMENT (=)
INTERFACE OPERATOR (==)
INTERFACE OPERATOR (/=)

INTEGER, PARAMETER :: LogicalValue_InvalidDimensions
INTEGER, PARAMEGER :: LogicalValue_InvalidAttrType
INTEGER, PARAMETER :: LogicalValue_InvalidAttrSize
INTEGER, PARAMETER :: LogicalValue_DefinitionFailed
INTEGER, PARAMETER :: LogicalValue_NonExistingVar

END MODULE LogicalValue_Class

Functions and Subroutines

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

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

SUBROUTINE initialize(this,description,name,value)
    TYPE(LogicalValue), INTENT(out)          :: this
    CHARACTER(len=*),   INTENT(in), OPTIONAL :: description
    CHARACTER(len=*),   INTENT(in), OPTIONAL :: name
    LOGICAL,            INTENT(in), OPTIONAL :: value

This subroutine initializes an (invalid) LogicalValue 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 LogicalValue 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 logical value. This name should not be the empty string.

value

The initial value of this LogicalValue object.

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

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

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

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

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

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

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

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

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

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

SUBROUTINE get(this,description,name,value)
    TYPE(LogicalValue), INTENT(in)            :: this
    CHARACTER(len=*),   INTENT(out), OPTIONAL :: description
    CHARACTER(len=*),   INTENT(out), OPTIONAL :: name
    LOGICAL,            INTENT(out), OPTIONAL :: value

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

This subroutine modifies the LogicalValue 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 parameter may not be set to the empty string.

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

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

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

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

LogicalValue_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(LogicalValue), INTENT(in) :: this

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

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

This function retrieves the description of this LogicalValue object.

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

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

FUNCTION getValue(this) RESULT(result)
    LOGICAL :: result
    TYPE(LogicalValue), INTENT(in) :: this

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

SUBROUTINE setValue(this,value)
    TYPE(LogicalValue), INTENT(inout) :: this
    LOGICAL,            INTENT(in)    :: value

This subroutine sets the value of this LogicalValue 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 LogicalValue object or a logical.

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

This operator compares two LogicalValue objects or an LogicalValue object and a logical value for equality. It is an alternative for using the equal function.

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

This operator compares two LogicalValue objects or an LogicalValue object and a logical value for inequality. It is an alternative for using the unequal function.

Examples

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

PROGRAM LogicalValue_Class_Example
  USE LogicalValue_Class
  USE DataFile_Class
  USE Error_Class
  IMPLICIT NONE

  CHARACTER(len=*), PARAMETER :: filename    = "data.nc"
  CHARACTER(len=*), PARAMETER :: description = "A sample logical value"
  CHARACTER(len=*), PARAMETER :: name        = "lval"
  CHARACTER(len=*), PARAMETER :: unit        = "meter"
  LOGICAL,          PARAMETER :: value       = .TRUE.

  TYPE(LogicalValue) :: 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 LogicalValue 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 LogicalValue 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 LogicalValue_Class_Example