[NEW] Return the difference between the given time and the time this calendar object is set to. If this calendar is set
before the given time, the returned value will be positive. If this calendar is set
after the given time, the returned value will be negative. The
field
parameter specifies the units of the return value. For example, if
fieldDifference(when, Calendar.MONTH)
returns 3, then this calendar is set to 3 months before
when
, and possibly some additional time less than one month.
As a side effect of this call, this calendar is advanced toward when
by the given amount. That is, calling this method has the side effect of calling add(field, n)
, where n
is the return value.
Usage: To use this method, call it first with the largest field of interest, then with progressively smaller fields. For example:
int y = cal.fieldDifference(when, Calendar.YEAR); int m = cal.fieldDifference(when, Calendar.MONTH); int d = cal.fieldDifference(when, Calendar.DATE);
computes the difference between
cal
and
when
in years, months, and days.
Note: fieldDifference()
is asymmetrical. That is, in the following code:
cal.setTime(date1); int m1 = cal.fieldDifference(date2, Calendar.MONTH); int d1 = cal.fieldDifference(date2, Calendar.DATE); cal.setTime(date2); int m2 = cal.fieldDifference(date1, Calendar.MONTH); int d2 = cal.fieldDifference(date1, Calendar.DATE);
one might expect that
m1 == -m2 && d1 == -d2
. However, this is not generally the case, because of irregularities in the underlying calendar system (e.g., the Gregorian calendar has a varying number of days per month).
@param when the date to compare this calendar's time to
@param field the field in which to compute the result
@return the difference, either positive or negative, betweenthis calendar's time and
when
, in terms of
field
.
@stable ICU 2.0