org.dmfs.rfc5545.calendarmetrics

Class CalendarMetrics

java.lang.Object

org.dmfs.rfc5545.calendarmetrics.CalendarMetrics

Direct Known Subclasses:

NoLeapMonthCalendarMetrics

public abstract class CalendarMetrics
extends java.lang.Object

Provides a set of methods that return all kinds of information about a calendar and do some calendar calculations.

Please note that most methods use a packed month instead of just a month number. That's due to the need to specify leap months in certain calendaring systems. Do not make any assumptions about the format of the packed month since this is an internal implementation detail. To get the actual month number and the leap month flag use monthNum(int) and isLeapMonth(int).

However, packed months are integers that are guaranteed to be comparable with respect to their natural order. So if a and b are two packed months, it's guaranteed that a<b if a comes before b in the year.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CalendarMetrics.CalendarMetricsFactory

Field Summary

Fields

Modifier and Type	Field and Description
int	minDaysInFirstWeek The minimal number of days in the first week.
Weekday	weekStart The first day of the week.
int	weekStartInt The first day of the week int.

Constructor Summary

Constructors

Constructor and Description
CalendarMetrics(java.lang.String name, Weekday weekStart, int minDaysInFirstWeek)

Method Summary

Modifier and Type	Method and Description
static int	dayOfMonth(int monthAndDay) Get the day of month from a compound MonthAndDay value like getMonthAndDayOfYearDay(int, int) and monthAndDay(int, int) return it.
boolean	equals(java.lang.Object obj) By default two CalendarMetrics equal when they are of the same class and the week definition equals.
abstract int	getDayOfMonthOfYearDay(int year, int yearDay) Determines the day of month for a given day of year.
int	getDayOfWeek(int year, int yearDay) Returns the day of week of the given year date.
int	getDayOfWeek(int year, int packedMonth, int dayOfMonth) Returns the day of week of the given date.
abstract int	getDayOfYear(int year, int packedMonth, int dayOfMonth) Get the day of the year for the specified date.
abstract int	getDaysPerPackedMonth(int year, int packedMonth) Get the number of days in a specific packed month.
abstract int	getDaysPerYear(int year) Get the number of days in the given year.
abstract int	getMaxMonthDayNum() Returns the largest month day number that the current calendar supports.
abstract int	getMaxWeekNoNum() Returns the largest week number that the current calendar supports.
abstract int	getMaxYearDayNum() Returns the largest year day number that the current calendar supports.
abstract int	getMonthAndDayOfYearDay(int year, int yearDay) Determines the month and day for a given day of year.
abstract int	getMonthsPerYear(int year) Get the number of months in the given year.
abstract int	getPackedMonthOfYearDay(int year, int yearDay) Determines the month of a given day of year.
abstract int	getWeekDayOfFirstYearDay(int year) Get the weekday of the first day (which is January the 1st in a Gregorian Calendar) in the given year.
abstract int	getWeekOfYear(int year, int yearDay) Get the ISO week number of the given date.
int	getWeekOfYear(int year, int packedMonth, int dayOfMonth) Get the ISO week number of the given date.
abstract int	getWeeksPerYear(int year) Get the number of ISO weeks in the given year.
abstract int	getYearDayOfFirstWeekStart(int year) Get the day of year of the start of the first week in a year.
abstract int	getYearDayOfIsoYear(int year, int weekOfYear, int dayOfWeek) Get the day of the year for the specified ISO week date, see ISO week date If the day belongs to the previous year zero or a negative value is returned.
abstract int	getYearDayOfWeekStart(int year, int week) Get the day of year of the start of the given week in a year.
abstract int	getYearDaysForPackedMonth(int year, int packedMonth) Get the number of days preceding the given month in the given year.
int	hashCode()
boolean	isLeapMonth(int packedMonth) Returns whether a certain packed month is a leap month, i.e. a month that exists in certain years only.
static int	monthAndDay(int packedMonth, int day) Returns a packed value that contains a packed month and a month day.
int	monthNum(int packedMonth) Returns the month number of a packed month.
abstract long	nextDay(long instance) Moves the given instance forward to the next (existing day).
abstract long	nextDay(long instance, int n) Moves the given instance forward by one or more days.
abstract long	nextMonth(long instance) Moves the given instance forward by one month.
abstract long	nextMonth(long instance, int n) Moves the given instance forward by one or more months.
static int	packedMonth(int monthAndDay) Get the packed month from a compound MonthAndDay value like getMonthAndDayOfYearDay(int, int) and monthAndDay(int, int) return it.
int	packedMonth(int monthNum, boolean leapMonth) Returns a packed month, which is a combination of the month number and a leap month flag.
int	packedMonth(java.lang.String month) Returns a packed month from a string representation.
java.lang.String	packedMonthToString(int packedMonth) Convert the packed month to a numerical string representation.
abstract long	prevDay(long instance) Moves the given instance backward to the previous (existing) day.
abstract long	prevDay(long instance, int n) Moves the given instance backward by one or more days.
abstract long	prevMonth(long instance) Moves the given instance backward by one month.
abstract long	prevMonth(long instance, int n) Moves the given instance backward by one or more months.
boolean	scaleEquals(CalendarMetrics obj) Returns whether two CalendarMetrics implement the same calendar scale.
long	setDayOfWeek(long instance, int dayOfWeek) Changes the day of week of the given instance ot the given value, but keeping the week number constant
long	startOfWeek(long instance) Get the start date of the week the given instance is in.
abstract long	toInstance(long timestamp, java.util.TimeZone timeZone) Converts a timestamp to an instance in the given TimeZone.
long	toMillis(long instance, java.util.TimeZone timeZone) Convert an instance to milliseconds since the epoch (i.e. since 1970-01-01 0:00:00 UTC).
abstract long	toMillis(java.util.TimeZone timeZone, int year, int packedMonth, int dayOfMonth, int hours, int minutes, int seconds, int millis) Convert the given (local) date to milliseconds since the epoch using the given TimeZone.
java.lang.String	toString()
boolean	validate(long instance) Validates the given instance.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

