com.miginfocom.util.dates
Class DateUtil

java.lang.Object
  extended by com.miginfocom.util.dates.DateUtil

public class DateUtil
extends java.lang.Object

A utility class with static methods for handling dates and calendars.


Field Summary
static long DAY_MILLIS
           
static long HOUR_MILLIS
           
static java.text.SimpleDateFormat ICAL_DF
           
static long MINUTE_MILLIS
           
static long SECOND_MILLIS
           
static long WEEK_MILLIS
           
 
Constructor Summary
DateUtil()
           
 
Method Summary
static java.util.Calendar addDSTSafe(java.util.Calendar cal, int field, int amount)
          Calls Calendar.add(int, int) on cal and then compensating for jumps over a Daylight Savings Time boundary, if present.
static long addMillisDSTSafe(long millis, java.util.TimeZone timeZone, long amount)
          Adds a number of milliseconds to cal, compensating for jumps over a Daylight Savings Time boundary, if present.
static int convertCalFieldToRangeType(int field)
          Convert Calendar's field type to DateRangeI's range type.
E.g.
static int convertRangeTypeToCalField(int rangeType)
          Converts DateRangeI.RANGE_TYPE_xxx type to the corresponding Calandar type.
static int convertToDayIndex(int dayOfWeek, java.util.Calendar cal)
          Converts an Calendar.DAY_OF_WEEK to an index for 0 to 6 compensating for getFirstDayOfWeek().
static int convertToDayOfWeek(int zeroDay, java.util.Calendar refCal)
          Converts an 0-based day to correct Calendar.DAY_OF_WEEK compensating for getFirstDayOfWeek().
static void copyTimeOfDay(java.util.Calendar src, java.util.Calendar dst)
          Copies time of day from src to dst.
static java.util.Calendar createCalendar(long millis, java.util.TimeZone timeZone, java.util.Locale locale)
          Creates a calendar with the set time.
static java.util.Calendar createCalendar(java.util.TimeZone timeZone, java.util.Locale locale)
          Creates a calendar with the current time set.
static java.lang.String[] getAlternativesForField(int field, java.util.Calendar cal, java.text.DateFormat dateFormat, java.lang.Integer count)
          Returns a list of alternante/near by choices, suitable for a popup menu or a combo box.
static int getDaysSpanApprox(java.util.Date date1, java.util.Date date2)
          Returns the approximate number of days from 'date1' to and including 'date2'.
static long getDSTDiff(java.util.Date start, java.util.TimeZone startZone, java.util.Date end, java.util.TimeZone endZone)
          Return the daylight savings time difference.
static java.lang.String getDurationString(java.util.Calendar start, java.util.Calendar end, boolean endIsExcluding, java.lang.String format)
          Returns a string that describes a duration, normally in a human readable format.
The formatting is not unlike that of the SimpleDateFormat class, though it is a bit more restrictive but you can also have different sub strings for if a duration time unit (such as the number of hours) is 1 (one), or not 1.
All charachters within ' (apostrophes) are returned as is, just as with SimpleDateFormat.
static java.lang.String getDurationString(DateRangeI dateRange, java.lang.String format)
          Returns a string that describes a duration, normally in a human readable format.
The formatting is not unlike that of the SimpleDateFormat class, though it is a bit more restrictive but you can also have different sub strings for if a duration time unit (such as the number of hours) is 1 (one), or not 1.
All charachters within ' (apostrophes) are returned as is, just as with SimpleDateFormat.
static long getFieldModulo(java.util.Calendar cal, int boundaryType)
          Returns a calendar rounded to a boundary (earliear) and then returns the .getTimeInMillis() on that date.
static int getLastDayOfWeek(java.util.Calendar cal)
          Returns the last day of week according to the locale of 'cal'.
static java.lang.Long getLastRecurrenceMillis(Recurrence rec, DateRangeI baseRange, java.util.Calendar max)
          Returns the end date (millisecond inclusive) of the last recurrence or null if the recurrence will continue forever.
static java.lang.String getLocalDateTimeString(java.util.Calendar cal)
          Return a string for printing in the local time zone
static java.util.Calendar getMiddleDate(java.util.Date date1, java.util.Date date2, java.util.Locale locale)
          Deprecated. Do not use.
static long getMillisSpannedDST(long start, java.util.TimeZone startZone, long end, java.util.TimeZone endZone)
          Returns the number of milliseconds between two points in time.
static int getSpanCount(java.util.Calendar start, java.util.Calendar end, int rangeType, boolean dstSafe)
          Returns the number of seconds, minutes, hours, days, weeks, months or years betwen two dates, inclusive.
static int getSpanCountIter(java.util.Calendar start, java.util.Calendar end, int rangeType)
          Returns the number of seconds, minutes, hours, days, weeks, months or years betwen two dates, inclusive.
static int getWeekDayOccurence(java.util.Calendar cal, int field, boolean fromStart)
          Return which week day occurence in a year or month cal is representing.
