org.dmfs.rfc5545

Class Instance

java.lang.Object

org.dmfs.rfc5545.Instance

public final class Instance
extends java.lang.Object

Provides a set of static methods to manipulate date and time values stored in a single packed long value.

Storing the values of an instance in a single long allows to compare them quickly and it doesn't require any object instantiations.

Note that the instance value alone doesn't say much without the corresponding CalendarMetrics and TimeZone.

Also note: never persist packed instance values. The implementation and the format of the packed long may change.

Method Summary

Modifier and Type	Method and Description
static int	dayOfMonth(long instance) Get the day of month of the given packed instance.
static int	dayOfWeek(long instance) Get the day of week stored in the packed instance.
static int	hour(long instance) Get the hour of the given packed instance.
static long	make(int year, int month, int dayOfMonth, int hour, int minute, int second) Return an instance value for the given date and time.
static long	make(int year, int month, int dayOfMonth, int hour, int minute, int second, int dayOfWeek) Return an instance value for the given date and time.
static long	maskWeekday(long instance) Masks the day of week value of the given instance.
static int	minute(long instance) Get the minute of the given packed instance.
static int	month(long instance) Get the month of the given packed instance.
static int	second(long instance) Get the seconds of the given packed instance.
static long	setDayOfMonth(long instance, int dayOfMonth) Update the day of month of the given instance.
static long	setDayOfWeek(long instance, int dayOfWeek) Update the day of week of the given instance.
static long	setHour(long instance, int hour) Update the hour of the given instance.
static long	setMinute(long instance, int minute) Update the minute of the given instance.
static long	setMonth(long instance, int month) Update the month of the given instance.
static long	setMonthAndDayOfMonth(long instance, int month, int dayOfMonth) Update the month and day of month of the given instance.
static long	setSecond(long instance, int second) Update the seconds of the given instance.
static long	setYear(long instance, int year) Update the year of the given instance.
static java.lang.String	toString(long instance) Convert the given instance to a String that conforms to RFC 5545, Section 3.3.5.
static java.lang.String	toString(long instance, boolean dateOnly) Convert the given instance to a String that conforms to RFC 5545, Section 3.3.5.
static void	writeTo(java.lang.StringBuilder out, long instance) Write a string representation of the given instance that conforms to RFC 5545, Section 3.3.5 to a StringBuilder.
static void	writeTo(java.lang.StringBuilder out, long instance, boolean dateOnly) Write a string representation of the given instance that conforms to RFC 5545, Section 3.3.5 to a StringBuilder.
static void	writeTo(java.io.Writer out, long instance) Write a string representation of the given instance that conforms to RFC 5545, Section 3.3.5 to a Writer.
static void	writeTo(java.io.Writer out, long instance, boolean dateOnly) Write a string representation of the given instance that conforms to RFC 5545, Section 3.3.5 to a Writer.
static int	year(long instance) Get the year of the given packed instance.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

make

public static long make(int year,
                        int month,
                        int dayOfMonth,
                        int hour,
                        int minute,
                        int second,
                        int dayOfWeek)

Return an instance value for the given date and time.

Parameters:

year - The year of the instance.

month - The month of the instance.

dayOfMonth - The day of the instance.

hour - The hour of the instance.

minute - The minutes of the instance.

second - The seconds of the instance.

dayOfWeek - The day of the week of the instance.

Returns:

The packed instance value.

make

public static long make(int year,
                        int month,
                        int dayOfMonth,
                        int hour,
                        int minute,
                        int second)

Return an instance value for the given date and time.

Parameters:

year - The year of the instance.

month - The month of the instance.

dayOfMonth - The day of the instance.

hour - The hour of the instance.

minute - The minutes of the instance.

second - The seconds of the instance.

Returns:

The packed instance value.

setYear

public static long setYear(long instance,
                           int year)

Update the year of the given instance.

Parameters:

instance - The instance to update.

year - The new year.

Returns:

The updated instance.

setMonth

public static long setMonth(long instance,
                            int month)

Update the month of the given instance.

Parameters:

instance - The instance to update.

month - The new month.

Returns:

The updated instance.

setDayOfMonth

public static long setDayOfMonth(long instance,
                                 int dayOfMonth)

Update the day of month of the given instance.

Parameters:

instance - The instance to update.

dayOfMonth - The new day of month value.

Returns:

The updated instance.

setDayOfWeek

public static long setDayOfWeek(long instance,
                                int dayOfWeek)

Update the day of week of the given instance.

Parameters:

instance - The instance to update.

dayOfWeek - The new day of week value.

Returns:

The updated instance.

setMonthAndDayOfMonth

public static long setMonthAndDayOfMonth(long instance,
                                         int month,
                                         int dayOfMonth)

Update the month and day of month of the given instance. This is basically like calling setMonth(long, int) and setDayOfMonth(long, int), just shorter.

Parameters:

instance - The instance to update.

month - The new month value.

