Partial

A partial in Joda-Time is a partial date and time representation. The two supplied implementations are TimeofDay and YearMonthDay. These classes do not store the date or time using a long millisecond instant, but instead store individual int field values. They also do not store the time zone, and thus represent local times.

These classes were created as it is not possible to directly interoperate between a local time and an instant. A partial does not fully specify a single point in the datetime continuum. Instead, a partial describes various datetime fields. For example, a TimeofDay occurs many times on the datetime continuum - once per day.

A partial can be converted to a full instant by specifying the missing values. If just the time zone is specified then the missing values are filled in from the current date and time. Alternatively, an instant may be specified, and the result is the merger of the fields from the instant and the partial.

In terms of datetime maths, you could write:

      partial  +  missing fields  +  time zone  =  instant

Date representations

Two classes represent a date in Joda-Time - DateMidnight and YearMonthDay. These have different meanings. DateMidnight is a fully specified instant, with a time zone. It is defined as the milliseond instant at exactly mignight (00:00) at the start of a day. YearMonthDay defines a day using the year, monthOfYear and dayOfMonth fields and no time zone. It can be thought of as a local date that covers the whole of the day from 00:00 to 23:59.

Using Partials in Joda-Time

Within Joda-Time a partial is represented by the ReadablePartial interface. There are two implementations of the interface provided:

  • TimeOfDay - An immutable implementation that stores the hour, minute, second and millisecond fields.
  • YearMonthDay - An immutable implementation that stores the year, monthOfYear and dayOfMonth fields.
  • Partial - An immutable implementation that can store any combination of datetime fields. For example, using this class you could create a YearMonth or DayOfWeekDayOfMonth partial.

The code can be used in various ways:

// setup objects
YearMonthDay date = new YearMonthDay(2004, 12, 25);
TimeOfDay time = new TimeOfDay(12, 20);

int year = date.getYear();  // returns 2004
int hour = time.getHour();  // returns 12
String monthStr = date.month().getAsText();  // returns 'December'
Conversion to and from instants is easy:
YearMonthDay date = new YearMonthDay(2004, 12, 25);
TimeOfDay time = new TimeOfDay(12, 20);

// merge, resulting in 2004-25-12T12:20 (default time zone)
DateTime dt = date.toDateTime(time);

// extract the date fields from someDT
DateTime someDT = ...
YearMonthDay date = new YearMonthDay(someDT);

Note that the interface ReadablePartial should not be used like the collections API. The interface only contains the core subset of the operations. Instead, you should refer directly to the implementation classes in your APIs.

Nulls

Joda-Time defines a null partial as the current time. Thus, when a method is defined as taking a ReadablePartial, passing null in will be the same as passing in a partial set to the current time.