net.degreedays.time

Class OffsetDayTime

java.lang.Object

net.degreedays.time.OffsetDayTime

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<OffsetDayTime>

public final class OffsetDayTime
extends java.lang.Object
implements java.lang.Comparable<OffsetDayTime>, java.io.Serializable

Represents a date-time with a time-zone defined in terms of the offset from UTC, for example 2020-04-10T14:55+01:00.

Note that, internally, this class, like all the other date-related classes in this package, uses the modern Gregorian calendar for all validation and calculations. The Gregorian calendar was introduced in 1582 but this class applies it to earlier dates as well (so using what is known as the "proleptic Gregorian calendar"). This fits with the ISO 8601 standard and is how the java.time package works by default, but it's not how java.util.Calendar works by default, so bear this in mind if you are working with dates from 1582 or before. You are of course unlikely to find good weather data from that far back, but we mention this just in case you find yourself using this class for other purposes as well!

Since:

1.2

Instances of this class are immutable. You can safely reuse them and call them from multiple threads at once.

Constructor Summary

Constructors

Constructor and Description
OffsetDayTime(DayTime dayTime, int offsetTotalMinutes) Constructs an OffsetDayTime object with the specified local date-time and UTC offset.
OffsetDayTime(Day day, Time time, int offsetTotalMinutes) Constructs an OffsetDayTime object with the specified local date, time, and UTC offset.

Method Summary

Modifier and Type	Method and Description
boolean	after(OffsetDayTime comparisonOffsetDayTime) Returns true if the instant in time represented by this OffsetDayTime is after the instant in time represented by comparisonOffsetDayTime; false otherwise.
boolean	before(OffsetDayTime comparisonOffsetDayTime) Returns true if the instant in time represented by this OffsetDayTime is before the instant in time represented by comparisonOffsetDayTime; false otherwise.
int	compareTo(OffsetDayTime comparisonOffsetDayTime) Compares two OffsetDayTime objects for chronological ordering, considering first the instants in time that they represent, and only considering their local clock times if those instants are identical.
Day	day() Returns a non-null Day object representing the YYYY-MM-DD component of this OffsetDayTime.
int	dayOfMonth() Returns a number between 1 and 31 (inclusive) indicating the day-of-the-month component of this OffsetDayTime.
DayOfWeek	dayOfWeek() Returns a non-null DayOfWeek object indicating the day of the week of this OffsetDayTime.
int	dayOfYear() Returns a number between 1 and 366 inclusive (365 for non-leap years) indicating the day of the year of this OffsetDayTime.
DayTime	dayTime() Returns a non-null DayTime object representing the YYYY-MM-DDThh:mm component of this OffsetDayTime.
boolean	equals(java.lang.Object o) Returns true if o is an OffsetDayTime representing the same date-time and UTC offset as this OffsetDayTime; false otherwise.
static OffsetDayTime	fromString(java.lang.String dateTimeAndOffsetString) Parses a string date-time with UTC-offset time-zone information included in ISO format like e.g. 2020-04-10T12:35Z ( Z indicating the UTC time-zone i.e. no offset), or 2019-01-31T18:22-08:00 (8 hours behind UTC).
int	hashCode() Overridden to ensure consistency with equals.
int	hour() Returns a number between 0 and 23 (inclusive) representing the hour component of this OffsetDayTime.
int	minute() Returns a number between 0 and 59 (inclusive) representing the minute component of this OffsetDayTime.
long	minutesAfter(OffsetDayTime comparisonOffsetDayTime) Returns the number of minutes that the instant in time represented by this OffsetDayTime is after that represented by comparisonOffsetDayTime, which will be negative if this OffsetDayTime comes first chronologically.
long	minutesBefore(OffsetDayTime comparisonOffsetDayTime) Returns the number of minutes that the instant in time represented by this OffsetDayTime is before that represented by comparisonOffsetDayTime, which will be negative if comparisonOffsetDayTime comes first chronologically.
int	monthOfYear() Returns a number between 1 (January) and 12 (December) representing the month-of-the-year component of this OffsetDayTime.
static OffsetDayTime	of(DayTime dayTime, int offsetTotalMinutes) Returns a non-null OffsetDayTime object with the specified local date-time and UTC offset.
static OffsetDayTime	of(Day day, Time time, int offsetTotalMinutes) Returns a non-null OffsetDayTime object with the specified local date, time, and UTC offset.
int	offsetTotalMinutes() Returns the total number of minutes by which this OffsetDayTime is offset from UTC; for example for 2020-08-15T11:43+01:00 this would return 60, and for 2020-08-15T11:43-05:00 it would return -300.
Time	time() Returns a non-null Time object representing the hh:mm component of this OffsetDayTime.
java.util.Date	toDate() Returns the instant in time represented by this OffsetDayTime as a non-null java.util.Date.
long	toEpochMilli() Returns the instant in time represented by this OffsetDayTime as the number of milliseconds since the epoch of 1970-01-01T00:00Z.
java.lang.String	toString() Returns a non-null, non-empty string representation of this OffsetDayTime in ISO format like 2020-08-15T17:57+01:00, 2020-08-15T12:57-05:00, or 2020-08-15T16:57Z.
int	year() Returns a number indicating the year component of this OffsetDayTime.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

