EQUIVALENCE

Associates different objects with same storage area.

Syntax

EQUIVALENCE (equivalence-list1) [, (equivalence-list2)]...

Description

All objects in each equivalence-list share the same storage area. Such objects become storage associated and are equivalenced to each other. Equivalencing may also cause other objects to become storage associated.

The following items must not appear in equivalence-list:

Derived-type objects may appear in an EQUIVALENCE statement if they have been defined with the SEQUENCE attribute.

The following restrictions apply to objects that can appear in an EQUIVALENCE statement:

The Fortran 90 standard imposes the following type restrictions on equivalenced objects:

The EQUIVALENCE statement does not cause type conversion or imply mathematical equivalence. If an array and a scalar share the same storage space through the EQUIVALENCE statement, the array does not have the characteristics of a scalar and the scalar does not have the characteristics of an array. They only share the same storage space.

Care should be taken when data types of different sizes share the same storage space, because the EQUIVALENCE statement specifies that each data item in equivalence-list has the same first storage unit. For example, if a 4-byte integer variable and a double-precision variable are equivalenced, the integer variable shares the same space as the 4 most significant bytes of the 8-byte double-precision variable.

Proper alignment of data types is always enforced. The compiler will issue a diagnostic if incorrect alignment is forced through an EQUIVALENCE statement. For data type alignment rules, see “Intrinsic data types”.

The lengths of the equivalenced objects need not be the same.

Equivalencing character data

An EQUIVALENCE statement specifies that the storage sequences of character data items whose names are specified in equivalence-list have the same first character storage unit. This causes the association of the data items in equivalence-list and can cause association of other data items as well. Consider the following example:

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

As a result of this EQUIVALENCE statement, the fourth character in a, the first character in b, and the first character in c(2) share the same storage.

Strings of the same or different lengths can be equivalenced to start on the first element, and you can use substring notation to specify other associations, as in the following:

CHARACTER (10) :: s1, s2
EQUIVALENCE (s1(2:2), s2(3:3)

Substring subscripts must be integer initialization expressions, and the substring length must be nonzero.

Equivalencing arrays

To determine equivalence between arrays with different dimensions, HP Fortran 90 views all elements of an array in linear sequence. Each array is stored as if it were a one-dimensional array. Array elements are stored in ascending sequential, column-major order; for information about how arrays are laid out in memory, see “Array fundamentals”.

Array elements can be equivalenced with elements of a different array or with scalars. No equivalence occurs outside the bounds of any of the equivalenced arrays.

If equivalenced arrays are not of the same type, they may not line up element by element.

If an array name appears without subscripts in an EQUIVALENCE statement, it has the same effect as specifying an array name with the subscript of its first element.

It is illegal to equivalence different elements of the same array to the same storage area. For example, the following is illegal:

INTEGER :: a(2), b
EQUIVALENCE (a(1), b), (a(2), b)

Likewise, it is illegal to use the EQUIVALENCE statement to force consecutive array elements to be noncontiguous, as in the following example:

REAL :: a(2), r(3)
EQUIVALENCE (a(1), r(1)), (a(2), r(3))

Array subscripts must be integer initialization expressions.

Equivalence in common blocks

An EQUIVALENCE statement must not cause two common blocks to be associated. However, you can use the EQUIVALENCE statement to place objects in common by equivalencing them to objects already in common. If one element of an array is equivalenced to an object in common, the whole array is placed in common with equivalence maintained for storage units preceding and following the data element in common. The common block is always extended when it is necessary to fit an array that shares storage space in the common block. It may be extended after the last entry, but not before the first.

Consider the following example, which puts array i in blank common and equivalences array element j(2) to i(3):

INTEGER :: i(6), j(6)
COMMON i
EQUIVALENCE (i(3), j(2))

The effect of the EQUIVALENCE statement is to extend blank common to include element j(6). This is entirely legal because the extension occurs at the end of the common block.

But if the EQUIVALENCE statement were changed as follows:

EQUIVALENCE (i(1), j(2))  ! illegal

it would result in an illegal equivalence, because storage would have to be inserted in front of the block in order to accommodate element j(1).

Examples

In the following example, the variables a, b, and c share the same storage space; array elements d(2) and e(5) share the same storage space; variables f, g, and h share the same storage:

INTEGER :: a, b, c, d(20), e(30), f, g, h
EQUIVALENCE (a, b, c), (d(2), e(5)), (f, g, h)

Related statements

COMMON

Related concepts

For information about data alignment, see Table 3-1 “Intrinsic data types” and “Alignment of derived-type objects”.