static int getWeeksOfYear(int year, java.util.Locale locale)
          Returns the maximum number of week for 'year' (normally 52 or 53)
static int getYear_WeekBased(java.util.Calendar cal)
          Returns the year of 'cal' but in the context of a week.
static boolean isContaining(java.util.Calendar outerStart, java.util.Calendar outerEnd, java.util.Calendar innerStart, java.util.Calendar innerEnd)
          Checks if a date range is compleately inside or equal to another range (end dates should be last millisecond of range)
static boolean isContaining(java.util.Date outerStart, java.util.Date outerEnd, java.util.Date innerStart, java.util.Date innerEnd)
          Checks if a date range is compleately inside or equal to another range.
static boolean isContaining(long outerStart, long outerEnd, long innerStart, long innerEnd)
          Checks if a date range is compleately inside or equal to another range.
static boolean isInSame(java.util.Calendar cal1, java.util.Calendar cal2, int rangeType)
          Returns if cal1 and cal2 is in the same range type.
static boolean isOnBoundaryStart(java.util.Calendar cal, int rangeType)
          Returns if a calendar date+time is on a boundary start.
static boolean isOverlapping(java.util.Calendar start1, java.util.Calendar end1, java.util.Calendar start2, java.util.Calendar end2)
          Checks if two date ranges overlap (or touches) eachother.
static boolean isOverlapping(java.util.Date start1, java.util.Date end1, java.util.Date start2, java.util.Date end2)
          Checks if two date ranges overlap (or touches) eachother.
static boolean isOverlapping(long start1, long end1, long start2, long end2)
          Checks if two date ranges overlap (or touches) eachother.
static java.util.Date parseDateTime(java.lang.String dateTime)
          Parse the date time and return a calendar.
static java.util.Calendar setFieldCorrect(java.util.Calendar cal, int field, int value)
          Help to set a value on a Calendar.
static java.util.Calendar setToBoundary(java.util.Calendar cal, int boundaryType, boolean toEarlier)
          Sets the date to the first or last millisecond of a boundary depending on 'toEarlier'.
static java.util.Calendar setToEndBoundary(java.util.Calendar cal, int boundaryType)
          Sets the date to the first or last millisecond of a boundary depending on 'toEarlier'.
static java.util.Calendar setToStartBoundary(java.util.Calendar cal, int boundaryType)
          Sets the date to the first millisecond of a boundary.
static java.util.Calendar setYearWeekDay_WeekBased(java.util.Calendar cal, int year, int week, int zeroDay)
          Convenience method to change the date (time of day is untouched) when the result should be WEEK-BASED.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SECOND_MILLIS

public static final long SECOND_MILLIS
See Also:
Constant Field Values

MINUTE_MILLIS

public static final long MINUTE_MILLIS
See Also:
Constant Field Values

HOUR_MILLIS

public static final long HOUR_MILLIS
See Also:
Constant Field Values

DAY_MILLIS

public static final long DAY_MILLIS
See Also:
Constant Field Values

WEEK_MILLIS

public static final long WEEK_MILLIS
See Also:
Constant Field Values

ICAL_DF

public static final java.text.SimpleDateFormat ICAL_DF
Constructor Detail

DateUtil

public DateUtil()
Method Detail

createCalendar

public static java.util.Calendar createCalendar(java.util.TimeZone timeZone,
                                                java.util.Locale locale)
Creates a calendar with the current time set.

Parameters:
timeZone - The time zone. If null the default will be used.
locale - The locale. If null the default will be used.
Returns:
The newly created Calendar

parseDateTime

public static java.util.Date parseDateTime(java.lang.String dateTime)
Parse the date time and return a calendar.

Parameters:
dateTime - The date time on the form "yyyyMMdd'T'HHmmssSSS".
Returns:
The date and time of the string. null if unparsable.

getLastRecurrenceMillis

public static java.lang.Long getLastRecurrenceMillis(Recurrence rec,
                                                     DateRangeI baseRange,
                                                     java.util.Calendar max)
Returns the end date (millisecond inclusive) of the last recurrence or null if the recurrence will continue forever.

Parameters:
rec - The recurrence to check. Not null.
baseRange - The range on which to base the recurrence on ranges. Called DTSTART/DTEND in RFC 2445 (iCalendar)
max - If not null the evaluation will never go after this date and this will thus be the latest date possible to return. Since the recurrences have to be evaluated in all to return the last recurrence this can be a safetynet to not make the evaluation take too much time.
Returns:
The end date (millisecond inclusive) of the last recurrence or null if the recurrence will continue forever.

createCalendar

public static java.util.Calendar createCalendar(long millis,
                                                java.util.TimeZone timeZone,
                                                java.util.Locale locale)
Creates a calendar with the set time.

