FUNCTION generate_subscripts_for_diagonal_in_2darr, xsize, ysize, xind_start, yind_start, diagonal_length, diagonal_direction, status, NO_PAR_CHECK = no_par_check
; Description: This function generates a one-dimensional vector of subscripts for a set of elements
; that form a diagonal in a two-dimensional array of size "xsize" by "ysize" elements.
; The set of elements in the diagonal is defined by the x index "xind_start" and the
; y index "yind_start" of the first element in the diagonal, the number of elements in
; the diagonal "diagonal_length", and the direction in which the diagonal runs
; "diagonal_direction", which may be any combination of increasing or decreasing x
; index, and increasing or decreasing y index (i.e. four possible directions).
;
; Input Parameters:
;
; xsize - INTEGER/LONG - The size of the two-dimensional array along the x-axis. This parameter
; must be positive.
; ysize - INTEGER/LONG - The size of the two-dimensional array along the y-axis. This parameter
; must be positive.
; xind_start - INTEGER/LONG - The x index of the first element in the diagonal. This parameter
; must lie in the range "0 <= xind_start < xsize".
; yind_start - INTEGER/LONG - The y index of the first element in the diagonal. This parameter
; must lie in the range "0 <= yind_start < ysize".
; diagonal_length - INTEGER/LONG - The number of elements in the diagonal. This parameter must
; be positive. Note that subscripts will only be generated for
; those elements of the diagonal that lie within the
; two-dimensional array.
; diagonal_direction - STRING - This parameter defines the direction in the two-dimensional array
; in which the diagonal runs from the first element in the diagonal.
; The acceptable values for this parameter are:
;
; ur - The diagonal runs upwards (increasing y index) and to the
; right (increasing x index) in the two-dimensional array from
; the first element in the diagonal.
; ul - The diagonal runs upwards (increasing y index) and to the
; left (decreasing x index) in the two-dimensional array from
; the first element in the diagonal.
; dr - The diagonal runs downwards (decreasing y index) and to the
; right (increasing x index) in the two-dimensional array from
; the first element in the diagonal.
; dl - The diagonal runs downwards (decreasing y index) and to the
; left (decreasing x index) in the two-dimensional array from
; the first element in the diagonal.
; status - ANY - A variable which will be used to contain the output status of the function on
; returning (see output parameters below).
;
; Output Parameters:
;
; status - INTEGER - If the function successfully generated the subscripts for the set of elements
; in the required diagonal, then "status" is returned with a value of "1",
; otherwise it is returned with a value of "0".
;
; Return Value:
;
; The return value is a one-dimensional VECTOR of numbers of LONG type representing the subscripts
; for the set of elements in the required diagonal of the two-dimensional array. All elements of
; the output vector are non-negative. If the function fails for any reason, then the return value
; is set to the single element vector "[-1L]".
;
; Keywords:
;
; If the keyword NO_PAR_CHECK is set (as "/NO_PAR_CHECK"), then the function will not perform
; parameter checking on the input parameters, reducing function overheads.
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 19/01/2012 - Module created (dmb).
;Set the default output parameter values
;Perform parameter checking if not instructed otherwise
;Check that "xsize" and "ysize" are positive numbers of the correct type
;Check that "xind_start" and "yind_start" are non-negative numbers of the correct type, and check
;that "xind_start" and "yind_start" are less than "xsize" and "ysize", respectively
;Check that "diagonal_length" is a positive number of the correct type
;Check that "diagonal_direction" is a scalar string with an acceptable value
;Determine the subscript in the two-dimensional array of the first element in the diagonal
;Set "status" to "1"
;If the diagonal runs upwards (increasing y index) and to the right (increasing x index) in the
;two-dimensional array from the first element in the diagonal
;Limit the set of elements in the diagonal to those that lie within the two-dimensional array
;Return the subscripts for the set of elements in the required diagonal of the two-dimensional
;array
;If the diagonal runs upwards (increasing y index) and to the left (decreasing x index) in the
;two-dimensional array from the first element in the diagonal
;Limit the set of elements in the diagonal to those that lie within the two-dimensional array
;Return the subscripts for the set of elements in the required diagonal of the two-dimensional
;array
;If the diagonal runs downwards (decreasing y index) and to the right (increasing x index) in
;the two-dimensional array from the first element in the diagonal
;Limit the set of elements in the diagonal to those that lie within the two-dimensional array
;Return the subscripts for the set of elements in the required diagonal of the two-dimensional
;array
;If the diagonal runs downwards (decreasing y index) and to the left (decreasing x index) in
;the two-dimensional array from the first element in the diagonal
;Limit the set of elements in the diagonal to those that lie within the two-dimensional array
;Return the subscripts for the set of elements in the required diagonal of the two-dimensional
;array