StringValue Class

Description
Module Interface
Subroutines and Functions
Examples

Description

The StringValue class represents a character string value. The current implementation imposes a limit on the length of the string of 2048 characters.

Module Interface

MODULE StringValue_Class

TYPE StringValue

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 :: StringValue_InvalidDimensions
INTEGER, PARAMEGER :: StringValue_InvalidAttrType
INTEGER, PARAMETER :: StringValue_InvalidAttrSize
INTEGER, PARAMETER :: StringValue_DefinitionFailed
INTEGER, PARAMETER :: StringValue_NonExistingVar

END MODULE StringValue_Class

Functions and Subroutines

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

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

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

This subroutine initializes an (invalid) StringValue 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 StringValue 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 string value. This name should not be the empty string.
value: The initial value of this StringValue object.

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

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

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

FUNCTION equal(left,right) RESULT(result)
    LOGICAL :: result
    TYPE(StringValue), INTENT(in) :: left
    CHARACTER(len=*), INTENT(in) :: right

FUNCTION equal(left,right) RESULT(result)
    LOGICAL :: result
    CHARACTER(len=)*, INTENT(in) :: left
    TYPE(StringValue), INTENT(in) :: right

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

FUNCTION unequal(left,right) RESULT(result)
    LOGICAL :: result
    TYPE(StringValue), INTENT(in) :: left
    CHARACTER(len=*), INTENT(in) :: right

FUNCTION unequal(left,right) RESULT(result)
    LOGICAL :: result
    CHARACTER(len=*), INTENT(in) :: left
    TYPE(StringValue), INTENT(in) :: right

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

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

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

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

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

StringValue_InvalidDimensions

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

StringValue_InvalidAttrType

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

StringValue_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(StringValue), INTENT(in)              :: this
    TYPE(DataFile),    INTENT(in)              :: file
    TYPE(Error),       INTENT(inout), OPTIONAL :: err

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

StringValue_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(StringValue), INTENT(in) :: this

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

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

This function retrieves the description of this StringValue object.

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

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

FUNCTION getValue(this) RESULT(result)
CHARACTER(len=*) :: result
TYPE(StringValue), INTENT(in) :: this

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

SUBROUTINE setValue(this,value)
TYPE(StringValue), INTENT(inout) :: this
CHARACTER(len=*), INTENT(in) :: value

This subroutine sets the value of this StringValue 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 StringValue object or a character string.

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

This operator compares two StringValue objects or an StringValue object and a character string for equality. It is an alternative for using the equal function.

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

This operator compares two StringValue objects or an StringValue object and a character string for inequality. It is an alternative for using the unequal function.

Examples

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

PROGRAM StringValue_Class_Example
USE StringValue_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        = "sval"
CHARACTER(len=*), PARAMETER :: unit        = "meter"
CHARACTER(len=*), PARAMETER :: value       = "A string value"

TYPE(StringValue) :: 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 StringValue 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 StringValue 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 StringValue_Class_Example