dayOfMonth - The new day of month value.

Returns:

The updated instance.

setHour

public static long setHour(long instance,
                           int hour)

Update the hour of the given instance.

Parameters:

instance - The instance to update.

hour - The new hour value.

Returns:

The updated instance.

setMinute

public static long setMinute(long instance,
                             int minute)

Update the minute of the given instance.

Parameters:

instance - The instance to update.

minute - The new minute value.

Returns:

The updated instance.

setSecond

public static long setSecond(long instance,
                             int second)

Update the seconds of the given instance.

Parameters:

instance - The instance to update.

second - The new seconds value.

Returns:

The updated instance.

maskWeekday

public static long maskWeekday(long instance)

Masks the day of week value of the given instance. The returned value represents the same instance, but day of week will be set to 0.

Parameters:

instance - The instance to mask.

Returns:

The instance value with masked day of week.

year

public static int year(long instance)

Get the year of the given packed instance.

Parameters:

instance - The instance.

Returns:

The year.

month

public static int month(long instance)

Get the month of the given packed instance.

Parameters:

instance - The instance.

Returns:

The month.

dayOfMonth

public static int dayOfMonth(long instance)

Get the day of month of the given packed instance.

Parameters:

instance - The instance.

Returns:

The day of month.

hour

public static int hour(long instance)

Get the hour of the given packed instance.

Parameters:

instance - The instance.

Returns:

The hour.

minute

public static int minute(long instance)

Get the minute of the given packed instance.

Parameters:

instance - The instance.

Returns:

The minute.

second

public static int second(long instance)

Get the seconds of the given packed instance.

Parameters:

instance - The instance.

Returns:

The seconds.

dayOfWeek

public static int dayOfWeek(long instance)

Get the day of week stored in the packed instance. If the day of week has not been stored, this method returns an invalid value. You have to ensure yourself that this value is valid. If in doubt, use CalendarMetrics.getDayOfWeek(int, int, int) to get the actual day of week.

Values are from 0-6 where 0 means Sunday and 6 means Saturday. Note that this is different from the values the Calendar class uses.

Parameters:

instance - The instance.

Returns:

The day of the week, if present.

toString

public static java.lang.String toString(long instance)

Convert the given instance to a String that conforms to RFC 5545, Section 3.3.5.

Example:

 20150304T203000
 

Parameters:

instance - An instance value.

Returns:

The formatted date-time value.

See Also:

toString(long, boolean)

toString

public static java.lang.String toString(long instance,
                                        boolean dateOnly)

Convert the given instance to a String that conforms to RFC 5545, Section 3.3.5. This method has a parameter to tell whether the time part should be included or not.

Example:

 dateOnly == false: 20150304T203000
 dateOnly == true:  20150304
 

Parameters:

instance - An instance value.

dateOnly - true to return the date value only, false to also append the time.

Returns:

The formatted date-time value.

See Also:

toString(long)

writeTo

public static void writeTo(java.lang.StringBuilder out,
                           long instance)

Write a string representation of the given instance that conforms to RFC 5545, Section 3.3.5 to a StringBuilder. This method always writes a time value. Use writeTo(Writer, long, boolean) to write only the date.

Example:

 20150304T203000
 

Parameters:

out - The StringBuilder to write to.

instance - An instance value.

See Also:

writeTo(Writer, long, boolean)

writeTo

public static void writeTo(java.lang.StringBuilder out,
                           long instance,
                           boolean dateOnly)

Write a string representation of the given instance that conforms to RFC 5545, Section 3.3.5 to a StringBuilder. This method has a parameter to tell whether the time part should be written or not.

Example:

 dateOnly == false: 20150304T203000
 dateOnly == true:  20150304
 

Parameters:

out - The StringBuilder to write to.

instance - An instance value.

dateOnly - true to write the date value only, false to also write the time.

See Also:

writeTo(StringBuilder, long)

writeTo

public static void writeTo(java.io.Writer out,
                           long instance)
                    throws java.io.IOException

Write a string representation of the given instance that conforms to RFC 5545, Section 3.3.5 to a Writer. This method always writes a time value. Use writeTo(Writer, long, boolean) to write only the date.

Example:

 20150304T203000
 

Parameters:

out - The Writer to write to.

instance - An instance value.

Throws:

java.io.IOException

See Also:

writeTo(Writer, long, boolean)

writeTo

public static void writeTo(java.io.Writer out,
                           long instance,
                           boolean dateOnly)
                    throws java.io.IOException

Write a string representation of the given instance that conforms to RFC 5545, Section 3.3.5 to a Writer. This method has a parameter to tell whether the time part should be written or not.

Example:

 dateOnly == false: 20150304T203000
 dateOnly == true:  20150304
 

Parameters:

out - The Writer to write to.

instance - An instance value.

dateOnly - true to write the date value only, false to also write the time.

Throws:

java.io.IOException

See Also:

writeTo(Writer, long)