java/joda-time-2.3/src/site/xdoc/key_partial.xml - third_party - Git at Google

 <?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 one 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 milliseond 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>
	<?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 one 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 milliseond 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>