PRO define_equal_bins, value1, value2, nbins, bin_limits, bin_size, status
; Description: This module defines the bin limits "bin_limits" for "nbins" bins of equal size between
; the values "value1" and "value2".
;
; Input Parameters:
;
; value1 - INTEGER/LONG/FLOAT/DOUBLE - The value of the first limit for the range for which bins are
; to be defined. This limit is usually the lower limit for the
; range.
; value2 - INTEGER/LONG/FLOAT/DOUBLE - The value of the second limit for the range for which bins are
; to be defined. This limit is usually the upper limit for the
; range. The value of "value2" must not be equal to the value of
; "value1".
; nbins - INTEGER/LONG - The number of bins to be defined in the range between "value1" and "value2".
; This parameter must be positive.
;
; Output Parameters:
;
; bin_limits - DOUBLE VECTOR - A one-dimensional vector of size "nbins + 1" with consecutive pairs
; of values representing the lower and upper limits of each bin. For
; instance, the ith bin, with i running from "0" to "nbins - 1", will
; correspond to the range of values between bin_limits[i] and
; bin_limits[i+1], where bin_limits[i] < bin_limits[i+1], regardless
; of whether "value1" is greater than or less than "value2".
; bin_size - DOUBLE - The size of each bin.
; status - INTEGER - If the module successfully defined a set of bin limits, then "status" is
; returned with a value of "1", otherwise it is returned with a value of "0".
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 09/12/2009 - Module created (dmb).
;Set the default output parameter values
;Check that "value1" and "value2" are numbers of the correct type, and check that they have
;sensible values
;Check that "nbins" is a positive number of the correct type
;Create the vector of values defining the bin limits
;Set "status" to "1"