OffsetDayTime

public OffsetDayTime(DayTime dayTime,
                     int offsetTotalMinutes)

Constructs an OffsetDayTime object with the specified local date-time and UTC offset.

Parameters:

dayTime - the local YYYY-MM-DDThh:mm date-time.

offsetTotalMinutes - the total minutes offset from UTC (e.g. 60 for the +01:00 time-zone, -300 for the -05:00 time-zone, 0 for the UTC/GMT time-zone).

Throws:

java.lang.NullPointerException - if dayTime is null.

java.lang.IllegalArgumentException - if offsetTotalMinutes is less than -1080 (for a -18:00 time-zone) or greater than 1080 (for a +18:00 time-zone).

OffsetDayTime

public OffsetDayTime(Day day,
                     Time time,
                     int offsetTotalMinutes)

Constructs an OffsetDayTime object with the specified local date, time, and UTC offset.

Parameters:

day - the local YYYY-MM-DD date.

time - the local hh:mm time.

offsetTotalMinutes - the total minutes offset from UTC (e.g. 60 for the +01:00 time-zone, -300 for the -05:00 time-zone, 0 for the UTC/GMT time-zone).

Throws:

java.lang.NullPointerException - if day or time is null.

java.lang.IllegalArgumentException - if offsetTotalMinutes is less than -1080 (for a -18:00 time-zone) or greater than 1080 (for a +18:00 time-zone).

Method Detail

of

public static OffsetDayTime of(DayTime dayTime,
                               int offsetTotalMinutes)

Returns a non-null OffsetDayTime object with the specified local date-time and UTC offset.

Parameters:

dayTime - the local YYYY-MM-DDThh:mm date-time.

offsetTotalMinutes - the total minutes offset from UTC (e.g. 60 for the +01:00 time-zone, -300 for the -05:00 time-zone, 0 for the UTC/GMT time-zone).

Throws:

java.lang.NullPointerException - if dayTime is null.

java.lang.IllegalArgumentException - if offsetTotalMinutes is less than -1080 (for a -18:00 time-zone) or greater than 1080 (for a +18:00 time-zone).

of

public static OffsetDayTime of(Day day,
                               Time time,
                               int offsetTotalMinutes)

Returns a non-null OffsetDayTime object with the specified local date, time, and UTC offset.

Parameters:

day - the local YYYY-MM-DD date.

time - the local hh:mm time.

offsetTotalMinutes - the total minutes offset from UTC (e.g. 60 for the +01:00 time-zone, -300 for the -05:00 time-zone, 0 for the UTC/GMT time-zone).

Throws:

java.lang.NullPointerException - if day or time is null.

java.lang.IllegalArgumentException - if offsetTotalMinutes is less than -1080 (for a -18:00 time-zone) or greater than 1080 (for a +18:00 time-zone).

dayTime

public DayTime dayTime()

Returns a non-null DayTime object representing the YYYY-MM-DDThh:mm component of this OffsetDayTime.

offsetTotalMinutes

public int offsetTotalMinutes()

