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

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

 <document>
  <properties>
   <title>Java date and time API - Quick start guide</title>
   <author>Stephen Colebourne</author>
  </properties>
 <body>

 <!-- ========================================================================= -->

 <section name="Quick start guide">
 <p>
 This is the quick introduction guide to Joda-Time and the features on offer.
 Its designed for those of you who are too impatient to read the full
 <a href="userguide.html">user guide</a>.
 </p>

 <subsection name="Date and Time">
 <p>
 Joda-Time includes these key datetime classes:
 <ul>
 <li><a href="apidocs/org/joda/time/DateTime.html"><code>DateTime</code></a> - Immutable replacement for JDK <code>Calendar</code></li>
 <li><a href="apidocs/org/joda/time/DateMidnight.html"><code>DateMidnight</code></a> - Immutable class representing a date where the time is forced to midnight</li>
 <li><a href="apidocs/org/joda/time/LocalDate.html"><code>LocalDate</code></a> - Immutable class representing a local date without a time (no time zone)</li>
 <li><a href="apidocs/org/joda/time/LocalTime.html"><code>LocalTime</code></a> - Immutable class representing a time without a date (no time zone)</li>
 <li><a href="apidocs/org/joda/time/LocalDateTime.html"><code>LocalDateTime</code></a> - Immutable class representing a local date and time (no time zone)</li>
 </ul>
 </p>

 <p>
 Each datetime class provides a variety of constructors.
 These include the <code>Object</code> constructor.
 This allows you to construct, for example, <code>DateTime</code> from
 the following objects:
 <ul>
 <li><code>Date</code> - a JDK instant</li>
 <li><code>Calendar</code> - a JDK calendar</li>
 <li><code>String</code> - in ISO8601 format</li>
 <li><code>Long</code> - in milliseconds</li>
 <li>any Joda-Time datetime class</li>
 </ul>
 This list is extensible. In other words Joda-Time sacrifices a little type-safety
 for extensibility. It does mean however, that converting from a JDK <code>Date</code>
 or <code>Calendar</code> to a Joda-Time class is easy - simply pass the JDK class
 into the constructor.
 </p>

 <p>
 Each datetime class provides simple easy methods
 to access the datetime <a href="field.html">fields</a>. For example, to access
 the month you can use:
 <source>
   DateTime dt = new DateTime();
   int month = dt.getMonthOfYear();
 </source>
 </p>

 <p>
 All the main datetime classes are immutable (like String) and cannot be changed
 after creation. However, simple methods have been provided to alter field values
 in a newly created object. For example, to set the year, or add 2 hours you can use:
 <source>
   DateTime dt = new DateTime();
   DateTime year2000 = dt.withYear(2000);
   DateTime twoHoursLater = dt.plusHours(2);
 </source>
 </p>

 <p>
 In addition to the basic get methods, each datetime class provides property
 methods for each field. These provide access to the full wealth of Joda-Time
 functionality. For example, to access details about a month or year:
 <source>
   DateTime dt = new DateTime();
   String monthName = dt.monthOfYear().getAsText();
   String frenchShortName = dt.monthOfYear().getAsShortText(Locale.FRENCH);
   boolean isLeapYear = dt.year().isLeap();
   DateTime rounded = dt.dayOfMonth().roundFloorCopy();
 </source>
 </p>
 </subsection>

 <subsection name="Calendar systems and time zones">
 <p>
 Joda-Time provides support for multiple calendar systems and the full range
 of time zones.
 The <a href="apidocs/org/joda/time/Chronology.html"><code>Chronology</code></a>
 and <a href="apidocs/org/joda/time/DateTimeZone.html"><code>DateTimeZone</code></a>
 classes provide this support.
 </p>
 <p>
 Joda-Time defaults to using the ISO calendar system (the calendar used by most
 of the business world) and the default time zone of your machine.
 These default values can be overridden whenever necessary.
 Please note that the ISO calendar system is historically inaccurate before 1583.
 </p>
 <p>
 Joda-Time uses a pluggable mechanism for calendars. (The JDK uses subclasses
 such as <code>GregorianCalendar</code>.)
 To obtain a Joda-Time calendar, use one of the factory methods on <code>Chronology</code>.
 <source>
   Chronology coptic = CopticChronology.getInstance();
 </source>
 </p>
 <p>
 Time zones are implemented as part of the chronology.
 To obtain a Joda-Time chronology in the Tokyo time zone, you can use.
 <source>
   DateTimeZone zone = DateTimeZone.forID("Asia/Tokyo");
   Chronology gregorianJuian = GJChronology.getInstance(zone);
 </source>
 </p>
 </subsection>

 <subsection name="Intervals and time periods">
 <p>
 Joda-Time provides support for intervals and time periods.
 </p>
 <p>
 An interval is represented by the
 <a href="apidocs/org/joda/time/Interval.html"><code>Interval</code></a> class.
 It holds a start and end datetime, and allows operations based around that
 range of time.
 </p>
 <p>
 A time period is represented by the
 <a href="apidocs/org/joda/time/Period.html"><code>Period</code></a> class.
 This holds a period such as 6 months, 3 days and 7 hours.
 You can create a <code>Period</code> directly, or derive it from an interval.
 </p>
 <p>
 A time duration is represented by the
 <a href="apidocs/org/joda/time/Duration.html"><code>Duration</code></a> class.
 This holds an exact duration in milliseconds.
 You can create a <code>Duration</code> directly, or derive it from an interval.
 </p>
 <p>
 Although a period and a duration may seem similar, they operate differently.
 For example, consider adding one day to a <code>DateTime</code> at the daylight
 savings cutover.
 <source>
   DateTime dt = new DateTime(2005, 3, 26, 12, 0, 0, 0);
   DateTime plusPeriod = dt.plus(Period.days(1));
   DateTime plusDuration = dt.plus(new Duration(24L*60L*60L*1000L));
 </source>
 Adding a period will add 23 hours in this case, not 24 because of the daylight
 savings change, thus the time of the result will still be midday.
 Adding a duration will add 24 hours no matter what, thus the time of the result
 will change to 13:00.
 </p>
 </subsection>
 </section>
 </body>
 </document>
	<?xml version="1.0" encoding="ISO-8859-1"?>

	<document>
	<properties>
	<title>Java date and time API - Quick start guide</title>
	<author>Stephen Colebourne</author>
	</properties>
	<body>

	<!-- ========================================================================= -->

	<section name="Quick start guide">
	<p>
	This is the quick introduction guide to Joda-Time and the features on offer.
	Its designed for those of you who are too impatient to read the full
	<a href="userguide.html">user guide</a>.
	</p>

	<subsection name="Date and Time">
	<p>
	Joda-Time includes these key datetime classes:
	<ul>
	<li><a href="apidocs/org/joda/time/DateTime.html"><code>DateTime</code></a> - Immutable replacement for JDK <code>Calendar</code></li>
	<li><a href="apidocs/org/joda/time/DateMidnight.html"><code>DateMidnight</code></a> - Immutable class representing a date where the time is forced to midnight</li>
	<li><a href="apidocs/org/joda/time/LocalDate.html"><code>LocalDate</code></a> - Immutable class representing a local date without a time (no time zone)</li>
	<li><a href="apidocs/org/joda/time/LocalTime.html"><code>LocalTime</code></a> - Immutable class representing a time without a date (no time zone)</li>
	<li><a href="apidocs/org/joda/time/LocalDateTime.html"><code>LocalDateTime</code></a> - Immutable class representing a local date and time (no time zone)</li>
	</ul>
	</p>

	<p>
	Each datetime class provides a variety of constructors.
	These include the <code>Object</code> constructor.
	This allows you to construct, for example, <code>DateTime</code> from
	the following objects:
	<ul>
	<li><code>Date</code> - a JDK instant</li>
	<li><code>Calendar</code> - a JDK calendar</li>
	<li><code>String</code> - in ISO8601 format</li>
	<li><code>Long</code> - in milliseconds</li>
	<li>any Joda-Time datetime class</li>
	</ul>
	This list is extensible. In other words Joda-Time sacrifices a little type-safety
	for extensibility. It does mean however, that converting from a JDK <code>Date</code>
	or <code>Calendar</code> to a Joda-Time class is easy - simply pass the JDK class
	into the constructor.
	</p>

	<p>
	Each datetime class provides simple easy methods
	to access the datetime <a href="field.html">fields</a>. For example, to access
	the month you can use:
	<source>
	DateTime dt = new DateTime();
	int month = dt.getMonthOfYear();
	</source>
	</p>

	<p>
	All the main datetime classes are immutable (like String) and cannot be changed
	after creation. However, simple methods have been provided to alter field values
	in a newly created object. For example, to set the year, or add 2 hours you can use:
	<source>
	DateTime dt = new DateTime();
	DateTime year2000 = dt.withYear(2000);
	DateTime twoHoursLater = dt.plusHours(2);
	</source>
	</p>

	<p>
	In addition to the basic get methods, each datetime class provides property
	methods for each field. These provide access to the full wealth of Joda-Time
	functionality. For example, to access details about a month or year:
	<source>
	DateTime dt = new DateTime();
	String monthName = dt.monthOfYear().getAsText();
	String frenchShortName = dt.monthOfYear().getAsShortText(Locale.FRENCH);
	boolean isLeapYear = dt.year().isLeap();
	DateTime rounded = dt.dayOfMonth().roundFloorCopy();
	</source>
	</p>
	</subsection>

	<subsection name="Calendar systems and time zones">
	<p>
	Joda-Time provides support for multiple calendar systems and the full range
	of time zones.
	The <a href="apidocs/org/joda/time/Chronology.html"><code>Chronology</code></a>
	and <a href="apidocs/org/joda/time/DateTimeZone.html"><code>DateTimeZone</code></a>
	classes provide this support.
	</p>
	<p>
	Joda-Time defaults to using the ISO calendar system (the calendar used by most
	of the business world) and the default time zone of your machine.
	These default values can be overridden whenever necessary.
	Please note that the ISO calendar system is historically inaccurate before 1583.
	</p>
	<p>
	Joda-Time uses a pluggable mechanism for calendars. (The JDK uses subclasses
	such as <code>GregorianCalendar</code>.)
	To obtain a Joda-Time calendar, use one of the factory methods on <code>Chronology</code>.
	<source>
	Chronology coptic = CopticChronology.getInstance();
	</source>
	</p>
	<p>
	Time zones are implemented as part of the chronology.
	To obtain a Joda-Time chronology in the Tokyo time zone, you can use.
	<source>
	DateTimeZone zone = DateTimeZone.forID("Asia/Tokyo");
	Chronology gregorianJuian = GJChronology.getInstance(zone);
	</source>
	</p>
	</subsection>

	<subsection name="Intervals and time periods">
	<p>
	Joda-Time provides support for intervals and time periods.
	</p>
	<p>
	An interval is represented by the
	<a href="apidocs/org/joda/time/Interval.html"><code>Interval</code></a> class.
	It holds a start and end datetime, and allows operations based around that
	range of time.
	</p>
	<p>
	A time period is represented by the
	<a href="apidocs/org/joda/time/Period.html"><code>Period</code></a> class.
	This holds a period such as 6 months, 3 days and 7 hours.
	You can create a <code>Period</code> directly, or derive it from an interval.
	</p>
	<p>
	A time duration is represented by the
	<a href="apidocs/org/joda/time/Duration.html"><code>Duration</code></a> class.
	This holds an exact duration in milliseconds.
	You can create a <code>Duration</code> directly, or derive it from an interval.
	</p>
	<p>
	Although a period and a duration may seem similar, they operate differently.
	For example, consider adding one day to a <code>DateTime</code> at the daylight
	savings cutover.
	<source>
	DateTime dt = new DateTime(2005, 3, 26, 12, 0, 0, 0);
	DateTime plusPeriod = dt.plus(Period.days(1));
	DateTime plusDuration = dt.plus(new Duration(24L60L60L*1000L));
	</source>
	Adding a period will add 23 hours in this case, not 24 because of the daylight
	savings change, thus the time of the result will still be midday.
	Adding a duration will add 24 hours no matter what, thus the time of the result
	will change to 13:00.
	</p>
	</subsection>
	</section>
	</body>
	</document>