Java Doc for DateMidnight.java in  » Development » Joda-Time » org » joda » time » Java Source Code / Java DocumentationJava Source Code and Java Documentation

It is important to emphasise that this class represents the time of midnight on any given day. Note that midnight is defined as 00:00, which is at the very start of a day.

This class does not represent a day, but the millisecond instant at midnight. If you need a class that represents the whole day, then an Interval or a LocalDate may be more suitable.

This class uses a Chronology internally. The Chronology determines how the millisecond instant value is converted into the date time fields. The default Chronology is ISOChronology which is the agreed international standard and compatable with the modern Gregorian calendar.

Each individual field can be queried in two ways:

• getDayOfMonth()
• dayOfMonth().get()

• numeric value
• text value
• short text value
• maximum/minimum values
• add/subtract
• set
• rounding

DateMidnight is thread-safe and immutable, provided that the Chronology is as well. All standard Chronology classes supplied are thread-safe and immutable.
author:
   Stephen Colebourne
since:
   1.0

If the object implies a chronology (such as GregorianCalendar does), then that chronology will be used.

This method creates a new DateMidnight using the midnight millisecond value and the new chronology.

If the addition is zero, then this is returned.

This method is typically used to add multiple copies of complex period instances.

If the specified time zone is null, the default zone is used.
Parameters:
  zone - the time zone, null means default zone

If the chronology is null, ISOChronology in the default time zone is used.
Parameters:
  chronology - the chronology, null means ISOChronology in default zone

If the specified time zone is null, the default zone is used.
Parameters:
  instant - the milliseconds from 1970-01-01T00:00:00Z
Parameters:
  zone - the time zone, null means default zone

If the chronology is null, ISOChronology in the default time zone is used.
Parameters:
  instant - the milliseconds from 1970-01-01T00:00:00Z
Parameters:
  chronology - the chronology, null means ISOChronology in default zone

If the object implies a chronology (such as GregorianCalendar does), then that chronology will be used. Otherwise, ISO default is used. Thus if a GregorianCalendar is passed in, the chronology used will be GJ, but if a Date is passed in the chronology will be ISO.

The recognised object types are defined in org.joda.time.convert.ConverterManager ConverterManager and include ReadableInstant, String, Calendar and Date. The String formats are described by ISODateTimeFormat.dateTimeParser .
Parameters:
  instant - the datetime object, null means now
throws:
  IllegalArgumentException - if the instant is invalid

If the object implies a chronology (such as GregorianCalendar does), then that chronology will be used, but with the time zone adjusted. Otherwise, ISO is used in the specified time zone. If the specified time zone is null, the default zone is used. Thus if a GregorianCalendar is passed in, the chronology used will be GJ, but if a Date is passed in the chronology will be ISO.

The recognised object types are defined in org.joda.time.convert.ConverterManager ConverterManager and include ReadableInstant, String, Calendar and Date. The String formats are described by ISODateTimeFormat.dateTimeParser .
Parameters:
  instant - the datetime object, null means now
Parameters:
  zone - the time zone, null means default time zone
throws:
  IllegalArgumentException - if the instant is invalid

If the chronology is null, ISO in the default time zone is used. Any chronology implied by the object (such as GregorianCalendar does) is ignored.

The recognised object types are defined in org.joda.time.convert.ConverterManager ConverterManager and include ReadableInstant, String, Calendar and Date. The String formats are described by ISODateTimeFormat.dateTimeParser .
Parameters:
  instant - the datetime object, null means now
Parameters:
  chronology - the chronology, null means ISOChronology in default zone
throws:
  IllegalArgumentException - if the instant is invalid

If the specified time zone is null, the default zone is used.
Parameters:
  year - the year
Parameters:
  monthOfYear - the month of the year
Parameters:
  dayOfMonth - the day of the month
Parameters:
  zone - the time zone, null means default time zone

If the chronology is null, ISOChronology in the default time zone is used.
Parameters:
  year - the year
Parameters:
  monthOfYear - the month of the year
Parameters:
  dayOfMonth - the day of the month
Parameters:
  chronology - the chronology, null means ISOChronology in default zone

If the amount is zero or null, then this is returned.
Parameters:
  duration - the duration, in millis, to reduce this instant by a copy of this datetime with the duration taken away
throws:
  ArithmeticException - if the new datetime exceeds the capacity of a long

If the amount is zero or null, then this is returned.
Parameters:
  duration - the duration to reduce this instant by a copy of this datetime with the duration taken away
throws:
  ArithmeticException - if the new datetime exceeds the capacity of a long

If the amount is zero or null, then this is returned.

