public final class ZonedDateTime extends Object implements DateTime, DateTime.WithAdjuster, Comparable<ZonedDateTime>, Serializable
2007-12-03T10:15:30+01:00 Europe/Paris
.
ZonedDateTime
is an immutable representation of a date-time with a time-zone.
This class stores all date and time fields, to a precision of nanoseconds,
as well as a time-zone and zone offset. For example, the value
"2nd October 2007 at 13:45.30.123456789 +02:00 in the Europe/Paris time-zone"
can be stored in a ZonedDateTime
.
The purpose of storing the time-zone is to distinguish the ambiguous case where the local time-line overlaps, typically as a result of the end of daylight time. Information about the local-time can be obtained using methods on the time-zone.
This class provides control over what happens at these cutover points
(typically a gap in spring and an overlap in autumn). The ZoneResolver
interface and implementations in ZoneResolvers
provide strategies for
handling these cases. The methods withEarlierOffsetAtOverlap()
and
withLaterOffsetAtOverlap()
provide further control for overlaps.
DateTime.MinusAdjuster, DateTime.PlusAdjuster, DateTime.WithAdjuster
Modifier and Type | Method and Description |
---|---|
int |
compareTo(ZonedDateTime other)
Compares this
ZonedDateTime to another date-time based on the UTC
equivalent date-times then time-zone unique key. |
DateTime |
doAdjustment(DateTime calendrical)
Implementation of the strategy to make an adjustment to the specified date-time object.
|
boolean |
equalInstant(ZonedDateTime other)
Checks if the instant of this date-time is equal to that of the specified date-time.
|
boolean |
equals(Object obj)
Checks if this date-time is equal to another date-time.
|
<R> R |
extract(Class<R> type)
Extracts date-time information in a generic way.
|
static ZonedDateTime |
from(DateTimeAccessor calendrical)
Obtains an instance of
ZonedDateTime from a calendrical. |
int |
get(DateTimeField field)
Gets the value of the specified date-time field as an
int . |
ZoneRules |
getApplicableRules()
Calculates the zone rules applicable for this date-time.
|
int |
getDayOfMonth()
Gets the day-of-month field.
|
DayOfWeek |
getDayOfWeek()
Gets the day-of-week field, which is an enum
DayOfWeek . |
int |
getDayOfYear()
Gets the day-of-year field.
|
int |
getHour()
Gets the hour-of-day field.
|
long |
getLong(DateTimeField field)
Gets the value of the specified date-time field as a
Long . |
int |
getMinute()
Gets the minute-of-hour field.
|
Month |
getMonth()
Gets the month-of-year field using the
Month enum. |
int |
getMonthValue()
Gets the month-of-year field from 1 to 12.
|
int |
getNano()
Gets the nano-of-second field.
|
ZoneOffset |
getOffset()
Gets the zone offset, such as '+01:00'.
|
int |
getSecond()
Gets the second-of-minute field.
|
int |
getYear()
Gets the year field.
|
ZoneId |
getZone()
Gets the time-zone, such as 'Europe/Paris'.
|
int |
hashCode()
A hash code for this date-time.
|
boolean |
isAfter(ZonedDateTime other)
Checks if the instant of this date-time is after that of the specified date-time.
|
boolean |
isBefore(ZonedDateTime other)
Checks if the instant of this date-time is before that of the specified date-time.
|
ZonedDateTime |
minus(DateTime.MinusAdjuster adjuster)
Returns a copy of this date-time with the specified period subtracted.
|
ZonedDateTime |
minus(long periodAmount,
PeriodUnit unit)
Returns a copy of this date-time with the specified period subtracted.
|
ZonedDateTime |
minusDays(long days)
Returns a copy of this
ZonedDateTime with the specified period in days subtracted. |
ZonedDateTime |
minusDuration(int hours,
int minutes,
int seconds,
long nanos)
Returns a copy of this
ZonedDateTime with the specified duration subtracted. |
ZonedDateTime |
minusHours(long hours)
Returns a copy of this
ZonedDateTime with the specified period in hours subtracted. |
ZonedDateTime |
minusMinutes(long minutes)
Returns a copy of this
ZonedDateTime with the specified period in minutes subtracted. |
ZonedDateTime |
minusMonths(long months)
Returns a copy of this
ZonedDateTime with the specified period in months subtracted. |
ZonedDateTime |
minusNanos(long nanos)
Returns a copy of this
ZonedDateTime with the specified period in nanoseconds subtracted. |
ZonedDateTime |
minusSeconds(long seconds)
Returns a copy of this
ZonedDateTime with the specified period in seconds subtracted. |
ZonedDateTime |
minusWeeks(long weeks)
Returns a copy of this
ZonedDateTime with the specified period in weeks subtracted. |
ZonedDateTime |
minusYears(long years)
Returns a copy of this
ZonedDateTime with the specified period in years subtracted. |
static ZonedDateTime |
now()
Obtains the current date-time from the system clock in the default time-zone.
|
static ZonedDateTime |
now(Clock clock)
Obtains the current date-time from the specified clock.
|
static ZonedDateTime |
of(int year,
int month,
int dayOfMonth,
int hour,
int minute,
int second,
int nanoOfSecond,
ZoneId zone)
Obtains an instance of
ZonedDateTime from year, month,
day, hour, minute, second, nanosecond and time-zone
where the date-time must be valid for the time-zone. |
static ZonedDateTime |
of(int year,
int month,
int dayOfMonth,
int hour,
int minute,
int second,
int nanoOfSecond,
ZoneId zone,
ZoneResolver resolver)
Obtains an instance of
ZonedDateTime from year, month,
day, hour, minute, second, nanosecond and time-zone
providing a resolver to handle an invalid date-time. |
static ZonedDateTime |
of(int year,
Month month,
int dayOfMonth,
int hour,
int minute,
int second,
int nanoOfSecond,
ZoneId zone)
Obtains an instance of
ZonedDateTime from year, month,
day, hour, minute, second, nanosecond and time-zone
where the date-time must be valid for the time-zone. |
static ZonedDateTime |
of(int year,
Month month,
int dayOfMonth,
int hour,
int minute,
int second,
int nanoOfSecond,
ZoneId zone,
ZoneResolver resolver)
Obtains an instance of
ZonedDateTime from year, month,
day, hour, minute, second, nanosecond and time-zone
providing a resolver to handle an invalid date-time. |
static ZonedDateTime |
of(LocalDate date,
LocalTime time,
ZoneId zone)
Obtains an instance of
ZonedDateTime from a local date and time
where the date-time must be valid for the time-zone. |
static ZonedDateTime |
of(LocalDate date,
LocalTime time,
ZoneId zone,
ZoneResolver resolver)
Obtains an instance of
ZonedDateTime from a local date and time
providing a resolver to handle an invalid date-time. |
static ZonedDateTime |
of(LocalDateTime dateTime,
ZoneId zone)
Obtains an instance of
ZonedDateTime from a local date-time
where the date-time must be valid for the time-zone. |
static ZonedDateTime |
of(LocalDateTime dateTime,
ZoneId zone,
ZoneResolver resolver)
Obtains an instance of
ZonedDateTime from a local date-time
providing a resolver to handle an invalid date-time. |
static ZonedDateTime |
of(OffsetDateTime dateTime,
ZoneId zone)
Obtains an instance of
ZonedDateTime from an OffsetDateTime
ensuring that the offset provided is valid for the time-zone. |
static ZonedDateTime |
ofEpochSecond(long epochSecond,
ZoneId zone)
Obtains an instance of
ZonedDateTime using seconds from the
epoch of 1970-01-01T00:00:00Z. |
static ZonedDateTime |
ofInstant(Instant instant,
ZoneId zone)
Obtains an instance of
ZonedDateTime from an Instant . |
static ZonedDateTime |
ofInstant(OffsetDateTime instantDateTime,
ZoneId zone)
Obtains an instance of
ZonedDateTime from an OffsetDateTime . |
static ZonedDateTime |
ofInstantUTC(Instant instant)
Obtains an instance of
ZonedDateTime from an Instant
using the UTC zone. |
static ZonedDateTime |
parse(CharSequence text)
Obtains an instance of
ZonedDateTime from a text string such as
2007-12-03T10:15:30+01:00[Europe/Paris] . |
static ZonedDateTime |
parse(CharSequence text,
CalendricalFormatter formatter)
Obtains an instance of
ZonedDateTime from a text string using a specific formatter. |
long |
periodUntil(DateTime endDateTime,
PeriodUnit unit)
Calculates the period from this date-time until the given date-time in the specified unit.
|
ZonedDateTime |
plus(DateTime.PlusAdjuster adjuster)
Returns a copy of this date-time with the specified period added.
|
ZonedDateTime |
plus(long periodAmount,
PeriodUnit unit)
Returns a copy of this date-time with the specified period added.
|
ZonedDateTime |
plusDays(long days)
Returns a copy of this
ZonedDateTime with the specified period in days added. |
ZonedDateTime |
plusDuration(int hours,
int minutes,
int seconds,
long nanos)
Returns a copy of this
ZonedDateTime with the specified duration added. |
ZonedDateTime |
plusHours(long hours)
Returns a copy of this
ZonedDateTime with the specified period in hours added. |
ZonedDateTime |
plusMinutes(long minutes)
Returns a copy of this
ZonedDateTime with the specified period in minutes added. |
ZonedDateTime |
plusMonths(long months)
Returns a copy of this
ZonedDateTime with the specified period in months added. |
ZonedDateTime |
plusNanos(long nanos)
Returns a copy of this
ZonedDateTime with the specified period in nanoseconds added. |
ZonedDateTime |
plusSeconds(long seconds)
Returns a copy of this
ZonedDateTime with the specified period in seconds added. |
ZonedDateTime |
plusWeeks(long weeks)
Returns a copy of this
ZonedDateTime with the specified period in weeks added. |
ZonedDateTime |
plusYears(long years)
Returns a copy of this
ZonedDateTime with the specified period in years added. |
DateTimeValueRange |
range(DateTimeField field)
Gets the range of valid values for the specified date-time field.
|
long |
toEpochSecond()
Converts this
ZonedDateTime to the number of seconds from the epoch
of 1970-01-01T00:00:00Z. |
Instant |
toInstant()
Converts this
ZonedDateTime to an Instant . |
LocalDate |
toLocalDate()
Converts this
ZonedDateTime to a LocalDate . |
LocalDateTime |
toLocalDateTime()
Converts this
ZonedDateTime to a LocalDateTime . |
LocalTime |
toLocalTime()
Converts this
ZonedDateTime to a LocalTime . |
OffsetDate |
toOffsetDate()
Converts this
ZonedDateTime to a OffsetDate . |
OffsetDateTime |
toOffsetDateTime()
Converts this
ZonedDateTime to a OffsetDateTime . |
OffsetTime |
toOffsetTime()
Converts this
ZonedDateTime to a OffsetTime . |
String |
toString()
Outputs this date-time as a
String , such as
2007-12-03T10:15:30+01:00[Europe/Paris] . |
String |
toString(CalendricalFormatter formatter)
Outputs this date-time as a
String using the formatter. |
ZonedDateTime |
with(DateTime.WithAdjuster adjuster)
Returns an adjusted date-time based on this date-time.
|
ZonedDateTime |
with(DateTime.WithAdjuster adjuster,
ZoneResolver resolver)
Returns an adjusted date-time based on this date-time
providing a resolver for invalid date-times.
|
ZonedDateTime |
with(DateTimeField field,
long newValue)
Returns a copy of this date-time with the specified field altered.
|
ZonedDateTime |
withDate(int year,
int month,
int dayOfMonth)
Returns a copy of this
ZonedDateTime with the date values altered. |
ZonedDateTime |
withDateTime(LocalDateTime dateTime)
Returns a copy of this
ZonedDateTime with the local date-time altered. |
ZonedDateTime |
withDateTime(LocalDateTime dateTime,
ZoneResolver resolver)
Returns a copy of this
ZonedDateTime with the local date-time altered,
providing a resolver for invalid date-times. |
ZonedDateTime |
withDayOfMonth(int dayOfMonth)
Returns a copy of this
ZonedDateTime with the day-of-month value altered. |
ZonedDateTime |
withDayOfYear(int dayOfYear)
Returns a copy of this
ZonedDateTime with the day-of-year altered. |
ZonedDateTime |
withEarlierOffsetAtOverlap()
Returns a copy of this ZonedDateTime changing the zone offset to the
earlier of the two valid offsets at a local time-line overlap.
|
ZonedDateTime |
withHour(int hour)
Returns a copy of this
ZonedDateTime with the hour-of-day value altered. |
ZonedDateTime |
withLaterOffsetAtOverlap()
Returns a copy of this ZonedDateTime changing the zone offset to the
later of the two valid offsets at a local time-line overlap.
|
ZonedDateTime |
withMinute(int minute)
Returns a copy of this
ZonedDateTime with the minute-of-hour value altered. |
ZonedDateTime |
withMonth(int month)
Returns a copy of this
ZonedDateTime with the month-of-year value altered. |
ZonedDateTime |
withNano(int nanoOfSecond)
Returns a copy of this
ZonedDateTime with the nano-of-second value altered. |
ZonedDateTime |
withSecond(int second)
Returns a copy of this
ZonedDateTime with the second-of-minute value altered. |
ZonedDateTime |
withTime(int hour,
int minute)
Returns a copy of this
ZonedDateTime with the time values altered. |
ZonedDateTime |
withTime(int hour,
int minute,
int second)
Returns a copy of this
ZonedDateTime with the time values altered. |
ZonedDateTime |
withTime(int hour,
int minute,
int second,
int nanoOfSecond)
Returns a copy of this
ZonedDateTime with the time values altered. |
ZonedDateTime |
withYear(int year)
Returns a copy of this
ZonedDateTime with the year value altered. |
ZonedDateTime |
withZoneSameInstant(ZoneId zone)
Returns a copy of this ZonedDateTime with a different time-zone,
retaining the instant.
|
ZonedDateTime |
withZoneSameLocal(ZoneId zone)
Returns a copy of this ZonedDateTime with a different time-zone,
retaining the local date-time if possible.
|
ZonedDateTime |
withZoneSameLocal(ZoneId zone,
ZoneResolver resolver)
Returns a copy of this ZonedDateTime with a different time-zone,
retaining the local date-time if possible.
|
public static ZonedDateTime now()
This will query the system clock
in the default
time-zone to obtain the current date-time.
The zone and offset will be set based on the time-zone in the clock.
Using this method will prevent the ability to use an alternate clock for testing because the clock is hard-coded.
public static ZonedDateTime now(Clock clock)
This will query the specified clock to obtain the current time. The zone and offset will be set based on the time-zone in the clock.
Using this method allows the use of an alternate clock for testing.
The alternate clock may be introduced using dependency injection
.
clock
- the clock to use, not nullpublic static ZonedDateTime of(int year, Month month, int dayOfMonth, int hour, int minute, int second, int nanoOfSecond, ZoneId zone)
ZonedDateTime
from year, month,
day, hour, minute, second, nanosecond and time-zone
where the date-time must be valid for the time-zone.
The day must be valid for the year and month, otherwise an exception will be thrown.
The local date-time must be valid for the time-zone. If the time is invalid for the zone, due to either being a gap or an overlap, then an exception will be thrown.
year
- the year to represent, from MIN_YEAR to MAX_YEARmonth
- the month-of-year to represent, not nulldayOfMonth
- the day-of-month to represent, from 1 to 31hour
- the hour-of-day to represent, from 0 to 23minute
- the minute-of-hour to represent, from 0 to 59second
- the second-of-minute to represent, from 0 to 59nanoOfSecond
- the nano-of-second to represent, from 0 to 999,999,999zone
- the time-zone, not nullDateTimeException
- if the value of any field is out of rangeDateTimeException
- if the day-of-month is invalid for the month-yearDateTimeException
- if the local date-time is invalid for the time-zonepublic static ZonedDateTime of(int year, Month month, int dayOfMonth, int hour, int minute, int second, int nanoOfSecond, ZoneId zone, ZoneResolver resolver)
ZonedDateTime
from year, month,
day, hour, minute, second, nanosecond and time-zone
providing a resolver to handle an invalid date-time.
The day must be valid for the year and month, otherwise an exception will be thrown.
The local date-time must be valid for the time-zone.
If the time is invalid for the zone, due to either being a gap or an overlap,
then the resolver will determine what action to take.
See ZoneResolvers
for common resolver implementations.
year
- the year to represent, from MIN_YEAR to MAX_YEARmonth
- the month-of-year to represent, not nulldayOfMonth
- the day-of-month to represent, from 1 to 31hour
- the hour-of-day to represent, from 0 to 23minute
- the minute-of-hour to represent, from 0 to 59second
- the second-of-minute to represent, from 0 to 59nanoOfSecond
- the nano-of-second to represent, from 0 to 999,999,999zone
- the time-zone, not nullresolver
- the resolver from local date-time to zoned, not nullDateTimeException
- if the value of any field is out of rangeDateTimeException
- if the day-of-month is invalid for the month-yearDateTimeException
- if the resolver cannot resolve an invalid local date-timepublic static ZonedDateTime of(int year, int month, int dayOfMonth, int hour, int minute, int second, int nanoOfSecond, ZoneId zone)
ZonedDateTime
from year, month,
day, hour, minute, second, nanosecond and time-zone
where the date-time must be valid for the time-zone.
The day must be valid for the year and month, otherwise an exception will be thrown.
The local date-time must be valid for the time-zone. If the time is invalid for the zone, due to either being a gap or an overlap, then an exception will be thrown.
year
- the year to represent, from MIN_YEAR to MAX_YEARmonth
- the month-of-year to represent, from 1 (January) to 12 (December)dayOfMonth
- the day-of-month to represent, from 1 to 31hour
- the hour-of-day to represent, from 0 to 23minute
- the minute-of-hour to represent, from 0 to 59second
- the second-of-minute to represent, from 0 to 59nanoOfSecond
- the nano-of-second to represent, from 0 to 999,999,999zone
- the time-zone, not nullDateTimeException
- if the value of any field is out of rangeDateTimeException
- if the day-of-month is invalid for the month-yearDateTimeException
- if the local date-time is invalid for the time-zonepublic static ZonedDateTime of(int year, int month, int dayOfMonth, int hour, int minute, int second, int nanoOfSecond, ZoneId zone, ZoneResolver resolver)
ZonedDateTime
from year, month,
day, hour, minute, second, nanosecond and time-zone
providing a resolver to handle an invalid date-time.
The day must be valid for the year and month, otherwise an exception will be thrown.
The local date-time must be valid for the time-zone.
If the time is invalid for the zone, due to either being a gap or an overlap,
then the resolver will determine what action to take.
See ZoneResolvers
for common resolver implementations.
year
- the year to represent, from MIN_YEAR to MAX_YEARmonth
- the month-of-year to represent, from 1 (January) to 12 (December)dayOfMonth
- the day-of-month to represent, from 1 to 31hour
- the hour-of-day to represent, from 0 to 23minute
- the minute-of-hour to represent, from 0 to 59second
- the second-of-minute to represent, from 0 to 59nanoOfSecond
- the nano-of-second to represent, from 0 to 999,999,999zone
- the time-zone, not nullresolver
- the resolver from local date-time to zoned, not nullDateTimeException
- if the value of any field is out of rangeDateTimeException
- if the day-of-month is invalid for the month-yearDateTimeException
- if the resolver cannot resolve an invalid local date-timepublic static ZonedDateTime of(LocalDate date, LocalTime time, ZoneId zone)
ZonedDateTime
from a local date and time
where the date-time must be valid for the time-zone.
This factory creates a ZonedDateTime
from a date, time and time-zone.
If the time is invalid for the zone, due to either being a gap or an overlap,
then an exception will be thrown.
date
- the local date, not nulltime
- the local time, not nullzone
- the time-zone, not nullDateTimeException
- if the local date-time is invalid for the time-zonepublic static ZonedDateTime of(LocalDate date, LocalTime time, ZoneId zone, ZoneResolver resolver)
ZonedDateTime
from a local date and time
providing a resolver to handle an invalid date-time.
This factory creates a ZonedDateTime
from a date, time and time-zone.
If the time is invalid for the zone, due to either being a gap or an overlap,
then the resolver will determine what action to take.
See ZoneResolvers
for common resolver implementations.
date
- the local date, not nulltime
- the local time, not nullzone
- the time-zone, not nullresolver
- the resolver from local date-time to zoned, not nullDateTimeException
- if the resolver cannot resolve an invalid local date-timepublic static ZonedDateTime of(LocalDateTime dateTime, ZoneId zone)
ZonedDateTime
from a local date-time
where the date-time must be valid for the time-zone.
This factory creates a ZonedDateTime
from a date-time and time-zone.
If the time is invalid for the zone, due to either being a gap or an overlap,
then an exception will be thrown.
dateTime
- the local date-time, not nullzone
- the time-zone, not nullDateTimeException
- if the local date-time is invalid for the time-zonepublic static ZonedDateTime of(LocalDateTime dateTime, ZoneId zone, ZoneResolver resolver)
ZonedDateTime
from a local date-time
providing a resolver to handle an invalid date-time.
This factory creates a ZonedDateTime
from a date-time and time-zone.
If the time is invalid for the zone, due to either being a gap or an overlap,
then the resolver will determine what action to take.
See ZoneResolvers
for common resolver implementations.
dateTime
- the local date-time, not nullzone
- the time-zone, not nullresolver
- the resolver from local date-time to zoned, not nullDateTimeException
- if the resolver cannot resolve an invalid local date-timepublic static ZonedDateTime of(OffsetDateTime dateTime, ZoneId zone)
ZonedDateTime
from an OffsetDateTime
ensuring that the offset provided is valid for the time-zone.
This factory creates a ZonedDateTime
from an offset date-time and time-zone.
If the date-time is invalid for the zone due to a time-line gap then an exception is thrown.
Otherwise, the offset is checked against the zone to ensure it is valid.
An alternative to this method is ofInstant(javax.time.Instant, javax.time.ZoneId)
. This method will retain
the date and time and throw an exception if the offset is invalid.
The ofInstant
method will change the date and time if necessary
to retain the same instant.
dateTime
- the offset date-time to use, not nullzone
- the time-zone, not nullDateTimeException
- if no rules can be found for the zoneDateTimeException
- if the date-time is invalid due to a gap in the local time-lineDateTimeException
- if the offset is invalid for the time-zone at the date-timepublic static ZonedDateTime ofInstantUTC(Instant instant)
ZonedDateTime
from an Instant
using the UTC zone.
The resulting date-time represents exactly the same instant on the time-line.
Calling toInstant()
will return an instant equal to the one used here.
If the instant represents a point on the time-line outside the supported year range then an exception will be thrown.
instant
- the instant to create the date-time from, not nullDateTimeException
- if the result exceeds the supported rangepublic static ZonedDateTime ofInstant(Instant instant, ZoneId zone)
ZonedDateTime
from an Instant
.
The resulting date-time represents exactly the same instant on the time-line.
Calling toInstant()
will return an instant equal to the one used here.
If the instant represents a point on the time-line outside the supported year range then an exception will be thrown.
instant
- the instant to create the date-time from, not nullzone
- the time-zone to use, not nullDateTimeException
- if the result exceeds the supported rangepublic static ZonedDateTime ofInstant(OffsetDateTime instantDateTime, ZoneId zone)
ZonedDateTime
from an OffsetDateTime
.
The resulting date-time represents exactly the same instant on the time-line. As such, the resulting local date-time may be different from the input.
If the instant represents a point on the time-line outside the supported year range then an exception will be thrown.
instantDateTime
- the instant to create the date-time from, not nullzone
- the time-zone to use, not nullDateTimeException
- if the result exceeds the supported rangepublic static ZonedDateTime ofEpochSecond(long epochSecond, ZoneId zone)
ZonedDateTime
using seconds from the
epoch of 1970-01-01T00:00:00Z.
The nanosecond field is set to zero.
epochSecond
- the number of seconds from the epoch of 1970-01-01T00:00:00Zzone
- the time-zone, not nullDateTimeException
- if the result exceeds the supported rangepublic static ZonedDateTime from(DateTimeAccessor calendrical)
ZonedDateTime
from a calendrical.
A calendrical represents some form of date and time information.
This factory converts the arbitrary calendrical to an instance of ZonedDateTime
.
calendrical
- the calendrical to convert, not nullDateTimeException
- if unable to convert to an ZonedDateTime
public static ZonedDateTime parse(CharSequence text)
ZonedDateTime
from a text string such as
2007-12-03T10:15:30+01:00[Europe/Paris]
.
The string must represent a valid date-time and is parsed using
DateTimeFormatters.isoZonedDateTime()
.
text
- the text to parse such as "2007-12-03T10:15:30+01:00[Europe/Paris]", not nullDateTimeParseException
- if the text cannot be parsedpublic static ZonedDateTime parse(CharSequence text, CalendricalFormatter formatter)
ZonedDateTime
from a text string using a specific formatter.
The text is parsed using the formatter, returning a date-time.
text
- the text to parse, not nullformatter
- the formatter to use, not nullDateTimeParseException
- if the text cannot be parsedpublic DateTimeValueRange range(DateTimeField field)
DateTimeAccessor
All fields can be expressed as a long
integer.
This method returns an object that describes the valid range for that value.
Note that the result only describes the minimum and maximum valid values and it is important not to read too much into them. For example, there could be values within the range that are invalid for the field.
This method will return a result whether or not the implementation supports the field.
LocalDateTimeField
before
delegating on to the doRange method
on the specified field.range
in interface DateTimeAccessor
field
- the field to get, not nullpublic int get(DateTimeField field)
DateTimeAccessor
int
.
This queries the date-time for the value for the specified field. The returned value will always be within the valid range of values for the field. If the date-time cannot return the value an exception will be thrown.
LocalDateTimeField
before
delegating on to the doGet method
on the specified field.get
in interface DateTimeAccessor
field
- the field to get, not nullpublic long getLong(DateTimeField field)
DateTimeAccessor
Long
.
This queries the date-time for the value for the specified field. The returned value may be outside the valid range of values for the field. If the date-time cannot return the value, it will throw an exception.
LocalDateTimeField
before
delegating on to the doGet method
on the specified field.getLong
in interface DateTimeAccessor
field
- the field to get, not nullpublic ZoneOffset getOffset()
public ZonedDateTime withEarlierOffsetAtOverlap()
This method only has any effect when the local time-line overlaps, such as at an autumn daylight savings cutover. In this scenario, there are two valid offsets for the local date-time. Calling this method will return a zoned date-time with the earlier of the two selected.
If this method is called when it is not an overlap, this
is returned.
This instance is immutable and unaffected by this method call.
ZonedDateTime
based on this date-time with the earlier offset, not nullDateTimeException
- if no rules can be found for the zoneDateTimeException
- if no rules are valid for this date-timepublic ZonedDateTime withLaterOffsetAtOverlap()
This method only has any effect when the local time-line overlaps, such as at an autumn daylight savings cutover. In this scenario, there are two valid offsets for the local date-time. Calling this method will return a zoned date-time with the later of the two selected.
If this method is called when it is not an overlap, this
is returned.
This instance is immutable and unaffected by this method call.
ZonedDateTime
based on this date-time with the later offset, not nullDateTimeException
- if no rules can be found for the zoneDateTimeException
- if no rules are valid for this date-timepublic ZoneId getZone()
This returns the stored time-zone id used to determine the time-zone rules.
public ZonedDateTime withZoneSameLocal(ZoneId zone)
This method changes the time-zone and retains the local date-time.
The local date-time is only changed if it is invalid for the new zone.
In that case, the retain offset
resolver is used.
To change the zone and adjust the local date-time,
use withZoneSameInstant(ZoneId)
.
This instance is immutable and unaffected by this method call.
zone
- the time-zone to change to, not nullZonedDateTime
based on this date-time with the requested zone, not nullpublic ZonedDateTime withZoneSameLocal(ZoneId zone, ZoneResolver resolver)
This method changes the time-zone and retains the local date-time. The local date-time is only changed if it is invalid for the new zone. In that case, the specified resolver is used.
To change the zone and adjust the local date-time,
use withZoneSameInstant(ZoneId)
.
This instance is immutable and unaffected by this method call.
zone
- the time-zone to change to, not nullresolver
- the resolver to use, not nullZonedDateTime
based on this date-time with the requested zone, not nullpublic ZonedDateTime withZoneSameInstant(ZoneId zone)
This method changes the time-zone and retains the instant. This normally results in a change to the local date-time.
This method is based on retaining the same instant, thus gaps and overlaps in the local time-line have no effect on the result.
To change the offset while keeping the local time,
use withZoneSameLocal(ZoneId)
.
zone
- the time-zone to change to, not nullZonedDateTime
based on this date-time with the requested zone, not nullDateTimeException
- if the result exceeds the supported date rangepublic ZoneRules getApplicableRules()
The rules provide the information on how the zone offset changes over time.
This usually includes historical and future information.
The rules are determined using ZoneId.getRulesValidFor(OffsetDateTime)
which finds the best matching set of rules for this date-time.
If a new version of the time-zone rules is registered then the result
of this method may change.
If this instance is created on one JVM and passed by serialization to another JVM it is possible for the time-zone id to be invalid. If this happens, this method will throw an exception.
DateTimeException
- if no rules can be found for the zoneDateTimeException
- if no rules are valid for this date-timepublic int getYear()
This method returns the primitive int
value for the year.
public int getMonthValue()
This method returns the month as an int
from 1 to 12.
Application code is frequently clearer if the enum Month
is used by calling getMonth()
.
getMonth()
public Month getMonth()
Month
enum.
This method returns the enum Month
for the month.
This avoids confusion as to what int
values mean.
If you need access to the primitive int
value then the enum
provides the int value
.
getMonthValue()
public int getDayOfMonth()
This method returns the primitive int
value for the day-of-month.
public int getDayOfYear()
This method returns the primitive int
value for the day-of-year.
public DayOfWeek getDayOfWeek()
DayOfWeek
.
This method returns the enum DayOfWeek
for the day-of-week.
This avoids confusion as to what int
values mean.
If you need access to the primitive int
value then the enum
provides the int value
.
Additional information can be obtained from the DayOfWeek
.
This includes textual names of the values.
public int getHour()
public int getMinute()
public int getSecond()
public int getNano()
public ZonedDateTime withDateTime(LocalDateTime dateTime)
ZonedDateTime
with the local date-time altered.
This method returns an object with the same ZoneId
and the
specified LocalDateTime
.
If the adjusted date results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
dateTime
- the local date-time to change to, not nullZonedDateTime
based on this time with the requested date-time, not nullpublic ZonedDateTime withDateTime(LocalDateTime dateTime, ZoneResolver resolver)
ZonedDateTime
with the local date-time altered,
providing a resolver for invalid date-times.
This method returns an object with the same ZoneId
and the
specified LocalDateTime
.
If the adjusted date results in a date-time that is invalid, then the specified resolver is used.
dateTime
- the local date-time to change to, not nullresolver
- the resolver to use, not nullZonedDateTime
based on this time with the requested date-time, not nullpublic ZonedDateTime with(DateTime.WithAdjuster adjuster)
This adjusts the date-time according to the rules of the specified adjuster.
A simple adjuster might simply set the one of the fields, such as the year field.
A more complex adjuster might set the date-time to the last day of the month.
A selection of common adjustments is provided in DateTimeAdjusters
.
These include finding the "last day of the month" and "next Wednesday".
The adjuster is responsible for handling special cases, such as the varying
lengths of month and leap years.
In addition, all principal classes implement the DateTime.WithAdjuster
interface,
including this one. For example, LocalDate
implements the adjuster interface.
As such, this code will compile and run:
dateTime.with(date);
If the adjusted date results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
with
in interface DateTime
adjuster
- the adjuster to use, not nullZonedDateTime
based on this date-time with the adjustment made, not nullDateTimeException
- if the adjustment cannot be madepublic ZonedDateTime with(DateTime.WithAdjuster adjuster, ZoneResolver resolver)
This adjusts the date-time according to the rules of the specified adjuster.
A simple adjuster might simply set the one of the fields, such as the year field.
A more complex adjuster might set the date-time to the last day of the month.
A selection of common adjustments is provided in DateTimeAdjusters
.
These include finding the "last day of the month" and "next Wednesday".
The adjuster is responsible for handling special cases, such as the varying
lengths of month and leap years.
In addition, all principal classes implement the DateTime.WithAdjuster
interface,
including this one. For example, LocalDate
implements the adjuster interface.
As such, this code will compile and run:
dateTime.with(date);
If the adjusted date results in a date-time that is invalid, then the specified resolver is used.
This instance is immutable and unaffected by this method call.
adjuster
- the adjuster to use, not nullresolver
- the resolver to use, not nullZonedDateTime
based on this date-time with the adjustment made, not nullDateTimeException
- if the adjustment cannot be madepublic ZonedDateTime with(DateTimeField field, long newValue)
This method returns a new date-time based on this date-time with a new value for the specified field. This can be used to change any field, for example to set the year, month of day-of-month. The offset is not part of the calculation and will be unchanged in the result.
In some cases, changing the specified field can cause the resulting date-time to become invalid, such as changing the month from January to February would make the day-of-month 31 invalid. In cases like this, the field is responsible for resolving the date. Typically it will choose the previous valid date, which would be the last valid day of February in this example.
If the adjustment results in a date-time that is invalid for the zone,
then the ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
with
in interface DateTime
with
in interface DateTimeAccessor
field
- the field to set in the returned date-time, not nullnewValue
- the new value of the field in the returned date-time, not nullZonedDateTime
based on this date-time with the specified field set, not nullDateTimeException
- if the value is invalidpublic ZonedDateTime withYear(int year)
ZonedDateTime
with the year value altered.
If the day-of-month is invalid for the year, it will be changed to the last valid day of the month.
If the adjustment results in a date-time that is invalid for the zone,
then the ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
year
- the year to represent, from MIN_YEAR to MAX_YEARZonedDateTime
based on this date-time with the requested year, not nullDateTimeException
- if the year value is invalidpublic ZonedDateTime withMonth(int month)
ZonedDateTime
with the month-of-year value altered.
If the day-of-month is invalid for the year, it will be changed to the last valid day of the month.
If the adjustment results in a date-time that is invalid for the zone,
then the ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
month
- the month-of-year to represent, from 1 (January) to 12 (December)ZonedDateTime
based on this date-time with the requested month, not nullDateTimeException
- if the month value is invalidpublic ZonedDateTime withDayOfMonth(int dayOfMonth)
ZonedDateTime
with the day-of-month value altered.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
dayOfMonth
- the day-of-month to represent, from 1 to 31ZonedDateTime
based on this date-time with the requested day, not nullDateTimeException
- if the day-of-month value is invalidDateTimeException
- if the day-of-month is invalid for the month-yearpublic ZonedDateTime withDayOfYear(int dayOfYear)
ZonedDateTime
with the day-of-year altered.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
dayOfYear
- the day-of-year to set in the returned date, from 1 to 365-366ZonedDateTime
based on this date with the requested day, not nullDateTimeException
- if the day-of-year value is invalidDateTimeException
- if the day-of-year is invalid for the yearpublic ZonedDateTime withDate(int year, int month, int dayOfMonth)
ZonedDateTime
with the date values altered.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This method will return a new instance with the same time fields, but altered date fields.
This instance is immutable and unaffected by this method call.
year
- the year to represent, from MIN_YEAR to MAX_YEARmonth
- the month-of-year to represent, from 1 (January) to 12 (December)dayOfMonth
- the day-of-month to represent, from 1 to 31ZonedDateTime
based on this date-time with the requested date, not nullDateTimeException
- if the any field value is invalidDateTimeException
- if the day-of-month is invalid for the month-yearpublic ZonedDateTime withHour(int hour)
ZonedDateTime
with the hour-of-day value altered.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
hour
- the hour-of-day to represent, from 0 to 23ZonedDateTime
based on this date-time with the requested hour, not nullDateTimeException
- if the hour value is invalidpublic ZonedDateTime withMinute(int minute)
ZonedDateTime
with the minute-of-hour value altered.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
minute
- the minute-of-hour to represent, from 0 to 59ZonedDateTime
based on this date-time with the requested minute, not nullDateTimeException
- if the minute value is invalidpublic ZonedDateTime withSecond(int second)
ZonedDateTime
with the second-of-minute value altered.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
second
- the second-of-minute to represent, from 0 to 59ZonedDateTime
based on this date-time with the requested second, not nullDateTimeException
- if the second value is invalidpublic ZonedDateTime withNano(int nanoOfSecond)
ZonedDateTime
with the nano-of-second value altered.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
nanoOfSecond
- the nano-of-second to represent, from 0 to 999,999,999ZonedDateTime
based on this date-time with the requested nanosecond, not nullDateTimeException
- if the nanos value is invalidpublic ZonedDateTime withTime(int hour, int minute)
ZonedDateTime
with the time values altered.
This method will return a new instance with the same date fields,
but altered time fields.
This is a shorthand for withTime(int,int,int)
and sets
the second field to zero.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
hour
- the hour-of-day to represent, from 0 to 23minute
- the minute-of-hour to represent, from 0 to 59ZonedDateTime
based on this date-time with the requested time, not nullDateTimeException
- if any field value is invalidpublic ZonedDateTime withTime(int hour, int minute, int second)
ZonedDateTime
with the time values altered.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
hour
- the hour-of-day to represent, from 0 to 23minute
- the minute-of-hour to represent, from 0 to 59second
- the second-of-minute to represent, from 0 to 59ZonedDateTime
based on this date-time with the requested time, not nullDateTimeException
- if any field value is invalidpublic ZonedDateTime withTime(int hour, int minute, int second, int nanoOfSecond)
ZonedDateTime
with the time values altered.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
hour
- the hour-of-day to represent, from 0 to 23minute
- the minute-of-hour to represent, from 0 to 59second
- the second-of-minute to represent, from 0 to 59nanoOfSecond
- the nano-of-second to represent, from 0 to 999,999,999ZonedDateTime
based on this date-time with the requested time, not nullDateTimeException
- if any field value is invalidpublic ZonedDateTime plus(DateTime.PlusAdjuster adjuster)
This method returns a new date-time based on this time with the specified period added.
The adjuster is typically Period
but may be any other type implementing
the DateTime.PlusAdjuster
interface.
The calculation is delegated to the specified adjuster, which typically calls
back to plus(long, PeriodUnit)
.
If the adjustment results in a date-time that is invalid for the zone,
then the ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
plus
in interface DateTime
adjuster
- the adjuster to use, not nullZonedDateTime
based on this date-time with the addition made, not nullDateTimeException
- if the addition cannot be madeArithmeticException
- if numeric overflow occurspublic ZonedDateTime plus(long periodAmount, PeriodUnit unit)
This method returns a new date-time based on this date-time with the specified period added. This can be used to add any period that is defined by a unit, for example to add years, months or days. The unit is responsible for the details of the calculation, including the resolution of any edge cases in the calculation.
If the adjustment results in a date-time that is invalid for the zone,
then the ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
plus
in interface DateTime
periodAmount
- the amount of the unit to add to the returned date-time, not nullunit
- the unit of the period to add, not nullZonedDateTime
based on this date-time with the specified period added, not nullDateTimeException
- if the unit cannot be added to this typepublic ZonedDateTime plusYears(long years)
ZonedDateTime
with the specified period in years added.
This method add the specified amount to the years field in four steps:
ZoneResolvers.retainOffset()
For example, 2008-02-29 (leap year) plus one year would result in the invalid date 2009-02-29 (standard year). Instead of returning an invalid result, the last valid day of the month, 2009-02-28, is selected instead.
This instance is immutable and unaffected by this method call.
years
- the years to add, positive or negativeZonedDateTime
based on this date-time with the years added, not nullDateTimeException
- if the result exceeds the supported rangepublic ZonedDateTime plusMonths(long months)
ZonedDateTime
with the specified period in months added.
This method adds the specified amount to the months field in four steps:
ZoneResolvers.retainOffset()
For example, 2007-03-31 plus one month would result in the invalid date 2007-04-31. Instead of returning an invalid result, the last valid day of the month, 2007-04-30, is selected instead.
This instance is immutable and unaffected by this method call.
months
- the months to add, positive or negativeZonedDateTime
based on this date-time with the months added, not nullDateTimeException
- if the result exceeds the supported rangepublic ZonedDateTime plusWeeks(long weeks)
ZonedDateTime
with the specified period in weeks added.
This method adds the specified amount in weeks to the days field incrementing the month and year fields as necessary to ensure the result remains valid. The result is only invalid if the maximum/minimum year is exceeded.
For example, 2008-12-31 plus one week would result in the 2009-01-07.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
weeks
- the weeks to add, positive or negativeZonedDateTime
based on this date-time with the weeks added, not nullDateTimeException
- if the result exceeds the supported rangepublic ZonedDateTime plusDays(long days)
ZonedDateTime
with the specified period in days added.
This method adds the specified amount to the days field incrementing the month and year fields as necessary to ensure the result remains valid. The result is only invalid if the maximum/minimum year is exceeded.
For example, 2008-12-31 plus one day would result in the 2009-01-01.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
days
- the days to add, positive or negativeZonedDateTime
based on this date-time with the days added, not nullDateTimeException
- if the result exceeds the supported rangepublic ZonedDateTime plusHours(long hours)
ZonedDateTime
with the specified period in hours added.
This method uses field based addition. This method changes the field by the specified number of hours. This may, at daylight savings cutover, result in a duration being added that is more or less than the specified number of hours.
For example, consider a time-zone where the spring DST cutover means that the local times 01:00 to 01:59 do not exist. Using this method, adding a period of 2 hours to 00:30 will result in 02:30, but it is important to note that the change in duration was only 1 hour.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
hours
- the hours to add, positive or negativeZonedDateTime
based on this date-time with the hours added, not nullDateTimeException
- if the result exceeds the supported rangepublic ZonedDateTime plusMinutes(long minutes)
ZonedDateTime
with the specified period in minutes added.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
minutes
- the minutes to add, positive or negativeZonedDateTime
based on this date-time with the minutes added, not nullDateTimeException
- if the result exceeds the supported rangepublic ZonedDateTime plusSeconds(long seconds)
ZonedDateTime
with the specified period in seconds added.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
seconds
- the seconds to add, positive or negativeZonedDateTime
based on this date-time with the seconds added, not nullDateTimeException
- if the result exceeds the supported rangepublic ZonedDateTime plusNanos(long nanos)
ZonedDateTime
with the specified period in nanoseconds added.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
nanos
- the nanos to add, positive or negativeZonedDateTime
based on this date-time with the nanoseconds added, not nullDateTimeException
- if the result exceeds the supported rangepublic ZonedDateTime plusDuration(int hours, int minutes, int seconds, long nanos)
ZonedDateTime
with the specified duration added.
Adding a duration differs from adding a period as gaps and overlaps in the local time-line are taken into account. For example, if there is a gap in the local time-line of one hour from 01:00 to 02:00, then adding a duration of one hour to 00:30 will yield 02:30.
The addition of a duration is always absolute and zone-resolvers are not required.
This instance is immutable and unaffected by this method call.
hours
- the hours to add, positive or negativeminutes
- the minutes to add, positive or negativeseconds
- the seconds to add, positive or negativenanos
- the nanos to add, positive or negativeZonedDateTime
based on this date-time with the duration added, not nullArithmeticException
- if the calculation exceeds the capacity of Instant
DateTimeException
- if the result exceeds the supported rangepublic ZonedDateTime minus(DateTime.MinusAdjuster adjuster)
This method returns a new date-time based on this time with the specified period subtracted.
The adjuster is typically Period
but may be any other type implementing
the DateTime.MinusAdjuster
interface.
The calculation is delegated to the specified adjuster, which typically calls
back to minus(long, PeriodUnit)
.
If the adjustment results in a date-time that is invalid for the zone,
then the ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
minus
in interface DateTime
adjuster
- the adjuster to use, not nullZonedDateTime
based on this date-time with the subtraction made, not nullDateTimeException
- if the subtraction cannot be madeArithmeticException
- if numeric overflow occurspublic ZonedDateTime minus(long periodAmount, PeriodUnit unit)
This method returns a new date-time based on this date-time with the specified period subtracted. This can be used to subtract any period that is defined by a unit, for example to subtract years, months or days. The unit is responsible for the details of the calculation, including the resolution of any edge cases in the calculation.
If the adjustment results in a date-time that is invalid for the zone,
then the ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
minus
in interface DateTime
periodAmount
- the amount of the unit to subtract from the returned date-time, not nullunit
- the unit of the period to subtract, not nullZonedDateTime
based on this date-time with the specified period subtracted, not nullDateTimeException
- if the unit cannot be added to this typepublic ZonedDateTime minusYears(long years)
ZonedDateTime
with the specified period in years subtracted.
This method subtracts the specified amount to the years field in four steps:
ZoneResolvers.retainOffset()
For example, 2008-02-29 (leap year) minus one year would result in the invalid date 2009-02-29 (standard year). Instead of returning an invalid result, the last valid day of the month, 2009-02-28, is selected instead.
This instance is immutable and unaffected by this method call.
years
- the years to subtract, positive or negativeZonedDateTime
based on this date-time with the years subtracted, not nullDateTimeException
- if the result exceeds the supported rangepublic ZonedDateTime minusMonths(long months)
ZonedDateTime
with the specified period in months subtracted.
This method subtracts the specified amount to the months field in four steps:
ZoneResolvers.retainOffset()
For example, 2007-03-31 minus one month would result in the invalid date 2007-04-31. Instead of returning an invalid result, the last valid day of the month, 2007-04-30, is selected instead.
This instance is immutable and unaffected by this method call.
months
- the months to subtract, positive or negativeZonedDateTime
based on this date-time with the months subtracted, not nullDateTimeException
- if the result exceeds the supported rangepublic ZonedDateTime minusWeeks(long weeks)
ZonedDateTime
with the specified period in weeks subtracted.
This method subtracts the specified amount in weeks to the days field incrementing the month and year fields as necessary to ensure the result remains valid. The result is only invalid if the maximum/minimum year is exceeded.
For example, 2008-12-31 minus one week would result in the 2009-01-07.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
weeks
- the weeks to subtract, positive or negativeZonedDateTime
based on this date-time with the weeks subtracted, not nullDateTimeException
- if the result exceeds the supported rangepublic ZonedDateTime minusDays(long days)
ZonedDateTime
with the specified period in days subtracted.
This method subtracts the specified amount to the days field incrementing the month and year fields as necessary to ensure the result remains valid. The result is only invalid if the maximum/minimum year is exceeded.
For example, 2008-12-31 minus one day would result in the 2009-01-01.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
days
- the days to subtract, positive or negativeZonedDateTime
based on this date-time with the days subtracted, not nullDateTimeException
- if the result exceeds the supported rangepublic ZonedDateTime minusHours(long hours)
ZonedDateTime
with the specified period in hours subtracted.
This method uses field based subtraction. This method changes the field by the specified number of hours. This may, at daylight savings cutover, result in a duration being subtracted that is more or less than the specified number of hours.
For example, consider a time-zone where the spring DST cutover means that the local times 01:00 to 01:59 do not exist. Using this method, subtracting a period of 2 hours from 02:30 will result in 00:30, but it is important to note that the change in duration was only 1 hour.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
hours
- the hours to subtract, positive or negativeZonedDateTime
based on this date-time with the hours subtracted, not nullDateTimeException
- if the result exceeds the supported rangepublic ZonedDateTime minusMinutes(long minutes)
ZonedDateTime
with the specified period in minutes subtracted.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
minutes
- the minutes to subtract, positive or negativeZonedDateTime
based on this date-time with the minutes subtracted, not nullDateTimeException
- if the result exceeds the supported rangepublic ZonedDateTime minusSeconds(long seconds)
ZonedDateTime
with the specified period in seconds subtracted.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
seconds
- the seconds to subtract, positive or negativeZonedDateTime
based on this date-time with the seconds subtracted, not nullDateTimeException
- if the result exceeds the supported rangepublic ZonedDateTime minusNanos(long nanos)
ZonedDateTime
with the specified period in nanoseconds subtracted.
If the adjustment results in a date-time that is invalid, then the
ZoneResolvers.retainOffset()
resolver is used.
This instance is immutable and unaffected by this method call.
nanos
- the nanos to subtract, positive or negativeZonedDateTime
based on this date-time with the nanoseconds subtracted, not nullDateTimeException
- if the result exceeds the supported rangepublic ZonedDateTime minusDuration(int hours, int minutes, int seconds, long nanos)
ZonedDateTime
with the specified duration subtracted.
Subtracting a duration differs from subtracting a period as gaps and overlaps in the local time-line are taken into account. For example, if there is a gap in the local time-line of one hour from 01:00 to 02:00, then subtracting a duration of one hour from 02:30 will yield 00:30.
The subtraction of a duration is always absolute and zone-resolvers are not required.
This instance is immutable and unaffected by this method call.
hours
- the hours to subtract, positive or negativeminutes
- the minutes to subtract, positive or negativeseconds
- the seconds to subtract, positive or negativenanos
- the nanos to subtract, positive or negativeZonedDateTime
based on this date-time with the duration subtracted, not nullArithmeticException
- if the calculation exceeds the capacity of Instant
DateTimeException
- if the result exceeds the supported rangepublic <R> R extract(Class<R> type)
This method exists to fulfill the DateTimeAccessor
interface.
This implementation returns the following types:
extract
in interface DateTimeAccessor
R
- the type to extracttype
- the type to extract, null returns nullpublic DateTime doAdjustment(DateTime calendrical)
DateTime.WithAdjuster
This method is not intended to be called by application code directly.
Instead, the DateTime.with(WithAdjuster)
method should be used:
Implementations must use the methods on DateTime
to make the adjustment.
The returned object must have the same observable type as this object.
The input object will be mutated if it is mutable, or a new object returned if immutable.
This interface can be used by calendar systems other than ISO. Implementations may choose to document compatibility with other calendar systems, or validate for it by querying the calendar system from the input object.
doAdjustment
in interface DateTime.WithAdjuster
calendrical
- the date-time object to adjust, not nullpublic long periodUntil(DateTime endDateTime, PeriodUnit unit)
DateTime
This is used to calculate the period between two date-times.
This method operates in association with PeriodUnit.between(R, R)
.
That method returns an object which can be used directly in addition/subtraction
whereas this method returns the amount directly:
long period = start.periodUntil(end, MONTHS); // this method long period = MONTHS.between(start, end).getAmount(); // same as above dateTime.plus(MONTHS.between(start, end)); // directly add
periodUntil
in interface DateTime
endDateTime
- the end date-time, of the same type as this object, not nullunit
- the unit to measure the period in, not nullpublic Instant toInstant()
ZonedDateTime
to an Instant
.public LocalDate toLocalDate()
ZonedDateTime
to a LocalDate
.public LocalTime toLocalTime()
ZonedDateTime
to a LocalTime
.public LocalDateTime toLocalDateTime()
ZonedDateTime
to a LocalDateTime
.public OffsetDate toOffsetDate()
ZonedDateTime
to a OffsetDate
.public OffsetTime toOffsetTime()
ZonedDateTime
to a OffsetTime
.public OffsetDateTime toOffsetDateTime()
ZonedDateTime
to a OffsetDateTime
.public long toEpochSecond()
ZonedDateTime
to the number of seconds from the epoch
of 1970-01-01T00:00:00Z.
Instants on the time-line after the epoch are positive, earlier are negative.
public int compareTo(ZonedDateTime other)
ZonedDateTime
to another date-time based on the UTC
equivalent date-times then time-zone unique key.
The ordering is consistent with equals as it takes into account the date-time, offset and zone.
compareTo
in interface Comparable<ZonedDateTime>
other
- the other date-time to compare to, not nullNullPointerException
- if other
is nullpublic boolean isBefore(ZonedDateTime other)
This method differs from the comparison in compareTo(javax.time.ZonedDateTime)
in that it
only compares the instant of the date-time. This is equivalent to using
dateTime1.toInstant().isBefore(dateTime2.toInstant());
.
other
- the other date-time to compare to, not nullNullPointerException
- if other
is nullpublic boolean isAfter(ZonedDateTime other)
This method differs from the comparison in compareTo(javax.time.ZonedDateTime)
in that it
only compares the instant of the date-time. This is equivalent to using
dateTime1.toInstant().isAfter(dateTime2.toInstant());
.
other
- the other date-time to compare to, not nullNullPointerException
- if other
is nullpublic boolean equalInstant(ZonedDateTime other)
This method differs from the comparison in compareTo(javax.time.ZonedDateTime)
and equals(java.lang.Object)
in that it only compares the instant of the date-time. This is equivalent to using
dateTime1.toInstant().equals(dateTime2.toInstant());
.
other
- the other date-time to compare to, not nullNullPointerException
- if other
is nullpublic boolean equals(Object obj)
The comparison is based on the offset date-time and the zone.
To compare for the same instant on the time-line, use equalInstant(javax.time.ZonedDateTime)
.
Only objects of type ZonedDateTime
are compared, other types return false.
public int hashCode()
public String toString()
String
, such as
2007-12-03T10:15:30+01:00[Europe/Paris]
.
The output will be one of the following formats:
yyyy-MM-dd'T'HH:mmXXXXX'['I']'
yyyy-MM-dd'T'HH:mm:ssXXXXX'['I']'
yyyy-MM-dd'T'HH:mm:ssfnnnXXXXX'['I']'
yyyy-MM-dd'T'HH:mm:ssfnnnnnnXXXXX'['I']'
yyyy-MM-dd'T'HH:mm:ssfnnnnnnnnnXXXXX'['I']'
public String toString(CalendricalFormatter formatter)
String
using the formatter.formatter
- the formatter to use, not nullUnsupportedOperationException
- if the formatter cannot printDateTimeException
- if an error occurs during printing