# 5.7 EQUIVALENCE Statement

The EQUIVALENCE statement specifies that a storage area is shared by two or more objects in a program unit. This causes total or partial storage association of the objects that share the storage area.

The EQUIVALENCE statement takes the following form:

  EQUIVALENCE (equiv-list) [, (equiv-list)]...
  equiv-list
  Is a list of two or more variables, array elements, or substrings, separated by commas (also called an equivalence set). If an object of derived type is specified, it must be a sequence type. Objects cannot have the TARGET attribute.

  Each expression in a subscript or a substring reference must be an integer initialization expression. A substring must not have a length of zero.

Rules and Behavior

The following objects cannot be specified in EQUIVALENCE statements:

- A dummy argument
- An allocatable array
- A pointer
- An object of nonsequence derived type
- An object of sequence derived type containing a pointer in the structure
- A function, entry, or result name
- A named constant
- A structure component
- A subobject of any of the above objects

The EQUIVALENCE statement causes all of the entities in one parenthesized list to be allocated storage beginning at the same storage location.

Association of objects depends on their types, as follows:

Type of Object | Type of Associated Object
--- | ---
Intrinsic numeric 1 or numeric sequence | Can be of any of these types
Default character or character sequence | Can be of either of these types 2
Any other intrinsic type | Must have the same type and kind parameters
Any other sequence type | Must have the same type
1 Default integer, default real, double precision real, default complex, double complex, or default logical. 2 The lengths do not have to be equal.

So, objects can be associated if they are of different numeric type. For example, the following is valid:

    INTEGER A(20)
    REAL Y(20)
    EQUIVALENCE(A, Y)

Objects of default character do not need to have the same length. The following example associates character variable D with the last 4 (of the 6) characters of character array F:

    CHARACTER(LEN=4) D
    CHARACTER(LEN=3) F(2)
    EQUIVALENCE(D, F(1)(3:))

Entities having different data types can be associated because multiple components of one data type can share storage with a single component of a higher-ranked data type. For example, if you make an integer variable equivalent to a complex variable, the integer variable shares storage with the real part of the complex variable.

The same storage unit cannot occur more than once in a storage sequence, and consecutive storage units cannot be specified in a way that would make them nonconsecutive.

Examples

The following EQUIVALENCE statement is invalid because it specifies the same storage unit for X(1) and X(2):

    REAL, DIMENSION(2), :: X
    REAL :: Y
    EQUIVALENCE(X(1), Y), (X(2), Y)

The following EQUIVALENCE statement is invalid because because A(1) and A(2) will not be consecutive:

    REAL A(2)
    DOUBLE PRECISION D(2)
    EQUIVALENCE(A(1), D(1)), (A(2), D(2))

In the following example, the EQUIVALENCE statement causes the four elements of the integer array IARR to share the same storage as that of the double-precision variable DVAR.

    DOUBLE PRECISION DVAR
    INTEGER(KIND=2) IARR(4)
    EQUIVALENCE(DVAR, IARR(1))

In the following example, the EQUIVALENCE statement causes the first character of the character variables KEY and STAR to share the same storage location. The character variable STAR is equivalent to the substring KEY(1:10).

    CHARACTER KEY*16, STAR*10
    EQUIVALENCE(KEY, STAR)

For More Information:

- On initialization expressions, see Section 4.1.7.1.
- On derived data types, see Section 3.2.
- On storage units, sequence, and association, see Section 16.4.3.

Previous Page Next Page Table of Contents