>

REVERSE_N

 NAME:
REVERSE_N

PURPOSE:
       This function reverses the ordering of data in an input array,
       which may have up to 7 dimensions.  The precise action taken
       depends on the number of dimensions of the input array:
   
   Scalar:     returns the unaltered scalar.
   Vector:     returns the vector with indices reversed
   2-d to 7-d: array is reversed along the specified dimension.

 CATEGORY:
   Array manipulation.

 CALLING SEQUENCE:
   Result = REVERSE_N(Array [,Subscript])

INPUTS:
   Array:      Scalar, vector, or 2- to 7- dimensional array
           of any numerical type.

 OPTIONAL INPUTS:
       Subscript:  Dimension of the input array in which to reverse 
           order of elements, where 1 is the first (most rapidly
           varying) dimension.  Subscript must be between 1 and
           number of dimensions of Array.
           The first dimension is reversed by default.

 KEYWORD PARAMETERS:
   None.

 OUTPUTS:
   The function return value is a copy of the original array
   that is reversed about one of its dimensions.

 COMMON BLOCKS:
   None.

 SIDE EFFECTS:
   None.

*RESTRICTIONS:
   Works only for 1- to 7-dimensional arrays,
   due to bug on some platforms in using 8 subscripts to index arrays.

 PROCEDURE:
   Uses the ROTATE function for 1- and 2-d arrays.
   Extracts and swaps subarrays along specified axis
           for arrays of 3 to 7 dimensions.

 EXAMPLE:

   Reverse first dimension by default:

   IDL> print, REVERSE_N(indgen(5))
          4       3       2       1       0 
 
   Reverse second dimension (row) of a 2-d array:

   IDL> print, REVERSE_N(indgen(5,2), 2) 
          5       6       7       8       9 
          0       1       2       3       4 
 
   Reverse third dimension of a 3-d array:

   IDL> print, REVERSE_N(indgen(5,4,2), 3) 
         20      21      22      23      24 
         25      26      27      28      29 
         30      31      32      33      34 
         35      36      37      38      39 
    
          0       1       2       3       4 
          5       6       7       8       9 
         10      11      12      13      14 
         15      16      17      18      19 


 MODIFICATION HISTORY:
   Adapted from IDL's REVERSE function:

   Old.
   Apr, 1991, DMS, Added 3D reversing.
       Sept, 1992 Mark L. Rivers, added simple return for scaler argument
   Sept, 1994. Added default for 3D case.

Modified:    July, 1999 Gwyn Fireman restructured; handles up to 7d arrays.

 DISCLAIMER:  This routine has been modified from its original form as it was
              supplied by Research Systems, Inc (RSI).  As such, RSI is not responsible
              for any errors existing in this code.