eoshift

Date:

10-12-2011

NAME

EOSHIFT - Performs an end-off shift on an array expression

SYNOPSIS

EOSHIFT ([ARRAY=]array, [SHIFT=]shift [,[BOUNDARY=]boundary][,[DIM=]dim])

IMPLEMENTATION

Cray Linux Environment (CLE)

STANDARDS

Fortran

DESCRIPTION

The EOSHIFT intrinsic function performs an end-off shift on an array expression of rank one, or it performs end-off shifts on all the complete rank one sections along a given array expression of rank two or greater. Elements are shifted off at one end of a section and copies of a boundary value are shifted in at the other end. Different sections can have different boundary values and can be shifted by different amounts and in different directions: positive for left shifts, negative for right shifts.

EOSHIFT accepts the following arguments:

array

May be of any type. It must not be scalar.

shift

Must be integer. If array has rank one, shift must be a scalar. Otherwise, shift must be scalar or have rank n-1 and have this shape:

(d1, d2, ..., ddim-1, ddim+1, ..., dn)

• where

(ds, d2, ..., dn)

• is the shape of array.

boundary

Must be of the same type and have the same type parameters as array. Must be scalar if array has rank one; otherwise, it must be either scalar or of rank n-1 and of shape:

(d1, d2, ..., ddim-1, ddim+1, ..., dn)

• The boundary argument can be omitted for the data types in the following list. In these cases, the default value is the scalar value shown:

-------------------------------------------
Type of array     Default Value of boundary
-------------------------------------------
Integer           0
Real              0.0
Complex           (0.0,0.0)
Logical           false
Character(len)    len blanks
-------------------------------------------

The boundary data type must be present for derived data types.

dim

Must be a scalar. Must be an integer value in the range 1 <= dim <= n, where n is the rank of array. If dim is omitted, the default value is 1.

EOSHIFT is a transformational intrinsic function. The name of this intrinsic cannot be passed as an argument.

RETURN VALUES

The result is an array of the same type, type parameters, and shape as array.

Element

(s1, s2, …, sn)

of the result has the value

array(s1, s2, …, sdim-1, sdim + sh, sdim+1, …, sn)

where sh is shift or

shift(s1, s2, …, sdim-1, sdim+1, …, sn)

provided that the inequality LBOUND(array,dim) <= sdim + sh <= UBOUND(array,dim)

holds and is otherwise boundary or

boundary(s1, s2, ..., sdim-1, sdim+1, ..., sn)

EXAMPLES

Example 1: If V is array [1,2,3,4,5,6], the effect of shifting V end-off to the left by three positions is achieved by EOSHIFT(V,SHIFT=3), which yields [4,5,6,0,0,0]. Specifying EOSHIFT(V,SHIFT=-2,BOUNDARY=99) achieves an end-off shift to the right by two positions with the boundary value of 99 and yields [99,99,1,2,3,4].

Example 2: The rows of an array of rank two can all be shifted by the same amount or by different amounts and the boundary elements can be the same or different. Assume that M is the following array:

| A B C |
| D E F |
| G H I |

EOSHIFT(M,SHIFT=-1,BOUNDARY=’*’,DIM=2) yields:

| * A B |
| * D E |
| * G H |

EOSHIFT(M,SHIFT=(/-1,1,0/),BOUNDARY=(/’*’,’/’,’?’/),DIM=2) yields:

| * A B |
| E F / |
| G H I |

Section EOSHIFT(M(2:3,2:3),SHIFT=-1,BOUNDARY=’*’,DIM=2) yields:

| * E |
| * H |