Returns the total number of minutes by which this OffsetDayTime is offset from UTC; for example for 2020-08-15T11:43+01:00 this would return 60, and for 2020-08-15T11:43-05:00 it would return -300.

day

public Day day()

Returns a non-null Day object representing the YYYY-MM-DD component of this OffsetDayTime.

time

public Time time()

Returns a non-null Time object representing the hh:mm component of this OffsetDayTime.

year

public int year()

Returns a number indicating the year component of this OffsetDayTime.

monthOfYear

public int monthOfYear()

Returns a number between 1 (January) and 12 (December) representing the month-of-the-year component of this OffsetDayTime.

dayOfMonth

public int dayOfMonth()

Returns a number between 1 and 31 (inclusive) indicating the day-of-the-month component of this OffsetDayTime.

dayOfWeek

public DayOfWeek dayOfWeek()

Returns a non-null DayOfWeek object indicating the day of the week of this OffsetDayTime.

dayOfYear

public int dayOfYear()

Returns a number between 1 and 366 inclusive (365 for non-leap years) indicating the day of the year of this OffsetDayTime.

hour

public int hour()

Returns a number between 0 and 23 (inclusive) representing the hour component of this OffsetDayTime.

minute

public int minute()

Returns a number between 0 and 59 (inclusive) representing the minute component of this OffsetDayTime.

toEpochMilli

public long toEpochMilli()

Returns the instant in time represented by this OffsetDayTime as the number of milliseconds since the epoch of 1970-01-01T00:00Z.

With this method you can create a java.time.Instant from an OffsetDayTime as follows:

 Instant.ofEpochMilli(offsetDayTime.toEpochMilli())
 

toDate

public java.util.Date toDate()

Returns the instant in time represented by this OffsetDayTime as a non-null java.util.Date. This is just a shortcut for:

 new Date(offsetDayTime.toEpochMilli())
 

fromString

public static OffsetDayTime fromString(java.lang.String dateTimeAndOffsetString)

Parses a string date-time with UTC-offset time-zone information included in ISO format like e.g. 2020-04-10T12:35Z ( Z indicating the UTC time-zone i.e. no offset), or 2019-01-31T18:22-08:00 (8 hours behind UTC).

In the part of the string before the time-zone info, this will also accept the variations allowed by DayTime.fromString(java.lang.String). The colon in the time-zone info is optional too. But in most cases it makes sense to stick with ISO format as in the examples above.

Returns:

a non-null OffsetDayTime object corresponding to the date-time and UTC offset represented by dateTimeAndOffsetString.

Throws:

java.lang.NullPointerException - if dateTimeAndOffsetString is null.

java.lang.NumberFormatException - if dateTimeAndOffsetString has an invalid format, or represents a non-existent date-time or one that is outside the range allowed by Day (0001-01-01 to 9999-12-31 inclusive).

See Also:

toString()

toString

public java.lang.String toString()

Returns a non-null, non-empty string representation of this OffsetDayTime in ISO format like 2020-08-15T17:57+01:00, 2020-08-15T12:57-05:00, or 2020-08-15T16:57Z.

In the examples above:

• the +01:00 in 2020-08-15T17:57+01:00 indicates a time-zone 1 hour ahead of UTC (i.e. a UTC offset of +60 minutes);
• the -05:00 in 2020-08-15T12:57-05:00 indicates a time-zone 5 hours behind UTC (i.e. a UTC offset of -300 minutes); and
• the Z in 2020-08-15T16:57Z indicates the UTC time-zone itself (i.e. no UTC offset, or a UTC offset of zero minutes).

Overrides:

toString in class java.lang.Object

See Also:

fromString(java.lang.String)

equals

public boolean equals(java.lang.Object o)

Returns true if o is an OffsetDayTime representing the same date-time and UTC offset as this OffsetDayTime; false otherwise.

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overridden to ensure consistency with equals.

Overrides:

hashCode in class java.lang.Object

compareTo

public int compareTo(OffsetDayTime comparisonOffsetDayTime)

Compares two OffsetDayTime objects for chronological ordering, considering first the instants in time that they represent, and only considering their local clock times if those instants are identical.

