EQUIVALENCE

Intel® Fortran Compiler Classic and Intel® Fortran Compiler Developer Guide and Reference

Download PDF

ID 767251

Date 9/08/2022

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-0F6B72B8-0679-4272-8CB6-CEA91200294D

View Details

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 is an obsolescent language feature in Standard Fortran.

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 constant 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:

Type of Object	Type of Associated Object
Intrinsic numeric ¹or numeric sequence	Can be of any of these types
Default character or character sequence	Can be of either of these types ²
Any other intrinsic type	Must have the same type and kind parameters
Any other sequence type	Must have the same type
¹Default integer, default real, double precision real, default complex, double complex, or default logical. ²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.

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.

Parent topic: E to F

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Intel® Fortran Compiler Classic and Intel® Fortran Compiler Developer Guide and Reference

EQUIVALENCE

See Also