weekStart

public final Weekday weekStart

The first day of the week.

weekStartInt

public final int weekStartInt

The first day of the week int.

minDaysInFirstWeek

public final int minDaysInFirstWeek

The minimal number of days in the first week.

Constructor Detail

CalendarMetrics

public CalendarMetrics(java.lang.String name,
                       Weekday weekStart,
                       int minDaysInFirstWeek)

Method Detail

monthAndDay

public static int monthAndDay(int packedMonth,
                              int day)

Returns a packed value that contains a packed month and a month day.

Parameters:

packedMonth - The packed month.

day - The day of month.

Returns:

A packed value, containing the packed month and the day.

See Also:

packedMonth(int), dayOfMonth(int)

packedMonth

public static int packedMonth(int monthAndDay)

Get the packed month from a compound MonthAndDay value like getMonthAndDayOfYearDay(int, int) and monthAndDay(int, int) return it.

Parameters:

monthAndDay - An integer that contains a packed month and a day.

Returns:

The packed month.

dayOfMonth

public static int dayOfMonth(int monthAndDay)

Get the day of month from a compound MonthAndDay value like getMonthAndDayOfYearDay(int, int) and monthAndDay(int, int) return it.

Parameters:

monthAndDay - An integer that contains a packed month and a day.

Returns:

The day of month.

packedMonth

public int packedMonth(java.lang.String month)

Returns a packed month from a string representation. The packed months are arithmetically comparable with respect to their natural order.

The string representation is the 1-based month number followed by an optional L literal to indicate a leap month.

Parameters:

month - The string representation of the month.

Returns:

A packed representation of the month.

Throws:

java.lang.IllegalArgumentException - if the given (leap-) month does not exist in this calendar scale or the month string is otherwise malformed.

packedMonthToString

public java.lang.String packedMonthToString(int packedMonth)

Convert the packed month to a numerical string representation.

Parameters:

packedMonth - The packed month.

Returns:

The converted month.

packedMonth

public int packedMonth(int monthNum,
                       boolean leapMonth)

Returns a packed month, which is a combination of the month number and a leap month flag. The packed months are arithmetically comparable with respect to their natural order.

Note that not all calendar scales support leap months.

Parameters:

monthNum - The 0-based month number.

leapMonth - true if this is a leap month, false otherwise.

Returns:

A packed representation of the month.

Throws:

java.lang.IllegalArgumentException - if the given (leap-) month does not exist in this calendar scale.

isLeapMonth

public boolean isLeapMonth(int packedMonth)

Returns whether a certain packed month is a leap month, i.e. a month that exists in certain years only.

Parameters:

packedMonth - The packed month to test.

Returns:

true if the month is a leap month, false otherwise.

monthNum

public int monthNum(int packedMonth)

Returns the month number of a packed month.

Parameters:

packedMonth - The packed month.

Returns:

the month number that is encoded in the packed month.

getMaxMonthDayNum

public abstract int getMaxMonthDayNum()

Returns the largest month day number that the current calendar supports.

Returns:

The maximum month number in this calendar scale.

getMaxYearDayNum

public abstract int getMaxYearDayNum()

Returns the largest year day number that the current calendar supports.

Returns:

The maximum year day number in this calendar scale.

getMaxWeekNoNum

public abstract int getMaxWeekNoNum()

Returns the largest week number that the current calendar supports.

Returns:

The maximum ISO week number in this calendar scale.

getDaysPerPackedMonth

