---

Manual Reference Pages  - merge (3fortran)

---

NAME

MERGE(3) - [ARRAY:CONSTRUCTION] Merge variables

SYNOPSIS

result = merge(tsource, fsource, mask)

         elemental type(TYPE(kind=KIND)) function merge(tsource,fsource,mask)

          type(TYPE(kind=KIND)),intent(in) :: tsource
          type(TYPE(kind=KIND)),intent(in) :: fsource
          logical(kind=**),intent(in)      :: mask

CHARACTERISTICS

o	a kind designated as ** may be any supported kind for the type
o	TSOURCE May be of any type, including user-defined.
o	FSOURCE Shall be of the same type and type parameters as TSOURCE.
o	MASK shall be of type logical.
o	The result will by of the same type and type parameters as TSOURCE.

DESCRIPTION

The elemental function MERGE(3) selects values from two arrays or scalars according to a logical mask. The result is equal to an element of TSOURCE where the corresponding element of MASK is .true., or an element of FSOURCE when it is .false. .

Multi-dimensional arrays are supported.

Note that argument expressions to MERGE(3) are not required to be short-circuited so (as an example) if the array X contains zero values in the statement below the standard does not prevent floating point divide by zero being generated; as 1.0/X may be evaluated for all values of X before the mask is used to select which value to retain:

          y = merge( 1.0/x, 0.0, x /= 0.0 )

Note the compiler is also free to short-circuit or to generate an infinity so this may work in many programming environments but is not recommended.

For cases like this one may instead use masked assignment via the WHERE construct:

          where(x .ne. 0.0)
             y = 1.0/x
          elsewhere
             y = 0.0
          endwhere

instead of the more obscure

          merge(1.0/merge(x,1.0,x /= 0.0), 0.0, x /= 0.0)

OPTIONS

o	TSOURCE : May be of any type, including user-defined.
o	FSOURCE : Shall be of the same type and type parameters as TSOURCE.
o	MASK : Shall be of type logical.

Note that (currently) character values must be of the same length.

RESULT

The result is built from an element of TSOURCE if MASK is .true. and from FSOURCE otherwise.

Because TSOURCE and FSOURCE are required to have the same type and type parameters (for both the declared and dynamic types), the result is polymorphic if and only if both TSOURCE and FSOURCE are polymorphic.

EXAMPLES

Sample program:

    program demo_merge
    implicit none
    integer :: tvals(2,3), fvals(2,3), answer(2,3)
    logical :: mask(2,3)
    integer :: i
    integer :: k
    logical :: chooseleft

       ! Works with scalars
       k=5
       write(*,*)merge (1.0, 0.0, k > 0)
       k=-2
       write(*,*)merge (1.0, 0.0, k > 0)

       ! set up some simple arrays that all conform to the
       ! same shape
       tvals(1,:)=[  10, -60,  50 ]
       tvals(2,:)=[ -20,  40, -60 ]

       fvals(1,:)=[ 0, 3, 2 ]
       fvals(2,:)=[ 7, 4, 8 ]

       mask(1,:)=[ .true.,  .false., .true. ]
       mask(2,:)=[ .false., .false., .true. ]

       ! lets use the mask of specific values
       write(*,*)’mask of logicals’
       answer=merge( tvals, fvals, mask )
       call printme()

       ! more typically the mask is an expression
       write(*, *)’highest values’
       answer=merge( tvals, fvals, tvals > fvals )
       call printme()

       write(*, *)’lowest values’
       answer=merge( tvals, fvals, tvals < fvals )
       call printme()

       write(*, *)’zero out negative values’
       answer=merge( 0, tvals, tvals < 0)
       call printme()

       write(*, *)’binary choice’
       chooseleft=.false.
       write(*, ’(3i4)’)merge([1,2,3],[10,20,30],chooseleft)
       chooseleft=.true.
       write(*, ’(3i4)’)merge([1,2,3],[10,20,30],chooseleft)

    contains

    subroutine printme()
          write(*, ’(3i4)’)(answer(i, :), i=1, size(answer, dim=1))
    end subroutine printme

    end program demo_merge

Results:

     >    1.00000000
     >    0.00000000
     >  mask of logicals
     >   10   3  50
     >    7   4 -60
     >  highest values
     >   10   3  50
     >    7  40   8
     >  lowest values
     >    0 -60   2
     >  -20   4 -60
     >  zero out negative values
     >   10   0  50
     >    0  40   0
     >  binary choice
     >   10  20  30
     >    1   2   3

STANDARD

Fortran 95

SEE ALSO

o	PACK(3) packs an array into an array of rank one
o	SPREAD(3) is used to add a dimension and replicate data
o	UNPACK(3) scatters the elements of a vector
o	TRANSPOSE(3) - Transpose an array of rank two

Fortran intrinsic descriptions (license: MIT) @urbanjost

---

Nemo Release 3.1

merge (3fortran)

November 02, 2024

Generated by manServer 1.08 from e489ad8e-a5db-4237-ad14-19d3e1542671 using man macros.