This method is typically used to subtract complex period instances. Subtracting one field is best achieved using methods like DateMidnight.minusYears(int) .
Parameters:
  period - the period to reduce this instant by a copy of this datetime with the period taken away
throws:
  ArithmeticException - if the new datetime exceeds the capacity of a long

This datetime instance is immutable and unaffected by this method call.

The following three lines are identical in effect:

 DateMidnight subtracted = dt.minusDays(6);
 DateMidnight subtracted = dt.minus(Period.days(6));
 DateMidnight subtracted = dt.withFieldAdded(DurationFieldType.days(), -6);
 

This datetime instance is immutable and unaffected by this method call.

The following three lines are identical in effect:

 DateMidnight subtracted = dt.minusMonths(6);
 DateMidnight subtracted = dt.minus(Period.months(6));
 DateMidnight subtracted = dt.withFieldAdded(DurationFieldType.months(), -6);
 

This datetime instance is immutable and unaffected by this method call.

The following three lines are identical in effect:

 DateMidnight subtracted = dt.minusWeeks(6);
 DateMidnight subtracted = dt.minus(Period.weeks(6));
 DateMidnight subtracted = dt.withFieldAdded(DurationFieldType.weeks(), -6);
 

This datetime instance is immutable and unaffected by this method call.

The following three lines are identical in effect:

 DateTime subtracted = dt.minusYears(6);
 DateTime subtracted = dt.minus(Period.years(6));
 DateTime subtracted = dt.withFieldAdded(DurationFieldType.years(), -6);
 

If the amount is zero, then this is returned.
Parameters:
  duration - the duration, in millis, to add to this one a copy of this datetime with the duration added
throws:
  ArithmeticException - if the new datetime exceeds the capacity of a long

If the amount is zero or null, then this is returned.
Parameters:
  duration - the duration to add to this one, null means zero a copy of this datetime with the duration added
throws:
  ArithmeticException - if the new datetime exceeds the capacity of a long

If the amount is zero or null, then this is returned.

This method is typically used to add complex period instances. Adding one field is best achieved using methods like DateMidnight.plusYears(int) .
Parameters:
  period - the duration to add to this one, null means zero a copy of this datetime with the period added
throws:
  ArithmeticException - if the new datetime exceeds the capacity of a long

This datetime instance is immutable and unaffected by this method call.

The following three lines are identical in effect:

 DateMidnight added = dt.plusDays(6);
 DateMidnight added = dt.plus(Period.days(6));
 DateMidnight added = dt.withFieldAdded(DurationFieldType.days(), 6);
 

This datetime instance is immutable and unaffected by this method call.

The following three lines are identical in effect:

 DateMidnight added = dt.plusMonths(6);
 DateMidnight added = dt.plus(Period.months(6));
 DateMidnight added = dt.withFieldAdded(DurationFieldType.months(), 6);
 

This datetime instance is immutable and unaffected by this method call.

The following three lines are identical in effect:

 DateMidnight added = dt.plusWeeks(6);
 DateMidnight added = dt.plus(Period.weeks(6));
 DateMidnight added = dt.withFieldAdded(DurationFieldType.weeks(), 6);
 

This datetime instance is immutable and unaffected by this method call.

The following three lines are identical in effect:

 DateMidnight added = dt.plusYears(6);
 DateMidnight added = dt.plus(Period.years(6));
 DateMidnight added = dt.withFieldAdded(DurationFieldType.years(), 6);
 

The interval starts at midnight 00:00 and ends at 00:00 the following day, (which is not included in the interval, as intervals are half-open). an interval over the day

DateMidnight is immutable, so there are no set methods. Instead, this method returns a new instance with the value of century of era changed.
Parameters:
  centuryOfEra - the centurey of era to set a copy of this object with the field set
throws:
  IllegalArgumentException - if the value is invalid
since:
   1.3

This method creates a new DateMidnight using the midnight millisecond value and the new chronology. If the same or similar chronology is specified, but with a different time zone, the day may change. This occurs because the new DateMidnight rounds down the millisecond value to get to midnight, and the time zone change may result in a rounding down to a different day.

For example, changing time zone from London (+00:00) to Paris (+01:00) will retain the same day, but changing from Paris to London will change the day. (When its midnight in London its the same day in Paris, but when its midnight in Paris its still the previous day in London)

To avoid these unusual effects, use DateMidnight.withZoneRetainFields(DateTimeZone) to change time zones.
Parameters:
  newChronology - the new chronology a copy of this instant with a different chronology

DateMidnight is immutable, so there are no set methods. Instead, this method returns a new instance with the value of day of month changed.
Parameters:
  dayOfMonth - the day of month to set a copy of this object with the field set