public abstract int getDaysPerPackedMonth(int year,
                                          int packedMonth)

Get the number of days in a specific packed month.

Parameters:

year - The year.

packedMonth - The packed month.

Returns:

The number of days in that month.

getPackedMonthOfYearDay

public abstract int getPackedMonthOfYearDay(int year,
                                            int yearDay)

Determines the month of a given day of year.

Parameters:

year - The year.

yearDay - The year day.

Returns:

the packed month.

getDayOfMonthOfYearDay

public abstract int getDayOfMonthOfYearDay(int year,
                                           int yearDay)

Determines the day of month for a given day of year.

Parameters:

year - The year.

yearDay - The year day.

Returns:

the month day.

getMonthAndDayOfYearDay

public abstract int getMonthAndDayOfYearDay(int year,
                                            int yearDay)

Determines the month and day for a given day of year. The result contains both, packed month and day in a single integer. To split the values use packedMonth(int) and dayOfMonth(int) like in:

 int monthAndDay = mCalendarMetrics.getMonthAndDayOfYearDay(year, yearDay);
 int month = CalendarMetrics.packedMonth(monthAndDay);
 int dayOfMonth = CalendarMetrics.dayOfMonth(monthAndDay);
 

Parameters:

year - The year.

yearDay - The day of the year. Must be a valid value between 1 and the maximum number of days in that year.

Returns:

an integer with the day of month in the lowest significant byte and the packed month in the second lowest significant byte.

getYearDaysForPackedMonth

public abstract int getYearDaysForPackedMonth(int year,
                                              int packedMonth)

Get the number of days preceding the given month in the given year.

Parameters:

year - The year.

packedMonth - The packed month.

Returns:

The days in the year preceding the month.

getMonthsPerYear

public abstract int getMonthsPerYear(int year)

Get the number of months in the given year.

Parameters:

year - The year.

Returns:

The number of months in that year.

getDaysPerYear

public abstract int getDaysPerYear(int year)

Get the number of days in the given year.

Parameters:

year - The year.

Returns:

The number of days in that year.

getWeeksPerYear

public abstract int getWeeksPerYear(int year)

Get the number of ISO weeks in the given year.

Parameters:

year - The year.

Returns:

The number of weeks in that year.

getWeekOfYear

public int getWeekOfYear(int year,
                         int packedMonth,
                         int dayOfMonth)

Get the ISO week number of the given date.

Note: this will return 0 if the week belongs to the previous ISO year and a value greater than getWeeksPerYear(int) if the week belongs to the next ISO year.

Parameters:

year - The year.

packedMonth - The packed month.

dayOfMonth - The day of month.

Returns:

The ISO week number.

getWeekOfYear

public abstract int getWeekOfYear(int year,
                                  int yearDay)

Get the ISO week number of the given date.

Note: this will return 0 if the week belongs to the previous ISO year and a value greater than getWeeksPerYear(int) if the week belongs to the next ISO year.

Parameters:

year - The year.

yearDay - The day of year.

Returns:

The ISO week number.

getDayOfWeek

public int getDayOfWeek(int year,
                        int yearDay)

Returns the day of week of the given year date.

Parameters:

year - The year.

yearDay - The day of the year.

Returns:

An integer for the day of the week where 0 means Sunday and 6 means Saturday or the respective week days in the respective calendar scale.

getDayOfWeek

public int getDayOfWeek(int year,
                        int packedMonth,
                        int dayOfMonth)

Returns the day of week of the given date.

Parameters:

year - The year.

packedMonth - The packed month number.

dayOfMonth - The day of the month.

Returns:

An int for the day of the week where 0 means Sunday and 6 means Saturday or the respective week days in the respective calendar scale.

getDayOfYear

public abstract int getDayOfYear(int year,
                                 int packedMonth,
                                 int dayOfMonth)

Get the day of the year for the specified date.

Parameters:

year - The year.

packedMonth - The packed month.

dayOfMonth - The day of month.

Returns:

The day of year.

getYearDayOfIsoYear

public abstract int getYearDayOfIsoYear(int year,
                                        int weekOfYear,
                                        int dayOfWeek)

Get the day of the year for the specified ISO week date, see ISO week date

If the day belongs to the previous year zero or a negative value is returned. If the day belongs to the next year the result is larger than getDaysPerYear(int) for year.

Parameters:

year - The year.

weekOfYear - The ISO week of the year.

dayOfWeek - The day of the week.

Returns:

The day of year.

getWeekDayOfFirstYearDay

public abstract int getWeekDayOfFirstYearDay(int year)

Get the weekday of the first day (which is January the 1st in a Gregorian Calendar) in the given year.

Parameters:

year - The year.

Returns:

The weekday number.

getYearDayOfFirstWeekStart

public abstract int getYearDayOfFirstWeekStart(int year)