Parameters:
millis - The time to set. If Long.MIN_VALUE it is NOT set.
timeZone - The time zone. If null the default will be used.
locale - The locale. If null the default will be used.
Returns:
The newly created Calendar

convertRangeTypeToCalField

public static final int convertRangeTypeToCalField(int rangeType)
Converts DateRangeI.RANGE_TYPE_xxx type to the corresponding Calandar type. Both DateRangeI.RANGE_TYPE_YEAR_MONTHS and DateRangeI.RANGE_TYPE_YEAR_MONTHS will be converted to Calandar.YEAR so this type might require special treatment.
If illegal date range type a ArrayIndexOutOfBoundsException will be thrown.

Parameters:
rangeType - The range type. DateRangeI.RANGE_TYPE_xxx. DateRangeI.RANGE_TYPE_CUSTOM will throw exception.
Returns:
The corresponding type in Calandar class. eg Calandar.WEEK_OF_YEAR.

convertCalFieldToRangeType

public static int convertCalFieldToRangeType(int field)
Convert Calendar's field type to DateRangeI's range type.
E.g. Calendar.DAY_OF_YEAR, Calendar.DAY_OF_MONTH, Calendar.DAY_OF_WEEK, Calendar.DAY_OF_WEEK_IN_MONTH all get converted to DateRangeI.RANGE_TYPE_DAY.
If field is unsupported (illogical) an ArrayIndexOutOfBoundsException will be thrown.

Parameters:
field - The field to convert. E.g. Calendar.DAY_OF_YEAR
Returns:
E.g. DateRangeI.RANGE_TYPE_DAY

setToStartBoundary

public static java.util.Calendar setToStartBoundary(java.util.Calendar cal,
                                                    int boundaryType)
Sets the date to the first millisecond of a boundary.

Parameters:
cal - The date to be changed. Not null.
boundaryType - The boundary the 'cal' will be set to. It can be one of: DateRangeI.RANGE_TYPE_SECOND Set the date/time to a second boundary
DateRangeI.RANGE_TYPE_MINUTE Set the date/time to a minute boundary
DateRangeI.RANGE_TYPE_HOUR Set the date/time to a hour boundary
DateRangeI.RANGE_TYPE_DAY Set the date/time to a days boundary
DateRangeI.RANGE_TYPE_WEEK Set the date/time to a week boundary
DateRangeI.RANGE_TYPE_MONTH Set the date/time to a month boundary
DateRangeI.RANGE_TYPE_YEAR_MONTHS Set the date/time to a year boundary. Jan 1 to Dec 31.
DateRangeI.RANGE_TYPE_YEAR_WEEKS Set the date/time to a year boundary. Week 01 to week 52/53
DateRangeI.RANGE_TYPE_CUSTOM same as DateRangeI.RANGE_TYPE_DAY
Returns:
'cal' changed to the appropriate date.

setToEndBoundary

public static java.util.Calendar setToEndBoundary(java.util.Calendar cal,
                                                  int boundaryType)
Sets the date to the first or last millisecond of a boundary depending on 'toEarlier'.

Parameters:
cal - The date to be changed. Not null.
boundaryType - The boundary the 'cal' will be set to. It can be one of: DateRangeI.RANGE_TYPE_SECOND Set the date/time to a second boundary
DateRangeI.RANGE_TYPE_MINUTE Set the date/time to a minute boundary
DateRangeI.RANGE_TYPE_HOUR Set the date/time to a hour boundary
DateRangeI.RANGE_TYPE_DAY Set the date/time to a days boundary
DateRangeI.RANGE_TYPE_WEEK Set the date/time to a week boundary
DateRangeI.RANGE_TYPE_MONTH Set the date/time to a month boundary
DateRangeI.RANGE_TYPE_YEAR_MONTHS Set the date/time to a year boundary. Jan 1 to Dec 31.
DateRangeI.RANGE_TYPE_YEAR_WEEKS Set the date/time to a year boundary. Week 01 to week 52/53
DateRangeI.RANGE_TYPE_CUSTOM same as DateRangeI.RANGE_TYPE_DAY
Returns:
'cal' changed to the appropriate date.

setToBoundary

public static java.util.Calendar setToBoundary(java.util.Calendar cal,
                                               int boundaryType,
                                               boolean toEarlier)
Sets the date to the first or last millisecond of a boundary depending on 'toEarlier'.

Parameters:
cal - The date to be changed. Not null.
boundaryType - The boundary the 'cal' will be set to. It can be one of: DateRangeI.RANGE_TYPE_SECOND Set the date/time to a second boundary
DateRangeI.RANGE_TYPE_MINUTE Set the date/time to a minute boundary
DateRangeI.RANGE_TYPE_HOUR Set the date/time to a hour boundary
DateRangeI.RANGE_TYPE_DAY Set the date/time to a days boundary
DateRangeI.RANGE_TYPE_WEEK Set the date/time to a week boundary
DateRangeI.RANGE_TYPE_MONTH Set the date/time to a month boundary
DateRangeI.RANGE_TYPE_YEAR_MONTHS Set the date/time to a year boundary. Jan 1 to Dec 31.
DateRangeI.RANGE_TYPE_YEAR_WEEKS Set the date/time to a year boundary. Week 01 to week 52/53
DateRangeI.RANGE_TYPE_CUSTOM same as DateRangeI.RANGE_TYPE_DAY
toEarlier - true means the "earlier" or lower side of the field boundary.
Returns:
'cal' changed to the appropriate date.