throws:
  IllegalArgumentException - if the value is invalid
since:
   1.3

DateMidnight is immutable, so there are no set methods. Instead, this method returns a new instance with the value of day of week changed.
Parameters:
  dayOfWeek - the day of week to set a copy of this object with the field set
throws:
  IllegalArgumentException - if the value is invalid
since:
   1.3

DateMidnight is immutable, so there are no set methods. Instead, this method returns a new instance with the value of day of year changed.
Parameters:
  dayOfYear - the day of year to set a copy of this object with the field set
throws:
  IllegalArgumentException - if the value is invalid
since:
   1.3

If the addition is zero, then this is returned.
Parameters:
  durationToAdd - the duration to add to this one
Parameters:
  scalar - the amount of times to add, such as -1 to subtract once a copy of this datetime with the duration added
throws:
  ArithmeticException - if the new datetime exceeds the capacity of a long

If the addition is zero, then this is returned.
Parameters:
  durationToAdd - the duration to add to this one, null means zero
Parameters:
  scalar - the amount of times to add, such as -1 to subtract once a copy of this datetime with the duration added
throws:
  ArithmeticException - if the new datetime exceeds the capacity of a long

DateMidnight is immutable, so there are no set methods. Instead, this method returns a new instance with the value of era changed.
Parameters:
  era - the era to set a copy of this object with the field set
throws:
  IllegalArgumentException - if the value is invalid
since:
   1.3

For example, if the field type is dayOfMonth then the day of month field would be changed in the returned instance. If the field type is null, then this is returned.

These three lines are equivalent:

 DateTime updated = dt.withField(DateTimeFieldType.dayOfMonth(), 6);
 DateTime updated = dt.dayOfMonth().setCopy(6);
 DateTime updated = dt.property(DateTimeFieldType.dayOfMonth()).setCopy(6);
 

If the addition is zero or the field is null, then this is returned.

These three lines are equivalent:

 DateMidnight added = dt.withFieldAdded(DateTimeFieldType.year(), 6);
 DateMidnight added = dt.plusYears(6);
 DateMidnight added = dt.year().addToCopy(6);
 

For example, if the partial is a LocalDate then the date fields would be changed in the returned instance. If the partial is null, then this is returned.
Parameters:
  partial - the partial set of fields to apply to this datetime, null ignored a copy of this datetime with a different set of fields
throws:
  IllegalArgumentException - if any value is invalid

Only the millis will change, the chronology and time zone are kept. The returned object will be either be a new instance or this.
Parameters:
  newMillis - the new millis, from 1970-01-01T00:00:00Z a copy of this instant with different millis

DateMidnight is immutable, so there are no set methods. Instead, this method returns a new instance with the value of month of year changed.
Parameters:
  monthOfYear - the month of year to set a copy of this object with the field set
throws:
  IllegalArgumentException - if the value is invalid
since:
   1.3

If the addition is zero, then this is returned.

This method is typically used to add multiple copies of complex period instances. Adding one field is best achieved using methods like DateMidnight.withFieldAdded(DurationFieldType,int) or DateMidnight.plusYears(int) .
Parameters:
  period - the period to add to this one, null means zero
Parameters:
  scalar - the amount of times to add, such as -1 to subtract once a copy of this datetime with the period added
throws:
  ArithmeticException - if the new datetime exceeds the capacity of a long

DateMidnight is immutable, so there are no set methods. Instead, this method returns a new instance with the value of week of weekyear changed.
Parameters:
  weekOfWeekyear - the week of weekyear to set a copy of this object with the field set
throws:
  IllegalArgumentException - if the value is invalid
since:
   1.3

DateMidnight is immutable, so there are no set methods. Instead, this method returns a new instance with the value of weekyear changed.
Parameters:
  weekyear - the weekyear to set a copy of this object with the field set
throws:
  IllegalArgumentException - if the value is invalid
since:
   1.3

DateMidnight is immutable, so there are no set methods. Instead, this method returns a new instance with the value of year changed.
Parameters:
  year - the year to set a copy of this object with the field set
throws:
  IllegalArgumentException - if the value is invalid
since:
   1.3

DateMidnight is immutable, so there are no set methods. Instead, this method returns a new instance with the value of year of century changed.
Parameters:
  yearOfCentury - the year of century to set a copy of this object with the field set
throws:
  IllegalArgumentException - if the value is invalid
since:
   1.3

DateMidnight is immutable, so there are no set methods. Instead, this method returns a new instance with the value of year of era changed.
Parameters:
  yearOfEra - the year of era to set a copy of this object with the field set
throws:
  IllegalArgumentException - if the value is invalid
since:
   1.3