EOSHIFT(ARRAY, SHIFT, BOUNDARY, DIM)

Purpose

Shifts the elements of all vectors along a given dimension of an array. The shift is end-off; that is, elements shifted off one end are lost, and copies of boundary elements are shifted in at the other end.

Class

Transformational function

Argument type and attributes

ARRAY

An array of any type.

SHIFT

An INTENT(IN) INTEGER scalar, if ARRAY has a rank of 1
Otherwise, an INTENT(IN) INTEGER scalar or an INTENT(IN) expression of rank rank(ARRAY)-1

BOUNDARY (optional)

The same type and type parameters as ARRAY. If ARRAY has a rank of 1, BOUNDARY must be scalar. Otherwise, BOUNDARY is a scalar or an expression of rank=rank(ARRAY)-1, and of shape (d1, d2..., dDIM-1, dDIM+1..., dn).

DIM (optional)

An INTEGER scalar. Its value must be in the range 1 ≤ DIM ≤ rank(ARRAY).

Result value

The result is an array with the same shape, data type, and type parameters as ARRAY.

The absolute value of SHIFT determines the amount of shift. The sign of SHIFT determines the direction of the shift:

Positive SHIFT: moves each element of the vector toward the beginning of the vector. If an element is taken off the beginning of a vector, its value is replaced by the corresponding value from BOUNDARY at the end of the vector.
Negative SHIFT: moves each element of the vector toward the end of the vector. If an element is taken off the end of a vector, its value is replaced by the corresponding value from boundary at the beginning of the vector.
Zero SHIFT: does no shifting. The value of the vector remains unchanged.

Result value

If BOUNDARY is a scalar value, this value is used in all shifts.

If BOUNDARY is an array of values, the values of the array elements of BOUNDARY with subscripts (s₁, s₂, …, s_(DIM-1), s_(DIM+1), …, s_n) are used for that dimension.

If BOUNDARY is not specified, the following default values are used, depending on the data type of ARRAY:

character: '␢' (one blank)
logical: false
integer: 0
real: 0.0
complex: (0.0, 0.0)

Examples

! A is | 1.1 4.4 7.7 |,
SHIFT is S=(/0, -1, 1/),
!      | 2.2 5.5 8.8 |
!      | 3.3 6.6 9.9 |
! and BOUNDARY is the array B=(/-0.1, -0.2, -0.3/).

! Leave the first column alone, shift the second
! column down one, and shift the third column up one.
RES = EOSHIFT (A, SHIFT = S, BOUNDARY = B, DIM = 1)
! The result is | 1.1 -0.2  8.8 |
!               | 2.2  4.4  9.9 |
!               | 3.3  5.5 -0.3 |

! Do the same shifts as before, but on the
! rows instead of the columns.
RES = EOSHIFT (A, SHIFT = S, BOUNDARY = B, DIM = 2)
! The result is |  1.1  4.4  7.7 |
!               | -0.2  2.2  5.5 |
!               |  6.6  9.9 -0.3 |