S3L_cshift

S3L_cshift performs a circular shift of a specified amount along a specified axis of the parallel array associated with array handle A. The argument axis indicates the dimension to be shifted, and index prescribes the shift distance.

Shift direction is upwards for positive index values and downward for negative index values.

For example, if A denotes a one-dimensional array of length n before the cshift, B denotes the same array after the cshift, and index is equal to 1, the array A will be circularly shifted upwards, as shown below:

For C Programs

B[1:n-1]=A[0:n-2], B[0]=A[n-1]

For Fortran Programs

B(2:n)=A(1:n-1), B(1)=A(n)

Syntax

The C and Fortran syntax for S3L_cshift are shown below.

C/C++ Syntax

Example 7-25

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_cshift(A, axis, index)
    S3L_array_t         A
    void                axis
    int                 index

F77/F90 Syntax

Example 7-26

include `s3l/s3l-f.h
include `s3l/s3l_errno-f.h'
subroutine
S3L_cshift(A, axis, index,
ier)
    integer*8          A
    integer*4          axis
    integer*4          index
    integer*4          ier

Input

S3L_cshift accepts the following arguments as input:

• A - Array handle for the parallel array to be shifted.

• axis - Specifies the axis along which the shift is to take place. This value must assume zero-based axis indexing when S3L_cshift is called from a C or C++ application and one-based indexing when called from an F77 or F90 application.

• index - Specifies the shift distance. If the extent of the axis being shifted is N, legal values for index are: -N < index < N.

Output

S3L_cshift uses the following argument for output:

• ier (Fortran only) - When called from a Fortran program, S3L_cshift returns error status in ier.

Error Handling

On success, S3L_cshift returns S3L_SUCCESS.

S3L_cshift performs generic checking of the validity of the arrays it accepts as arguments. If an array argument contains an invalid or corrupted value, the function terminates and an error code indicating which value of the array handle was invalid is returned. See Appendix A of this manual for a detailed list of these error codes.

In addition, the following condition will cause the function to terminate and return the associated error code:

• S3L_ERR_ARG_AXISNUM - Invalid axis value.

• S3L_ERR_INDX_INVALID - index value is out of range.

Examples

../examples/s3l/utils/cshift_reduce.c
../examples/s3l/utils-f/cshift_reduce.f

Related Functions

S3L_reduce
S3L_reduce_axis