EQUIVALENCE

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:

• A dummy argument

• An allocatable variable

• An automatic object

• A pointer

• An object of nonsequence derived type

• A derived-type object that has an allocatable or pointer component at any level

• A component of a derived-type object

• A function, entry, or result name

• A named constant

• A structure component

• A subobject of any of the above objects

• A coarray

• An object with either the DLLIMPORT or DLLEXPORT attribute

• A variable with the BIND attribute

• A variable in a common block that has the BIND attribute

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:

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:

• If an EQUIVALENCE object is default integer, default real, double-precision real, default complex, default logical, or a sequenced derived type of all numeric or logical components, all objects in the EQUIVALENCE statement must be one of these types, though it is not necessary that they be the same type.

• If an EQUIVALENCE object is default character or a sequenced derived type of all character components, all objects in the EQUIVALENCE statement must be one of these types. The lengths do not need to be the same.

• If an EQUIVALENCE object is a sequenced derived type that is not purely numeric or purely character, all objects in the EQUIVALENCE statement must be the same derived type.

• If an EQUIVALENCE object is an intrinsic type other than the default (for example, INTEGER(1)), all objects in the EQUIVALENCE statement must be the same type and kind.

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.