7.15 ASSOCIATED — Status of a pointer or pointer/target pair

Description:

ASSOCIATED(PTR [, TGT]) determines the status of the pointer PTR or if PTR is associated with the target TGT.

Option:

f95, gnu

Class:

inquiry function

Syntax:

L = ASSOCIATED(PTR) L = ASSOCIATED(PTR [, TGT])

Arguments:

PTR	PTR shall have the POINTER attribute and it can be of any type.
TGT	(Optional) TGT shall be a POINTER or a TARGET. It must have the same type, kind type parameter, and array rank as PTR.

The status of neither PTR nor TGT can be undefined.

Return value:

ASSOCIATED(PTR) returns a scalar value of type LOGICAL(4). There are several cases:

(A) If the optional TGT is not present, then ASSOCIATED(PTR)

is true if PTR is associated with a target; otherwise, it returns false.

(B) If TGT is present and a scalar target, the result is true if

TGT is not a 0 sized storage sequence and the target associated with PTR occupies the same storage units. If PTR is disassociated, then the result is false.

(C) If TGT is present and an array target, the result is true if

TGT and PTR have the same shape, are not 0 sized arrays, are arrays whose elements are not 0 sized storage sequences, and TGT and PTR occupy the same storage units in array element order. As in case(B), the result is false, if PTR is disassociated.

(D) If TGT is present and an scalar pointer, the result is true if

target associated with PTR and the target associated with TGT are not 0 sized storage sequences and occupy the same storage units. The result is false, if either TGT or PTR is disassociated.

(E) If TGT is present and an array pointer, the result is true if

target associated with PTR and the target associated with TGT have the same shape, are not 0 sized arrays, are arrays whose elements are not 0 sized storage sequences, and TGT and PTR occupy the same storage units in array element order. The result is false, if either TGT or PTR is disassociated.

Example:

          program test_associated
             implicit none
             real, target  :: tgt(2) = (/1., 2./)
             real, pointer :: ptr(:)
             ptr => tgt
             if (associated(ptr)     .eqv. .false.) call abort
             if (associated(ptr,tgt) .eqv. .false.) call abort
          end program test_associated