associated

Date:

10-12-2011

NAME

ASSOCIATED - Returns the pointer association status

SYNOPSIS

ASSOCIATED ([POINTER=]pointer [,[TARGET=]target])

STANDARDS

Fortran

DESCRIPTION

The ASSOCIATED intrinsic function returns the association status of its pointer argument or indicates the pointer is associated with the target. It accepts the following arguments:

pointer

Must be a pointer and can be any type or may be a procedure pointer. Its pointer-associated status must not be undefined.

target

Must be a pointer or a data target or procedure target. If it is a pointer, its pointer-associated status must not be undefined.

ASSOCIATED is an inquiry function. The name of this intrinsic cannot be passed as an argument.

RETURN VALUES

The result is of type default logical.

If TARGET is absent, the result is true if POINTER is currently associated with a target and false if it is not.

If TARGET is present and is a procedure, the result is true if POINTER is associated with TARGET.

If TARGET is present and is a procedure pointer, the result is true if POINTER and TARGET are associated with the same procedure. If either POINTER or TARGET is disassociated, the result is false.

If TARGET is present and is a scalar target, the result is true if TARGET is not a zero-sized storage sequence and the target associated with POINTER occupies the same storage units as TARGET. Otherwise, the result is false. If POINTER is disassociated, the result is false.

If TARGET is present and is an array target, the result is true if the target associated with POINTER and TARGET have the same shape, are neither of size zero nor arrays whose elements are zero-sized storage sequences, and occupy the same storage units in array element order. Otherwise, the result is false. If POINTER is disassociated, the result is false.

If TARGET is present and is a scalar pointer, the result is true if the target associated with POINTER and the target associated with TARGET are not zero-sized storage sequences and they occupy the same storage units. Otherwise, the result is false. If either POINTER or TARGET is disassociated, the result is false.

If TARGET is present and is an array pointer, the result is true if the target associated with POINTER and the target associated with TARGET have same shape, are neither of size zero nor arrays whose elements are zero-sized storage sequences, and occupy the same storage units in array-element order. Otherwise, the result is false. If either POINTER or TARGET is disassociated, the result is false.

EXAMPLES

Example 1: ASSOCIATED(CURRENT,HEAD) yields true if CURRENT points to the target HEAD.

Example 2: Consider the following statement:

A_PART => A (:N)

After the preceding statement is executed, the statement ASSOCIATED(A_PART,A) yields true if N is equal to UBOUND(A,DIM=1).

Example 3: After the execution of the following statements, ASSOCIATED(CUR,TOP) yields false:

NULLIFY(CUR);  NULLIFY(TOP)