Add date_compare() to Date API

Here's a version that requires the caller to convert the dates, if necessary.

This function kind of mimics version_compare().

/**
 * Compare two dates.
 *
 * Examples:
 *
 * @code
 * if (date_compare($date1, $date2) > 0) {
 *   // $date1 is greater than $date2.
 * }
 * if (date_compare($date1, $date2) < 0) {
 *   // $date1 is lower than $date2.
 * }
 * if (date_compare($date1, $date2) == 0) {
 *   // $date1 is equal to $date2.
 * }
 * @endcode
 *
 * @param mixed $date1
 *   the starting date
 * @param mixed $date2
 *   the ending date
 * @return
 *   -1 if the first date is lower than the second, 0 if they are equal,
 *   and 1 if the second is lower.
 */
function date_compare($date1, $date2) {
  $diff = date_format($date1, 'U') - date_format($date2, 'U');
  return ($diff > 0 ? 1 : ($diff < 0 ? -1 : 0));
}

I'm using this function to compare dates to grant/deny access to nodes based on workflow rules defined by custom code. I hope this function can be useful to other as it is a bit more intuitive than doing the inner logic in it explicitly everywhere you need this kind of comparisons.

@Karen: If you like the idea, then please let me know if you want it in patch form. I thought it could be placed just above date_difference() code. Also, the README would have to be updated. Not sure if there would be more stuff to update.

@arlinsandbulte: it makes your code more readable, and it also helps to remind how to perform such operations, which is easier with this function because it mimics version_compare(). But well, this is just a personal point of view. YMMV.

Good point in adding format conversion, though maybe it could be done only when the $type argument is not DATE_OBJECT, for performance reasons.

Thanks for taking into consideration! :)