<?xml version="1.0" encoding="ISO-8859-1"?>

<document>

 <properties>
  <title>Java date and time API - Partial</title>
  <author>Stephen Colebourne</author>
 </properties>

 <body>

<section name="Partial">

<p>
A <i>partial</i> in Joda-Time is a partial date and time representation.
All implementations represent local dates and times, and do not reference a time zone.
As such, they only <i>partially</i> represent a date or time in the datetime continuum.
</p>
<p>
The main implementations changed in version 1.3.
This was to address implementation issues with the original design.
The previous classes - <code>TimeofDay</code> and <code>YearMonthDay</code> - are now effectively deprecated.
The new implementations are <code>LocalDate</code>, <code>LocalTime</code> and <code>LocalDateTime</code>.
</p>
<p>
It is not possible to directly interoperate between a partial and an <a href="key_instant.html">instant</a>.
A partial does not fully specify a single point in the datetime continuum, but instead may match
multiple points. For example, a <code>LocalTime</code> occurs once per day on the datetime continuum.
</p>
<p>
A partial can be converted to a full instant by specifying the missing values.
At a minimum the time zone must be specified. It may be necessary to specify other missing fields.
For example, to convert a <code>LocalDate</code> to a <code>DateTime</code> requires
filling in the time fields and the time zone.
</p>
<p>
In terms of datetime maths, you could write:
<source>
      partial  +  missing fields  +  time zone  =  instant
</source>
</p>

<subsection name="Date representations">
<p>
Two classes represent a date in Joda-Time - <code>DateMidnight</code> and <code>LocalDate</code>.
These have different meanings.
<code>DateMidnight</code> is a fully specified instant, with a time zone.
It is defined as the millisecond instant at exactly mignight (00:00) at the start of a day.
<code>LocalDate</code> 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.
</p>
</subsection>

</section>

<section name="Using Partials in Joda-Time">
<p>
Within Joda-Time a partial is represented by the
<a href="apidocs/org/joda/time/ReadablePartial.html">ReadablePartial</a> interface.
There are six implementations of the interface provided:
<ul>
<li><a href="apidocs/org/joda/time/LocalDate.html">LocalDate</a> -
An immutable implementation that represents a date without a time or time zone.</li>
<li><a href="apidocs/org/joda/time/LocalTime.html">LocalTime</a> -
An immutable implementation that represents a time without a date or time zone.</li>
<li><a href="apidocs/org/joda/time/LocalDateTime.html">LocalDateTime</a> -
An immutable implementation that represents a datetime without a time zone.</li>
<li><a href="apidocs/org/joda/time/YearMonth.html">YearMonth</a> -
An immutable implementation that represents a year and month, useful for credit card expiry dates.</li>
<li><a href="apidocs/org/joda/time/MonthDay.html">MonthDay</a> -
An immutable implementation that represents a month and day, useful for birthdays without years.</li>
<li><a href="apidocs/org/joda/time/Partial.html">Partial</a> -
An immutable implementation that can store any combination of datetime fields.
For example, using this class you could create a YearMonth or DayOfWeekDayOfMonth partial.</li>
<li><a href="apidocs/org/joda/time/YearMonthDay.html">YearMonthDay</a> -
Effectively deprecated - only supports the year, monthOfYear and dayOfMonth fields.</li>
<li><a href="apidocs/org/joda/time/TimeOfDay.html">TimeOfDay</a> -
Effectively deprecated - only supports the hour, minute, second and millisecond fields.</li>
</ul>
</p>
<p>
The code can be used in various ways:
<source>
// setup objects
LocalDate date = new LocalDate(2004, 12, 25);
LocalTime time = new LocalTime(12, 20);

int year = date.getYear();  // returns 2004
int hour = time.getHour();  // returns 12
String monthStr = date.month().getAsText();  // returns 'December'
</source>
Conversion to and from instants is easy:
<source>
LocalDate date = new LocalDate(2004, 12, 25);
LocalTime time = new LocalTime(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 = ...
LocalDate date = new LocalDate(someDT);
</source>
</p>
<p>
Note that the interface <code>ReadablePartial</code> 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.
</p>

<subsection name="Nulls">
<p>
Joda-Time defines a null partial as the current time.
Thus, when a method is defined as taking a <code>ReadablePartial</code>, passing null in
will be the same as passing in a partial set to the current time.
</p>
</subsection>

</section>

</body>
</document>