Get the day of year of the start of the first week in a year. Note this method returns values below 1 if the start of the week is in the previous year. The result depends on the values of weekStart and minDaysInFirstWeek.

Parameters:

year - The year.

Returns:

The day of year.

getYearDayOfWeekStart

public abstract int getYearDayOfWeekStart(int year,
                                          int week)

Get the day of year of the start of the given week in a year. Note this method returns values below 1 if the start of the week is in the previous year. The result depends on the values of weekStart and minDaysInFirstWeek.

Parameters:

year - The year.

week - The week.

Returns:

The day of year.

toMillis

public long toMillis(long instance,
                     java.util.TimeZone timeZone)

Convert an instance to milliseconds since the epoch (i.e. since 1970-01-01 0:00:00 UTC).

Parameters:

instance - The instance to convert.

timeZone - The time zone or null for all day and floating instances.

Returns:

The time in milliseconds since the epoch of this instance.

toMillis

public abstract long toMillis(java.util.TimeZone timeZone,
                              int year,
                              int packedMonth,
                              int dayOfMonth,
                              int hours,
                              int minutes,
                              int seconds,
                              int millis)

Convert the given (local) date to milliseconds since the epoch using the given TimeZone.

Parameters:

timeZone - The time zone or null for floating dates (and all-day dates).

year - The year.

packedMonth - The packed month.

dayOfMonth - The day of the month.

hours - The hour of the day.

minutes - The minutes.

seconds - The seconds.

millis - The milliseconds.

Returns:

The milliseconds since the epoch.

toInstance

public abstract long toInstance(long timestamp,
                                java.util.TimeZone timeZone)

Converts a timestamp to an instance in the given TimeZone.

Parameters:

timestamp - The time in milliseconds since the epoch.

timeZone - The time zone, may be null in which case UTC will be used.

Returns:

a packed instance.

validate

public boolean validate(long instance)

Validates the given instance.

At present this method doesn't check for leap seconds and it doesn't honor daylight saving switches. So it validates times between 2:00h and 3:00 to true even if the local time can't have these values due to daylight savings.

TODO: add check for daylight saving changes.

Parameters:

instance - The instance to validate.

Returns:

true if the date is valid, false otherwise.

nextMonth

public abstract long nextMonth(long instance)

Moves the given instance forward by one month. In many cases this is faster than nextMonth(long, int) with n = 1.

Parameters:

instance - The instance to modify.

Returns:

A new instance.

nextMonth

public abstract long nextMonth(long instance,
                               int n)

Moves the given instance forward by one or more months.

Parameters:

instance - The instance to modify.

n - The number of months to add.

Returns:

A new instance.

prevMonth

public abstract long prevMonth(long instance)

Moves the given instance backward by one month. In many cases this is faster than prevMonth(long, int) with n = 1.

Parameters:

instance - The instance to modify.

Returns:

A new instance.

prevMonth

public abstract long prevMonth(long instance,
                               int n)

Moves the given instance backward by one or more months.

Parameters:

instance - The instance to modify.

n - The number of months to go back.

Returns:

A new instance.

nextDay

public abstract long nextDay(long instance)

Moves the given instance forward to the next (existing day).

Parameters:

instance - The instance to modify.

Returns:

A new instance.

nextDay

public abstract long nextDay(long instance,
                             int n)

Moves the given instance forward by one or more days.

Parameters:

instance - The instance to modify.

n - The number of days to add.

Returns:

A new instance.

prevDay

public abstract long prevDay(long instance)

Moves the given instance backward to the previous (existing) day.

Parameters:

instance - The instance to modify.

Returns:

A new instance.

prevDay

public abstract long prevDay(long instance,
                             int n)

Moves the given instance backward by one or more days.

Parameters:

instance - The instance to modify.

n - The number of days to go back.

Returns:

A new instance.

startOfWeek

public long startOfWeek(long instance)

Get the start date of the week the given instance is in.

Parameters:

instance - The instance.

Returns:

The instance of the start of the week.

setDayOfWeek

public long setDayOfWeek(long instance,
                         int dayOfWeek)

Changes the day of week of the given instance ot the given value, but keeping the week number constant

Parameters:

instance - The instance to modify.

dayOfWeek - The new day of the week.

Returns:

A new instance.

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

By default two CalendarMetrics equal when they are of the same class and the week definition equals. Subclasses may override this to change this behavior, i.e. Islamic calendars need to match the leap year rule as well.

Overrides:

equals in class java.lang.Object

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

scaleEquals

public boolean scaleEquals(CalendarMetrics obj)

Returns whether two CalendarMetrics implement the same calendar scale.

By default two CalendarMetrics use the same calendar scale when they are of the same class. Subclasses may override this to change this behavior, i.e. Islamic calendars need to match the leap year rule as well.