When two OffsetDayTime objects represent the same instant in time but in different time-zones (e.g. like how 2020-02-15T12:36-08:00 and 2020-02-15T15:36-05:00 are in different time-zones but actually represent the same instant in time), this will order the one with the earlier local dayTime() first (so 2020-02-15T12:36-08:00 will be ordered before 2020-02-15T15:36-05:00). In this way this compareTo method remains consistent with equals(java.lang.Object).

Specified by:

compareTo in interface java.lang.Comparable<OffsetDayTime>

Parameters:

comparisonOffsetDayTime - the OffsetDayTime to be compared. Cannot be null.

Returns:

a negative integer if this OffsetDayTime represents an instant in time before that of comparisonOffsetDayTime (or they represent the same instant in time but this OffsetDayTime has an earlier local dayTime()); zero if this OffsetDayTime is equal to comparisonOffsetDayTime (which means they both represent the same instant in time and have the same UTC offset); or a positive integer if this OffsetDayTime represents an instant in time after that of comparisonOffsetDayTime (or they represent the same instant in time but this OffsetDayTime has a later local dayTime()).

Throws:

java.lang.NullPointerException - if comparisonOffsetDayTime is null.

See Also:

before(net.degreedays.time.OffsetDayTime), after(net.degreedays.time.OffsetDayTime)

before

public boolean before(OffsetDayTime comparisonOffsetDayTime)

Returns true if the instant in time represented by this OffsetDayTime is before the instant in time represented by comparisonOffsetDayTime; false otherwise.

The comparison made by this method is different to that made by compareTo(net.degreedays.time.OffsetDayTime) because this method considers only whether the instant in time that this OffsetDayTime represents is before that represented by comparisonOffsetDayTime. Consider for example 2020-02-15T12:36-08:00 and 2020-02-15T15:36-05:00... Both represent the same instant in time, but in different time-zones. This method will never put one before the other, but compareTo(net.degreedays.time.OffsetDayTime) will order 2020-02-15T12:36-08:00 first (as its docs explain).

Parameters:

comparisonOffsetDayTime - the OffsetDayTime to compare with this OffsetDayTime. Cannot be null.

Throws:

java.lang.NullPointerException - if comparisonOffsetDayTime is null.

See Also:

after(net.degreedays.time.OffsetDayTime), compareTo(net.degreedays.time.OffsetDayTime)

after

public boolean after(OffsetDayTime comparisonOffsetDayTime)

Returns true if the instant in time represented by this OffsetDayTime is after the instant in time represented by comparisonOffsetDayTime; false otherwise.

The comparison made by this method is different to that made by compareTo(net.degreedays.time.OffsetDayTime) because this method considers only whether the instant in time that this OffsetDayTime represents is after that represented by comparisonOffsetDayTime. Consider for example 2020-02-15T12:36-08:00 and 2020-02-15T15:36-05:00... Both represent the same instant in time, but in different time-zones. This method will never put one after the other, but compareTo(net.degreedays.time.OffsetDayTime) will order 2020-02-15T12:36-08:00 first (as its docs explain).

Parameters:

comparisonOffsetDayTime - the OffsetDayTime to compare with this OffsetDayTime. Cannot be null.

Throws:

java.lang.NullPointerException - if comparisonOffsetDayTime is null.

See Also:

before(net.degreedays.time.OffsetDayTime), compareTo(net.degreedays.time.OffsetDayTime)

minutesAfter

public long minutesAfter(OffsetDayTime comparisonOffsetDayTime)

Returns the number of minutes that the instant in time represented by this OffsetDayTime is after that represented by comparisonOffsetDayTime, which will be negative if this OffsetDayTime comes first chronologically.

Throws:

java.lang.NullPointerException - if comparisonOffsetDayTime is null.

See Also:

minutesBefore(net.degreedays.time.OffsetDayTime)

minutesBefore

public long minutesBefore(OffsetDayTime comparisonOffsetDayTime)

Returns the number of minutes that the instant in time represented by this OffsetDayTime is before that represented by comparisonOffsetDayTime, which will be negative if comparisonOffsetDayTime comes first chronologically.

Throws:

java.lang.NullPointerException - if comparisonOffsetDayTime is null.

See Also:

minutesAfter(net.degreedays.time.OffsetDayTime)