Intel® Fortran Compiler 16.0 User and Reference Guide

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.

EQUIVALENCE (equiv-list) [,(equiv-list)]...

equiv-list

Is a list of two or more variable names, 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.

Description

The following objects cannot be specified in EQUIVALENCE statements:

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

If an equivalence object has the PROTECTED attribute, all of the objects in the equivalence set must have the PROTECTED attribute.

Association of objects depends on their types, as follows:

Type of Object

Type of Associated Object

Intrinsic numeric 1or 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

1Default integer, default real, double precision real, default complex, double complex, or default logical.

2The 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.

Intel® Fortran lets you associate character and noncharacter entities, for example:

  CHARACTER*1 char1(10)
  REAL reala, realb
  EQUIVALENCE (reala, char1(1))
  EQUIVALENCE (realb, char1(2))

EQUIVALENCE statements require only the first subscript of a multidimensional array (unless the STRICT compiler directive is in effect). For example, the array declaration var(3,3), var(4) could appear in an EQUIVALENCE statement. The reference is to the fourth element of the array (var(1,2)), not to the beginning of the fourth row or column.

If you use the STRICT directive, the following rules apply to the kinds of variables and arrays that you can associate:

Example

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 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)

The following shows another example:

  CHARACTER name, first, middle, last
  DIMENSION name(60), first(20), middle(20), last(20)
  EQUIVALENCE (name(1), first(1)), (name(21), middle(1))
  EQUIVALENCE (name(41), last(1))

Consider the following:

  CHARACTER (LEN = 4) :: a, b
  CHARACTER (LEN = 3) :: c(2)
  EQUIVALENCE (a, c(1)), (b, c(2))

This causes the following alignment:

   1          2          3          4          5          6          7
 a(1:1)     a(2:2)     a(3:3)     a(4:4)
                                  b(1:1)     b(2:2)     b(3:3)     b(4:4)
 c(1)(1:1)  c(1)(2:2)  c(1)(3:3)  c(2)(1:1)  c(2)(2:2)  c(2)(3:3)

Note that the fourth element of a, the first element of b, and the first element of c(2) share the same storage unit.

See Also