ALLOCATE
Purpose
The ALLOCATE statement dynamically provides storage for pointer targets and allocatable objects.
Syntax
- stat_variable
- A scalar integer variable.
- errmsg_variable (Fortran 2003)
- A scalar character variable.
- source_expr (Fortran 2003)
- An expression that is scalar or has the same rank as allocate_object.
- i_d_type_spec (Fortran 2003)
- Is an intrinsic_type_spec or derived_type_spec. See Type Declaration for a list of possible type specifications.
allocation_list
- allocate_object
- A variable name or structure component that must be a data pointer or an allocatable object.
- lower_bound
- A scalar integer expression.
- upper_bound
- A scalar integer expression.
Constraints
You cannot specify i_d_type_spec and source_expr at the same time.
If any
allocate_object has deferred type parameters, is unlimited
polymorphic
, or is of an abstract type
, i_d_type_spec or
source_expr must appear.
i_d_type_spec must specify a type with which each allocate_object is type compatible.
A type parameter value in i_d_type_spec must be an asterisk if and only if each allocate_object is a dummy argument whose corresponding type parameter is assumed.
The kind type parameter values of each allocate_object must be the same as the corresponding type parameter values of i_d_type_spec.
If allocate_object is an array, you must specify either the array bounds or source_expr with the same rank as allocate_object. If allocate_object is scalar, array bounds cannot be specified.
If source_expr appears,
each allocate_object must be type-compatible with
source_expr.
Corresponding kind type parameters of allocate_object and source_expr must have the same values.
Rules
Execution of an ALLOCATE statement for a pointer causes the pointer to become associated with the target allocated. Execution of an ALLOCATE statement for an allocatable object causes the object to become definable.
If you specify bounds for an array, the number of dimensions specified (that is, the number of
upper bounds in allocation_list) must be equal to the rank of
allocate_object. Otherwise, you must specify
SOURCE= or MOLD=, and the bounds of
source_expr determine the bounds of the array. Subsequent changes to the
bounds of source_expr do not affect the array bounds after they are
determined.
If i_d_type_spec is specified, each
allocate_object is allocated with the specified dynamic type and type
parameter values. If source_expr is specified, each
allocate_object is allocated with the dynamic type and type parameter
values of source_expr. Otherwise, each
allocate_object is allocated with the same dynamic type as its declared
type.
When an ALLOCATE statement is executed for an array, the values of the bounds are determined at that time. Subsequent redefinition or undefinition of any entities in the bound expressions does not affect the array specification. Any lower bound, if omitted, is assigned a default value of 1. If any lower bound value exceeds the corresponding upper bound value, that dimension has an extent of 0 and allocate_object is zero-sized.
Any allocate_object or a specified bound of an allocate_object must not depend on the value of stat_variable or errmsg_variable, or on the value, bounds, length type parameters, allocation status, or association status of any allocate_object in the same ALLOCATE statement.
stat_variable,source_expr, and
errmsg_variable must not be allocated within the
ALLOCATE statement in which they appear. They also must not depend on the
value, bounds, length type parameters, allocation status, or association status of any
allocate_object in the same ALLOCATE
statement.
If you specify MOLD= and
source_expr is a variable, its value need not be defined. In addition,
MOLD= does not copy the value of source_expr to
the variable to be allocated.
If the STAT= specifier is not present and an error condition occurs during execution of the statement, the program terminates. If the STAT= specifier is present, the stat_variable is assigned one of the following values:
| Stat value | Error condition |
|---|---|
| 0 | No error |
| 1 | Error in system routine attempting to do allocation |
| 2 | An invalid data object has been specified for allocation |
| 3 | Both error conditions 1 and 2 have occurred |
If an error condition occurs during execution of the
ALLOCATE statement and the ERRMSG=specifier is present,
an explanatory message is assigned to errmsg_variable. If no such
condition occurs, the value of errmsg_variable is not changed.
Allocating an allocatable object that is already allocated causes an error condition in the ALLOCATE statement.
- A new target is created and the pointer becomes associated with this target.
- Any previous association with the pointer is broken.
- Any previous target that had been created by allocation and is not associated with any other pointers becomes inaccessible.
When an object of derived type is created by an ALLOCATE statement, any allocatable ultimate components have an allocation status of not allocated.
Use the ALLOCATED intrinsic function to determine if an allocatable object is allocated. Use the ASSOCIATED intrinsic function to determine the association status of a pointer or whether a pointer is associated with a specified target.
Examples
CHARACTER, POINTER :: P(:,:)
CHARACTER, TARGET :: C(4,4)
INTEGER, ALLOCATABLE, DIMENSION(:) :: A
P => C
N = 2; M = N
ALLOCATE (P(N,M),STAT=I) ! P is no longer associated with C
N = 3 ! Target array for P maintains 2X2 shape
IF (.NOT.ALLOCATED(A)) ALLOCATE (A(N**2))
ENDINTEGER, ALLOCATABLE :: NEW(:)
INTEGER, POINTER :: OLD(:)
ALLOCATE(OLD(4))
ALLOCATE (NEW, MOLD=OLD) ! Allocate NEW with the bounds of OLD
END