isOnBoundaryStart

public static boolean isOnBoundaryStart(java.util.Calendar cal,
                                        int rangeType)
Returns if a calendar date+time is on a boundary start. E.g. first millisecond of a month.

Parameters:
cal - The calendar containing the date+time.
rangeType - The range type to check for. E.g. DateRangeI.RANGE_TYPE_MONTH.
Returns:
If a calendar date+time is on a boundary start.

copyTimeOfDay

public static final void copyTimeOfDay(java.util.Calendar src,
                                       java.util.Calendar dst)
Copies time of day from src to dst.

Parameters:
src - The source calendar, won't be changed
dst - The destination calendar.

getFieldModulo

public static final long getFieldModulo(java.util.Calendar cal,
                                        int boundaryType)
Returns a calendar rounded to a boundary (earliear) and then returns the .getTimeInMillis() on that date. Can be used as a key in a HashMap for instance. Same as writing (cal % field)

Parameters:
cal - The calendar, not changed.
boundaryType - The boundary the 'cal' will be set (modulo'ed) to. It can be one of: DateRangeI.RANGE_TYPE_SECOND, DateRangeI.RANGE_TYPE_MINUTE, DateRangeI.RANGE_TYPE_HOUR, DateRangeI.RANGE_TYPE_DAY, DateRangeI.RANGE_TYPE_WEEK, DateRangeI.RANGE_TYPE_MONTH, DateRangeI.RANGE_TYPE_YEAR_MONTHS or DateRangeI.RANGE_TYPE_YEAR_WEEKS
Returns:
a calendar rounded to a boundary (earliear) and then returns the .getTimeInMillis() on that date.

getDurationString

public static java.lang.String getDurationString(java.util.Calendar start,
                                                 java.util.Calendar end,
                                                 boolean endIsExcluding,
                                                 java.lang.String format)
Returns a string that describes a duration, normally in a human readable format.
The formatting is not unlike that of the SimpleDateFormat class, though it is a bit more restrictive but you can also have different sub strings for if a duration time unit (such as the number of hours) is 1 (one), or not 1.
All charachters within ' (apostrophes) are returned as is, just as with SimpleDateFormat. Spaces are the only non-valid formatting character allowed outside these apostrophes and they will end up in the retuned string.
Formatting characters are case sensitive and they are:

y - Years
M - Months
w - Weeks
d - Days
H - Hours
m - Minutes
s - Seconds
S - Milliseconds
? - Hides the value of the preceding value type if it is zero. E.g. "yy?" will only show the year if it is > 0.

If the same formatting character are repeated the total count of them will be the least amount of figures returned for that value. For instanse:
"HH" will return "01" or "123" while
"H" will return "1" or "123"
for a 1 or 123 hours duration, respectively.

The larger formatting characters are evaluated first and the duration they represent are then substracted from the remaining duration. For instance a duration of 61 minutes will return:
"1 hours and 1 minutes" for "H'hours and 'm' minutes"
but
"63 minutes" for "'m' minutes

Within a text surrounded by apostrophes a block formatted "(*:*:*)" may exist. This pattern will be replaced by the text representing first star if the last evaluated time value was 0, the second star if that last value was 1 and the third start for any other value. Note that the stars can be of any length, including zero. They can not, however, contain the characters "'", "(", ")" or ":". Not even with a preceding "\" (backslash).
For instance, for the format string:
"m' minute (a:b:c)'"
would return:
"0 minut a"
for a zero minute duration and
"1 minut b"
for a one minute duration and
"2 minute c"
for a two minute duration.

Normally a format string like "m' minute(s::s)'" or "m?'(: minute: minutes)'" can be used for having correct ending.
Any formatting error will throw a IllegalArgumentException.

Parameters:
start - The start of the duration. Time zone will be used.
end - The end of the duration. Time zone will NOT be used.
endIsExcluding - Set to true if the end date is 'excluding' the last millisecond, normally meaning that the milliseconds are are an even number (0).
format - A formatting string. E.g. "y?'(: year, : years, )'M' month(s::s), 'dd' day(s::s), 'HH' hour(s::s), 'mm' minute(s::s), 'ss' second(s::s), 'S' millisecond(s::s)'".
Returns:
The resulting string. Never null.

getDurationString

public static java.lang.String getDurationString(DateRangeI dateRange,
                                                 java.lang.String format)
Returns a string that describes a duration, normally in a human readable format.
The formatting is not unlike that of the SimpleDateFormat class, though it is a bit more restrictive but you can also have different sub strings for if a duration time unit (such as the number of hours) is 1 (one), or not 1.
All charachters within ' (apostrophes) are returned as is, just as with SimpleDateFormat. Spaces are the only non-valid formatting character allowed outside these apostrophes and they will end up in the retuned string.
Formatting characters are case sensitive and they are:

y - Years
M - Months
w - Weeks
d - Days
H - Hours
m - Minutes
s - Seconds
S - Milliseconds
? - Hides the value of the preceding value type if it is zero. E.g. "yy?" will only show the year if it is > 0.

If the same formatting character are repeated the total count of them will be the least amount of figures returned for that value. For instanse:
"HH" will return "01" or "123" while
"H" will return "1" or "123"
for a 1 or 123 hours duration, respectively.

The larger formatting characters are evaluated first and the duration they represent are then substracted from the remaining duration. For instance a duration of 61 minutes will return:
"1 hours and 1 minutes" for "H'hours and 'm' minutes"
but
"63 minutes" for "'m' minutes

Within a text surrounded by apostrophes a block formatted "(*:*:*)" may exist. This pattern will be replaced by the text representing first star if the last evaluated time value was 0, the second star if that last value was 1 and the third start for any other value. Note that the stars can be of any length, including zero. They can not, however, contain the characters "'", "(", ")" or ":". Not even with a preceding "\" (backslash).
For instance, for the format string:
"m' minute (a:b:c)'"
would return:
"0 minute a"
for a zero minute duration and
"1 minute b"
for a one minute duration and
"2 minute c"
for a two minute duration.

Normally a format string like "m' minute(s::s)'" or "m?'(: minute: minutes)'" can be used for correct endings.
Any formatting error will throw a IllegalArgumentException.

Parameters:
dateRange - The date range to return the duration string for.
format - A formatting string. E.g. "y?'(: year, : years, )'M' month(s::s), 'dd' day(s::s), 'HH' hour(s::s), 'mm' minute(s::s), 'ss' second(s::s), 'S' millisecond(s::s)'".
Returns:
The resulting string. Never null.

getLocalDateTimeString

public static java.lang.String getLocalDateTimeString(java.util.Calendar cal)
Return a string for printing in the local time zone

Returns:
A string for printing in the local time zone

getWeeksOfYear

public static final int getWeeksOfYear(int year,
                                       java.util.Locale locale)
Returns the maximum number of week for 'year' (normally 52 or 53)

Parameters:
year - The year in question
locale - The locale, if null the default is used.
Returns:
The maximum number of week for 'year' (normally 52 or 53)

setYearWeekDay_WeekBased

public static java.util.Calendar setYearWeekDay_WeekBased(java.util.Calendar cal,
                                                          int year,
                                                          int week,
                                                          int zeroDay)
Convenience method to change the date (time of day is untouched) when the result should be WEEK-BASED. This mean that the year of 'cal' actually don't have to be 'year'. setYearWeekDay_WeekBased(2003,1,0) is 2002-12-30 in europe and 2002-12-29 in the US for instance. Week 01 starts in 2002, that's the reason. This method is week-based.

Parameters:
cal - The calendar object to be changed. Not null.
year - The year, week based! setYearWeekDay_WeekBased(2002, 1, 0) -> 2001-12-30
week - The week, same as Calendar.WEEK_OF_YEAR.
zeroDay - The day of week (0-6). NOT THE SAME AS Calendar.DAY_OF_WEEK!!! Here 0 == first day of week (SUNDAY OR MONDAY normally) and 6 == last day of week (SATURDAY or SUNDAY normally).
Returns:
The object 'cal' that has been changed.
See Also:
convertToDayOfWeek(int, java.util.Calendar)

convertToDayOfWeek

public static final int convertToDayOfWeek(int zeroDay,
                                           java.util.Calendar refCal)
Converts an 0-based day to correct Calendar.DAY_OF_WEEK compensating for getFirstDayOfWeek(). Here 0 == first day of week (SUNDAY OR MONDAY normally) and 6 == last day of week (SATURDAY or SUNDAY normally).

Parameters:
zeroDay - 0 to 6 where 0 is the first day of week in the current locale.
refCal - The refernce calendar to get the first day of week from. If null, a default Locale will be used.
Returns:
The day of week that Calendar.DAY_OF_WEEK specifiec. For example Calendar.MONDAY for 0 in europe or Calendar.SUNDAY for 0 in US. The value is 1..7 with the current Calendar class (2003-01-04)

convertToDayIndex

public static final int convertToDayIndex(int dayOfWeek,
                                          java.util.Calendar cal)
Converts an Calendar.DAY_OF_WEEK to an index for 0 to 6 compensating for getFirstDayOfWeek(). SUNDAY is 0 in US but 6 in Europe and MONDAY is 1 in US but 0 in europe.

Parameters:
dayOfWeek - The day. Eg. Calendar.MONDAY
cal - The Calendar to use for the convertion. Set to the correct Locale.
Returns:
A day index accoring to a full week. 0 to 6.

getDaysSpanApprox

public static final int getDaysSpanApprox(java.util.Date date1,
                                          java.util.Date date2)
Returns the approximate number of days from 'date1' to and including 'date2'. Could be off one day due to DST. Just for quick approximations. Same date equals 1. always > 0

Parameters:
date1 - AtStart date
date2 - AtEnd date
Returns:
The approximate number of days from 'date1' to and including 'date2'. Could be off one day. Just for quick approximations. Same date equals 1. always > 0

isInSame

public static final boolean isInSame(java.util.Calendar cal1,
                                     java.util.Calendar cal2,
                                     int rangeType)
Returns if cal1 and cal2 is in the same range type. (e.g. DateRangeI.RANGE_TYPE_DAY)

Parameters:
rangeType - The range type. DateRangeI.RANGE_TYPE_xxx. Not RANGE_TYPE_CUSTOM.
Returns:
If cal1 and cal2 is in the same range type.

getLastDayOfWeek

public static final int getLastDayOfWeek(java.util.Calendar cal)
Returns the last day of week according to the locale of 'cal'.

Parameters:
cal - The calendar used for the calulation. Remains unchanged.
Returns:
The last day of week according to the locale of 'cal'. Eg. Calendar.MONDAY or Calendar.SUNDAY

getYear_WeekBased

public static final int getYear_WeekBased(java.util.Calendar cal)
Returns the year of 'cal' but in the context of a week. 2002-12-31 returns 2003 for instance since it is week 01. This is not supported in Calendar for Java 1.4.1_01 but it's RFE:ed (BUG-ID 4267450)

Parameters:
cal - The date to return the year of, week based
Returns:
The year of 'cal' but in the context of a week. 2002-12-31 returns 2003 for instance since it is week 01.

getMiddleDate

public static final java.util.Calendar getMiddleDate(java.util.Date date1,
                                                     java.util.Date date2,
                                                     java.util.Locale locale)
Deprecated. Do not use.

Calulates the time in the middle of 'date1' and 'date2'. No specific order on dates.

Parameters:
date1 - a date
date2 - a date
locale - The locale to use or null for the default
Returns:
The time in the middle of 'date1' and 'date2'.

isOverlapping

public static final boolean isOverlapping(java.util.Calendar start1,
                                          java.util.Calendar end1,
                                          java.util.Calendar start2,
                                          java.util.Calendar end2)
Checks if two date ranges overlap (or touches) eachother. Inclusive (end dates should be last millisecond of range)

Parameters:
start1 - AtStart date 1
end1 - AtEnd date 1
start2 - AtStart date 2
end2 - AtEnd date 2
Returns:
If two date ranges overlap (or touches) eachother. Inclusive (end dates should be last millisecond of range)

isOverlapping

public static final boolean isOverlapping(java.util.Date start1,
                                          java.util.Date end1,
                                          java.util.Date start2,
                                          java.util.Date end2)
Checks if two date ranges overlap (or touches) eachother. Inclusive (end dates should be last millisecond of range)

Parameters:
start1 - AtStart date 1
end1 - AtEnd date 1
start2 - AtStart date 2
end2 - AtEnd date 2
Returns:
If two date ranges overlap (or touches) eachother. Inclusive (end dates should be last millisecond of range)

isOverlapping

public static final boolean isOverlapping(long start1,
                                          long end1,
                                          long start2,
                                          long end2)
Checks if two date ranges overlap (or touches) eachother. Inclusive (end dates should be last millisecond of range)

Parameters:
start1 - AtStart date 1
end1 - AtEnd date 1. Inclusive (should be last millisecond of range)
start2 - AtStart date 2
end2 - AtEnd date 2. Inclusive (should be last millisecond of range)
Returns:
If two date ranges overlap (or touches) eachother. Inclusive (end dates should be last millisecond of range)

isContaining

public static final boolean isContaining(java.util.Calendar outerStart,
                                         java.util.Calendar outerEnd,
                                         java.util.Calendar innerStart,
                                         java.util.Calendar innerEnd)
Checks if a date range is compleately inside or equal to another range (end dates should be last millisecond of range)

Parameters:
outerStart - The surrounding start date
outerEnd - The surrounding end date. Inclusive (should be last millisecond of range)
innerStart - The possibly inside startdate
innerEnd - The possibly inside enddate. Inclusive (should be last millisecond of range)
Returns:
If a date range is compleately inside or equal to another range.

isContaining

public static final boolean isContaining(java.util.Date outerStart,
                                         java.util.Date outerEnd,
                                         java.util.Date innerStart,
                                         java.util.Date innerEnd)
Checks if a date range is compleately inside or equal to another range.

Parameters:
outerStart - The surrounding start date
outerEnd - The surrounding end date. Inclusive (should be last millisecond of range)
innerStart - The possibly inside startdate
innerEnd - The possibly inside enddate. Inclusive (should be last millisecond of range)
Returns:
If a date range is compleately inside or equal to another range.

isContaining

public static final boolean isContaining(long outerStart,
                                         long outerEnd,
                                         long innerStart,
                                         long innerEnd)
Checks if a date range is compleately inside or equal to another range.

Parameters:
outerStart - The surrounding start date in milliseconds
outerEnd - The surrounding end date in milliseconds. Inclusive (should be last millisecond of range)
innerStart - The possibly inside startdate in milliseconds
innerEnd - The possibly inside enddate in milliseconds. Inclusive (should be last millisecond of range)
Returns:
If a date range is compleately inside or equal to another range.

getSpanCountIter

public static final int getSpanCountIter(java.util.Calendar start,
                                         java.util.Calendar end,
                                         int rangeType)
Returns the number of seconds, minutes, hours, days, weeks, months or years betwen two dates, inclusive. For instance 2002-12-31 to 2003-01-01 spans two years.
The method ITERATES the result (anti-bug policy).
If range isn't sorted this method will return a negative number.

Parameters:
start - AtStart date/time
end - AtStart date/time
rangeType - One of: DateRangeI.RANGE_TYPE_SECOND Counts the seconds
DateRangeI.RANGE_TYPE_MINUTE Counts the minutes
DateRangeI.RANGE_TYPE_HOUR Counts the hours
DateRangeI.RANGE_TYPE_DAY Counts the days
DateRangeI.RANGE_TYPE_WEEK Counts the weeks
DateRangeI.RANGE_TYPE_MONTH Counts the months
DateRangeI.RANGE_TYPE_YEAR_MONTHS Counts the years, month based. jan 1 to dec 31
DateRangeI.RANGE_TYPE_YEAR_WEEKS Counts the years, week based. week 01 to week 52/53
Returns:
The number of days, weeks, months or years betwen two dates, inclusive. Always != 0.
See Also:
getSpanCount(java.util.Calendar, java.util.Calendar, int, boolean)

getSpanCount

public static final int getSpanCount(java.util.Calendar start,
                                     java.util.Calendar end,
                                     int rangeType,
                                     boolean dstSafe)
Returns the number of seconds, minutes, hours, days, weeks, months or years betwen two dates, inclusive. For instance 2002-12-31 to 2003-01-01 spans two years

RANGE_TYPE_MONTH, RANGE_TYPE_YEAR_MONTHS and RANGE_TYPE_YEAR_WEEKS are passed in to getSpanCountIter(...) since their length is variable and has to be iterated.
If start > end the value will be negative but have the same absolute value as if they were reversed.

The returned value will never be 0.

Parameters:
start - AtStart date/time. Not null.
end - AtStart date/time. Not null.
rangeType - One of: DateRangeI.RANGE_TYPE_SECOND Counts the seconds
DateRangeI.RANGE_TYPE_MINUTE Counts the minutes
DateRangeI.RANGE_TYPE_HOUR Counts the hours
DateRangeI.RANGE_TYPE_DAY Counts the days
DateRangeI.RANGE_TYPE_WEEK Counts the weeks
DateRangeI.RANGE_TYPE_MONTH Counts the months (iterative algorithm)
DateRangeI.RANGE_TYPE_YEAR_MONTHS Counts the years, month based. jan 1 to dec 31 (iterative algorithm)
DateRangeI.RANGE_TYPE_YEAR_WEEKS Counts the years, week based. week 01 to week 52/53 (iterative algorithm)
dstSafe - For instance a day can span 23, 24 or 25 hours depending on if it's the Daylight saving day. With this set to true the returned value will be compensated to return 24 for all days. This is also valid for minutes and seconds. Note that if true adding the returned amount to start may not end up on end but on one earlier or later.
Returns:
The number of seconds, minutes, hours, days, weeks, months or years betwen two dates. Inclusive, which means never 0.
See Also:
getSpanCountIter(java.util.Calendar, java.util.Calendar, int)

getMillisSpannedDST

public static long getMillisSpannedDST(long start,
                                       java.util.TimeZone startZone,
                                       long end,
                                       java.util.TimeZone endZone)
Returns the number of milliseconds between two points in time. Compansates for daylight savings so that for instance time 00.00 to 00.00 the next day always returns 24 * 60 * 60 * 1000 millisecond even if that day has a changed in DST. If this is an undesired behaviour just use end.getTimeInMillis() - start.getTimeInMillis() instead.

if end < start a negative value will be returned.

if start == end zero is returned. Compare this to DateRangeI.getMillisSpanned(boolean, boolean) which always add 1 to end since is there end date is considered inclusive.

Time zones are only used to componsate for DST, NOT for the calculation!

Parameters:
start - The start date/time
startZone - The time zone for the start time. If null default is used.
end - The end date/time
endZone - The time zone for the end time. If null default is used.
Returns:
Returns the number of milliseconds between two points in time, compensated for DST differences.

getDSTDiff

public static long getDSTDiff(java.util.Date start,
                              java.util.TimeZone startZone,
                              java.util.Date end,
                              java.util.TimeZone endZone)
Return the daylight savings time difference. (start - end).

Parameters:
start - Start time
startZone - The time zone for the start. Not null.
end - End time
endZone - The time zone for the end. Not null.
Returns:
The daylight savings time difference.

addMillisDSTSafe

public static long addMillisDSTSafe(long millis,
                                    java.util.TimeZone timeZone,
                                    long amount)
Adds a number of milliseconds to cal, compensating for jumps over a Daylight Savings Time boundary, if present. Calendar.add() has this behaviour when HOUR or greater TYPES are added. If MILLISECONDS that are more than an hour are added no compensation for DST is made in SUN's code though. This method takes care of this.
This method should normally not be used for adding milliseconds that translates to under one hour, since it due to this DST compensation can have strange effects. Those sub-one-hour cases has to be taken care of manually.

Parameters:
millis - The milliseconds that represents the time.
timeZone - The time zone. If null the default will be used.
amount - The number of milliseconds to add.
Returns:
The new millisecond

addDSTSafe

public static java.util.Calendar addDSTSafe(java.util.Calendar cal,
                                            int field,
                                            int amount)
Calls Calendar.add(int, int) on cal and then compensating for jumps over a Daylight Savings Time boundary, if present. Calendar.add() has this behaviour when HOUR or greater TYPES are added. If MILLISECONDS that are more than an hour are added no compensation for DST is made in SUN's code though. This method takes care of this.
This method should normally not be used for adding milliseconds that translates to under one hour, since it due to this DST compensation can have strange effects. Those sub-one-hour cases has to be taken care of manually.

Parameters:
cal - The calendar to add the millis to
amount - The number of milliseconds to add.
Returns:
cal as a convenience for chaning.

getWeekDayOccurence

public static int getWeekDayOccurence(java.util.Calendar cal,
                                      int field,
                                      boolean fromStart)
Return which week day occurence in a year or month cal is representing. I.e. "How many times has the week day that cal represents occured in the current month/year, counting from the start/end".

Parameters:
cal - The date from where to get the day of week.
field - Either Calendar.DAY_OF_YEAR or Calendar.DAY_OF_MONTH. Not checked som ust be correct or the result will be undefined.
fromStart - If true the returned value is from the start of the MONTH/YEAR. false mens from the end if the MONTH/YEAR.
Returns:
which week day occurence in a year or month cal is representing.

setFieldCorrect

public static java.util.Calendar setFieldCorrect(java.util.Calendar cal,
                                                 int field,
                                                 int value)
Help to set a value on a Calendar. Since the Calendar.set(f, value) method on a Calendar is behaving in strange way for some fields, this method can help in certain circumstances. This method works more like Calendar.add(f, delta).
For instance, in a Calendar containing the date August 31 setting the MONTH to September would actually end up with the month beeing October (1:st).
In short, the setted field is guaranteed to be set to value with this method. If not, an exception is thrown, and that is to be considered a bug in this method.
Feb 29 -> feb 28 if year changes from leap year to normal year.
Read the java docs on the Calendar class. This method would set the day of month to 30 and the month to september.
The method also always do a .get() so that the Calendar actually resolves a new time, so there are no "half set" values that can be of truble later.
Also see bugID 4846659 in Sun's bug database.

Parameters:
cal - The calendar to change
field - The field to change. See Calendar
value - The value // * @param disregOutRng If true all attemps to set a "field out of range" is disregarded. E.g if cal is "2003-jan-31" and // * you try to set month to february, nothing will happen and the method will return false to indicate this.
Returns:
If the calendar accepted the values. Can only be false if

getAlternativesForField

public static java.lang.String[] getAlternativesForField(int field,
                                                         java.util.Calendar cal,
                                                         java.text.DateFormat dateFormat,
                                                         java.lang.Integer count)
Returns a list of alternante/near by choices, suitable for a popup menu or a combo box.

Parameters:
field - The field in Calendar to return alternates for. Handles: Calendar.YEAR
Calendar.MONTH
Calendar.DAY_OF_MONTH
Calendar.WEEK_OF_YEAR
Calendar.DAY_OF_WEEK
Calendar.HOUR
Calendar.MINUTE
cal - To know the base of nearby.
dateFormat - Teh format of the field. E.g. new SimpleDateFormat("MMMM") for a long month format. Should have correct Locale set.
Returns:
A list of possible (parsabe) alteratives for field. Not null.


Copyright © 2009 MiG InfoCom AB. All Rights Reserved.