Unit Class

1. Description

2. Module Interface

3. Subroutines and Functions

4. Examples

Description

The Unit class represents an unit of measure. This class provides a high-level interface to the udunits package.

Module Interface

MODULE Unit_Class

TYPE Unit

TYPE UnitConversion
   REAL :: slope
   REAL :: intercept
END TYPE UnitConversion

INTERFACE isValid
INTERFACE initialize
INTERFACE finalize
INTERFACE equal
INTERFACE unequal
INTERFACE get
INTERFACE set
INTERFACE print
INTERFACE getConversionTo
INTERFACE hasOrigin
INTERFACE isConvertibleTo
INTERFACE isTimeUnit
INTERFACE ASSIGNMENT (=)
INTERFACE OPERATOR (==)
INTERFACE OPERATOR (/=)
INTERFACE OPERATOR (*)
INTERFACE OPERATOR (/)
INTERFACE OPERATOR (**)
INTERFACE OPERATOR (.isConvertibleTo.)

INTEGER, PARAMETER :: Unit_NoUnitsFile
INTEGER, PARAMEGER :: Unit_SyntaxError
INTEGER, PARAMETER :: Unit_UnknownSpecification
INTEGER, PARAMETER :: Unit_IOError
INTEGER, PARAMETER :: Unit_MemoryAllocationError
INTEGER, PARAMETER :: Unit_UnknownUnit
INTEGER, PARAMETER :: Unit_PackageNotInitialized
INTEGER, PARAMETER :: Unit_InvalidUnit
INTEGER, PARAMETER :: Unit_InsufficientMemory
INTEGER, PARAMETER :: Unit_UnexpectedError
INTEGER, PARAMETER :: Unit_NotConvertible

END MODULE Unit_Class

Functions and Subroutines

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

This function checks whether the parameter this contains a valid Unit object. It may be applied to any Unit object at any time.

SUBROUTINE initialize(this,text,err)
    TYPE(Unit),       INTENT(out)          :: this
    CHARACTER(len=*), INTENT(in), OPTIONAL :: text
    TYPE(Error),      INTENT(in), OPTIONAL :: err

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

text

A character string that describes the unit. The udunits package is used to parse this string. It this parameter is not provided, the Unit object will be initialized as a dimensionless unit.

err

An Error object that can be used to obtain information on error conditions that would otherwise result in a fatal run-time error.

The following error codes can be set:

Unit_PackageNotInitialized
The udunits package has not been initialized.
Unit_UnknownUnit
The unit text contains a unit that is not recognized by the udunits package. Most likely, the units file used by udunits does not contain a definition of the unit.
Unit_SyntaxError
The unit text contains a syntactical error.
Unit_UnexpectedError
An error occured without a known cause. This error could occur when the Fields library is linked with an incompatible version of the udunits library.

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

(See also the Error class.)

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

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

This function compares two Unit objects. When the two objects are equal, the value .TRUE. is returned. Otherwise, the return value is .FALSE..
This function can also be invoked via the binary operator ==.

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

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

SUBROUTINE get(this,text,err)
    TYPE(Unit),       INTENT(in)            :: this
    CHARACTER(len=*), INTENT(out)           :: text
    TYPE(Error),      INTENT(out), OPTIONAL :: err

This subroutine retrieves a character string the descirbes this Unit object, this. The optional parameter, err, can be used to catch run-time errors that would otherwise be fatal. The object itself is not modified.
The following errors can be set:

Unit_PackageNotInitialized
The udunits package has not been initialized.
Unit_InvalidUnit
The unit is in valid and, as a result, could not be formatted to a character string.
Unit_InsufficientMemory
The parameter, text, is too small to contain the formatted representation of this unit.
Unit_UnexpectedError
An error occured without a known cause. This error could occur when the Fields library is linked with an incompatible version of the udunits library.

(See also the Error class.)

SUBROUTINE set(this,text,err)
    TYPE(Unit),       INTENT(inout)        :: this
    CHARACTER(len=*), INTENT(in)           :: text
    TYPE(Error),      INTENT(in), OPTIONAL :: err

This subroutine changes the unit of the Unit object, this. The optional parameter, err, can be used to catch run-time errors that would otherwise be fatal.
The following error codes can be set:

Unit_PackageNotInitialized
The udunits package has not been initialized.
Unit_UnknownUnit
The unit text contains a unit that is not recognized by the udunits package. Most likely, the units file used by udunits does not contain a definition of the unit.
Unit_SyntaxError
The unit text contains a syntactical error.
Unit_UnexpectedError
An error occured without a known cause. This error could occur when the Fields library is linked with an incompatible version of the udunits library.

(See also the Error class.)

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

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

FUNCTION getConversionTo(this,to,err) RESULT(result)
    TYPE(UnitConversion) :: result
    TYPE(Unit),  INTENT(in)              :: this
    TYPE(Unit),  INTENT(in)              :: to
    TYPE(Error), INTENT(inout), OPTIONAL :: err

This function computes the conversion from the unit this to the unit to. The return value of this function is valid only when isConvertibleTo(this,to) is .TRUE.. An optional Error object can be passed to catch run-time errors that would otherwise end program execution.
The following errors codes can be set:
The following error codes can be set:

Unit_PackageNotInitialized
The udunits package has not been initialized.
Unit_UnknownUnit
One of the two units is invalid.
Unit_NotConvertible
A conversion between the two units is not defined (in the udunits file).
Unit_UnexpectedError
An error occured without a known cause. This error could occur when the Fields library is linked with an incompatible version of the udunits library.

(See also the Error class.)

FUNCTION isConvertibleTo(this,to) RESULT(result)
    LOGICAL :: result
    TYPE(Unit), INTENT(in) :: this
    TYPE(Unit), INTENT(in) :: to

This function checks whether the unit this can be converted to the unit to and returns the result. This function can also be invoked with the operator .isConvertibleTo..

FUNCTION isTimeUnit(this) RESULT(result)
    LOGICAL :: result
    TYPE(Unit), INTENT(in) :: this

This function returns the value .TRUE. when the Unit object, this, represents a time unit.

FUNCTION hasOrigin(this) RESULT(result)
    LOGICAL :: result
    TYPE(Unit), INTENT(in) :: this

This function returns the value .TRUE. when the unit represented by the object, this, has a scale defined relative to an origin.

ASSIGNMENT (=)    <left> = <right>

This operator copies the content of the Unit 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 and equal to the object at the right.

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

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

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

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

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

This operator checks whether the Unit objects at the left can be converted to the unit at the right. It is an alternative for using the isConvertibleTo function.

OPERATOR (*)    <left> * <right>

This operator multiplies two Unit objects or a Unit object and a real number. The result is a Unit object.
This operator can also be used to multiply a one, two or three dimensional real array (at the left) by a UnitConversion (at the right). In this case, the result is a real array of the same shape.

OPERATOR (/)    <left> / <right>

This operator divides two Unit objects, a Unit object by a real number, or a real number by a Unit object. The result is a Unit object.

OPERATOR (**)    <left> ** <right>

This operator raises the Unit object at the left to an integer power (at the right). The result is a new Unit object.

Examples

The following example program shows how Unit objects can be used.

PROGRAM Unit_Class_Example
  USE Error_Class
  USE Support
  USE Unit_Class
  IMPLICIT NONE

  TYPE(Error)          :: err
  TYPE(Unit)           :: u_length,u_length2,u_area,u_velocity,u_time
  TYPE(UnitConversion) :: foot_to_meter
  REAL, DIMENSION(10)  :: data

  CALL initialize(e)

  CALL initialize(u_length,"meter",err=e)
  IF (isSet(e)) THEN
    CALL fatalError("u_length")
  END IF

  CALL initialize(u_time,"seconds since 0001-01-01",err=e)
  IF (isSet(e)) THEN
    CALL fatalError("u_time")
  END IF

  u_area = u_length**2
  u_velocity = u_length/u_time

  CALL initialize(u_length2,"foot",err=e)
  IF (isSet(e)) THEN
    CALL fatalError("u_length2")
  END IF
  DO i=LBound(array,1),UBound(array,1)
    array(i) = Float(i)
  END DO

  foot_to_meter = getConversionTo(u_length2,u_length)
  array(:) = array(:)*foot_to_meter

  CALL finalize(u_length2)
  CALL finalize(u_velocity)
  CALL finalize(u_area)
  CALL finalize(u_time)
  CALL finalize(u_length)
  CALL finalize(e)
END PROGRAM Unit_Class_Example