Subject: MOVE_ALLOC / SWAP_ALLOC Edits                  J3/03-162
From: Kurt W. Hirchert                  (Meeting 164) 14 Mar 2003

J3/03-161 contains my analysis of the functionality request in
UK ballot item TC11, including the rationale for why I am offering
these edits.  The edits themselves come from J3/01-161, with page
and line numbers adjusted for the current draft and extension to
add SWAP_ALLOC.  (My own personal preference would be to add only
MOVE_ALLOC, but I believe it would be easier for the committee
to cut down edits for both into edits for just one of these
intrinsics than to start with the edits for one and convert them
into the edits for the other or the edits for doing both.)

=====
Edits
=====

[287:15] "subroutine MVBITS is" -> "subroutines MOVE_ALLOC, MVBITS,
         and SWAP_ALLOC are"
[287:15+1] "The" -> "MOVE_ALLOC and SWAP_ALLOC are not elemental,
         but their effects are limited to their arguments.  The
	 remaining"
[293:25+] Insert "
13.5.15+1  Alloocation transfer procedures
MOVE_ALLOC(TO,FROM)     Transfers an allocation from one
                         allocatable object to another
SWAP_ALLOC(A,B)         Swaps the allocations of two
                         allocatable objects"
[332:28+] Insert text
<<<<<
13.7.79+1  MOVE_ALLOC(TO,FROM)

Description. Transfers an allocation from one allocatable object
to another.

Class.  Subroutine.

Arguments.

TO      shall be type compatible (5.1.1.8) with FROM and have the
         same rank.  It shall be allocatable.  It is an INTENT(OUT)
         argument.  Its nondeferred type parameters shall have the
         same values as the corresponding type parameters of the
         current allocation, if any, of FROM.  No declared
         nondeferred type parameter of TO shall differ in value
         from a corresponding declared nondeferred type parameter
         of FROM.

FROM    may be of any type and rank.  It shall be allocatable.  It
         is an INTENT(INOUT) argument.

If FROM is not currently allocated, TO becomes not currently
allocated; otherwise, the allocation of FROM is transferred to TO,
including its bounds, type, and type parameters, and FROM becomes
not currently allocated.

If a pointer is associated with the allocation of FROM, it becomes
associated with TO if TO has the TARGET attribute, and its pointer
association status becomes undefined otherwise.

Example.

       REAL,ALLOCATABLE :: GRID(:),TEMPGRID(:)
       ...
       ALLOCATE(GRID(-N:N)       ! initial allocation of GRID
       ...
! "reallocation" of GRID to allow intermediate points
       ALLOCATE(TEMPGRID(LBOUND(GRID,1)*2:UBOUND(GRID,1)*2))
                         ! allocate bigger grid
       TEMPGRID(::2)=GRID! distribute values to new locations
       CALL MOVE_ALLOC(TO=GRID,FROM=TEMPGRID)
                         ! old grid is deallocated because TO is
                         ! INTENT(OUT), and GRID then "takes over"
                         ! new grid allocation
>>>>>
348:17+  Insert text
<<<<<
13.17.112+1  SWAP_ALLOC(A,B)

Description. Swaps the allocations of two allocatable objects

Class.  Subroutine.

Arguments.

A       may be of any type and rank.  It shall be allocatable.
         It is an INTENT(INOUT) argument.

B       shall have the same type and rank as A.  It shall be
         allocatable.  It is an INTENT(INOUT) argument.  It shall
	 have the same deferred type parameters as A.  No
	 nondeferred type parameter of B shall differ in value
	 from the corresponding type parameter of A.

If either argument is not currently allocated, the other becomes
not currently allocated; otherwise, the allocation of each is
transferred to the other, including its bounds, type, and type
parameters.

If a pointer is associated with the allocation of either argument,
it becomes associated with the other argument if that other
argument has the TARGET attribute, and its pointer association
status becomes undefined otherwise.

Example.

       REAL,ALLOCATABLE :: GRID(:),TEMPGRID(:)
       ...
       ALLOCATE(GRID(-N:N)       ! initial allocation of GRID
       ...
! "reallocation" of GRID to allow intermediate points
       ALLOCATE(TEMPGRID(LBOUND(GRID,1)*2:UBOUND(GRID,1)*2))
                         ! allocate bigger grid
       TEMPGRID(::2)=GRID! distribute values to new locations
       DEALLOCATE(GRID)  ! free the old allocation
       CALL SWAP_ALLOC(GRID,TEMPGRID)
                         ! swap the new allocation to GRIB
>>>>>
[404:29+] Insert "
(2+1) The target of the pointer is transferred by MOVE_ALLOC or
       SWAP_ALLOC to an allocatable object without the TARGET
       attribute."
[411:4+] Insert "
(19+1) Transfer of an allocation by MOVE_ALLOC or SWAP_ALLOC causes
        the receiving object to be defined if the source object was."
[412:21+] Insert "
(9+1) When MOVE_ALLOC or SWAP_ALLOC causes an allocatable entity
       to become not currently allocated, it becomes undefined."

                              - end -

--
Kurt W Hirchert                                  hirchert@atmos.uiuc.edu
UIUC Department of Atmospheric Sciences                  +1-217-265-0327