;----------------------------------------------------------------------------
;+
; 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.
;	July, 1999 Gwyn Fireman restructured; handles up to 7d arrays.
;-
;----------------------------------------------------------------------------

FUNCTION REVERSE_N, Array, Subscript

on_error, 2                     ; Return to caller if an error occurs

if (n_elements(subscript) eq 0) $ ; reverse 1st dimension by default
  then subscript = 1
	
s = size(array, /structure)
n_dim	= s.n_dimensions	; get number of dimensions of input array

if (n_dim gt 7) $		; test for invalid dimensions of input array
  then message, 'Input array must have < 7 dimensions'

				; test for invalid values of subscript
if ((subscript le 0) or (subscript gt n_dim))	$ ; impossible subscript
  and (n_dim ne 0)				$ ; don't worry about scalars
  then message, 'Specified subscript is invalid'

case n_dim of

  0:	return, array			; scalar

  1:	return, rotate(array, 2)	; vector

  2:	case subscript of		; 2-dimensional array
	  1:	return, rotate(array, 5)
	  2:	return, rotate(array, 7)
	endcase

  else:	begin				; 3- to 7-dimensional array

    R_array = array			; will hold reversed array
    n = s.dimensions[subscript-1]	; get dimension of subscript specified
    max_i = (n-1)/2			; max index = 1/2 subscript range

    case subscript of
      1: for i = 0, max_i do begin
        t0 = R_array[    i,*,*,*,*,*,*]	; extract ith subarray from "top"
        t1 = R_array[n-1-i,*,*,*,*,*,*]	; extract ith subarray from "bottom"
        R_array[n-i-1,0,0,0,0,0,0] = t0	; put ith "top" subarray in "bottom"
        R_array[    i,0,0,0,0,0,0] = t1	; put ith "bottom" subarray in "top"
		; center subarray not swapped for odd number of dimensions
      endfor
      2: for i = 0, max_i do begin
        t0 = R_array[*,    i,*,*,*,*,*]
        t1 = R_array[*,n-1-i,*,*,*,*,*]
        R_array[0,n-i-1,0,0,0,0,0] = t0
        R_array[0,    i,0,0,0,0,0] = t1
      endfor
      3: for i = 0, max_i do begin
        t0 = R_array[*,*,    i,*,*,*,*]
        t1 = R_array[*,*,n-i-1,*,*,*,*]
        R_array[0,0,n-i-1,0,0,0,0] = t0
        R_array[0,0,    i,0,0,0,0] = t1
      endfor
      4: for i = 0, max_i do begin
        t0 = R_array[*,*,*,    i,*,*,*]
        t1 = R_array[*,*,*,n-i-1,*,*,*]
        R_array[0,0,0,n-i-1,0,0,0] = t0
        R_array[0,0,0,    i,0,0,0] = t1
      endfor
      5: for i = 0, max_i do begin
        t0 = R_array[*,*,*,*,    i,*,*]
        t1 = R_array[*,*,*,*,n-i-1,*,*]
        R_array[0,0,0,0,n-i-1,0,0] = t0
        R_array[0,0,0,0,    i,0,0] = t1
      endfor
      6: for i = 0, max_i do begin
        t0 = R_array[*,*,*,*,*,    i,*]
        t1 = R_array[*,*,*,*,*,n-i-1,*]
        R_array[0,0,0,0,0,n-i-1,0] = t0
        R_array[0,0,0,0,0,    i,0] = t1
      endfor
      7: for i = 0, max_i do begin
        t0 = R_array[*,*,*,*,*,*,    i]
        t1 = R_array[*,*,*,*,*,*,n-i-1]
        R_array[0,0,0,0,0,0,n-i-1] = t0
        R_array[0,0,0,0,0,0,    i] = t1
      endfor
   endcase			; end of case for subscript to reverse over
   return, R_array
 endcase			; end of case for 7-dimensional arrays

endcase				; end of case for dimension of input array

end				; end of function REVERSE_N