PRO unique_elements, data, unique, nunique, UNIQUE_SUBS = unique_subs

; Description: This module determines the set of unique elements in the input array "data" 
;              and returns this set as a vector of unique elements "unique" sorted into 
;              ascending order, along with the number of unique elements "nunique".
;              There is also the option to return the subscripts of the unique data values
;              in the input array "data" via the keyword UNIQUE_SUBS.
;
; Input Parameters:
;   
;   data - ARRAY (ANY TYPE) - An array of input data.
;
; Output Parameters:
;
;   unique - VECTOR (SAME TYPE AS "data") - A one-dimensional vector consisting of the set 
;                                           of unique elements in "data" sorted into 
;                                           ascending order.
;   nunique - LONG - The number of elements in the output parameter "unique".
;   
; Keywords:
;
;   If the keyword UNIQUE_SUBS is set to a named variable, then, on return, this variable 
;   will contain the subscripts of the unique data values in the input array "data". In
;   this case "unique" and "data[unique_subs]" are the same vectors.
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
;   05/08/2008 - Module rewritten for increased speed (dmb)
;   02/05/2008 - Module created (dmb)  

;Determine the number of elements in "data"

;If "data" is empty

;If "data" has one element

;If "data" has more than one element, then sort the data into ascending order

;Compare adjacent elements in the sorted data vector

;Find the positions in the sorted data vector where adjacent elements are different

;Construct the output vector of unique elements sorted in to ascending order