J3/03-137

To: J3
From: UK Fortran panel
Subject: Edits for UK comment TC11 (Reallocate arrays)
Date: 11 March 2003

Comment TC11 of the UK vote was:

    Allow reallocation of allocatable arrays

    It should be possible to reallocate arrays; given the existence of
    the RESHAPE function this should apply to arrays of any rank.  The
    value preserved should be via array element ordering, as with
    RESHAPE.  We prefer a REALLOCATE procedure but could accept a
    facility like the SWAP_ALLOCATION procedure which has been
    suggested.

An actual implementation will probably allocate separate storage,
copy the elements across, then deallocate the old storage. This
is more efficient than can be done by the Fortran 95 programmer,
who has to do a double copy (allocate a temporary, copy the data
to it, deallocate the old array, allocate with the new extents,
copy the data into it, and finally deallocate the temporary).

The implementation may sometimes be able to avoid any copying.

We have chosen to allow the new array to be smaller than the old
array.

We have chosen to require that the new lower bounds be specified.  If
they were optional and a call without them were not to require the use
of a keyword, they would have to be placed later in the argument list,
which seems unnatural. Further, some users will want the default lower
bound values to be the old ones and others will want them all to be 1.

We also offer an alternative version of the procedure itself, in which
each old value is preserved in the new element that is addressed by
the same set of subscript values.

Here are the edits:

75:3. Before "or" add ", an invocation of the intrinsic subroutine
    REALLOCATE (13.7.93a),".

77:29. After "allocated" add "or reallocated".

269:8. After "allocated" add ", reallocated".

293:12. Change "functions" to "procedures".

293:17+. Add

   REALLOCATE (ARRAY, LOWER, UPPER   Reallocates an allocatable array
       [, STAT, ERRMSG])

340:14+. Add

   13.7.93a  REALLOCATE (ARRAY, LOWER, UPPER [, STAT, ERRMSG])

   Description. Reallocates an allocatable array.

   Class. Subroutine.

   Arguments.

   ARRAY shall be an allocated allocatable array of any type. It is
      reallocated to have lower bounds LOWER and upper bounds UPPER.
      The definition status and values of the first <n> elements of the
      output ARRAY, in array element order, shall be those of the first
      <n> elements of the input ARRAY in array element order, where <n>
      is the minimum of the sizes of the input ARRAY and the output
      ARRAY. Other elements of the output ARRAY are undefined. If an
      error condition occurs, the allocation status and value of ARRAY
      shall not be altered.
...............
Alternative
   ARRAY shall be an allocated allocatable array of any type. It is
      reallocated to have lower bounds LOWER and upper bounds UPPER.
      If ARRAY (I1,I2,..) is an element of the array both before and
      after the reallocation, its definition status and value shall be
      the same. Other elements of the output ARRAY are undefined. If an
      error condition occurs, the allocation status and value of ARRAY
      shall not be altered.
...............

   LOWER shall be of type default integer, rank one, and size equal
      to the rank of ARRAY. It is an INTENT(IN) argument and specifies
      the new lower bounds.

   UPPER shall be of type default integer, rank one, and size equal to
      the rank of ARRAY. It is an INTENT(IN) argument and specifies the
      new upper bounds.

   STAT (optional) shall be scalar and of type default integer. It is
      an INTENT(OUT) argument. If present, successful execution of the
      subroutine causes STAT to become defined with the value zero and
      an error condition causes STAT to become defined with a
      processor-dependent positive value. If STAT is not present and an
      error condition occurs, execution of the program is terminated.

   ERRMSG (optional) shall be scalar and of type default character. It
      is an INTENT(INOUT) argument. If present, successful execution of
      the subroutine does not change the value of ERRMSG but an error
      condition causes ERRMSG to become defined with a
      processor-dependent explanatory message.

   Example.

   The following code allocates an 8 x 8 array A and sets its element
   values to A(I,J) to I+J. It then reallocates A to have bounds
   (0:10,0:10). The values of the first 64 elements of A are unchanged
   and the values of the other entries are undefined.
...............
Alternative
   The following code allocates an 8 x 8 array A and sets its element
   values to A(I,J) to I+J. It then reallocates A to have bounds
   (0:10,0:10). The values of A(I,J) are still I+J for 1<=I<=8 and
   1<=J<=8, but the values of the other entries are undefined.
...............

     REAL, ALLOCATABLE :: A (:,:)
     INTEGER :: I,J
     ALLOCATE (A(8,8))
     DO I = 1,8; DO J = 1,8; A(I,J) = I+J; END DO; END DO
     CALL REALLOCATE (A, [0,0], [10,10])