net.degreedays.time
Class OffsetDayTime

java.lang.Object
  extended by net.degreedays.time.OffsetDayTime
All Implemented Interfaces:
java.io.Serializable, java.lang.Comparable

public final class OffsetDayTime
extends java.lang.Object
implements java.lang.Comparable, 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
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
 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(java.lang.Object 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:

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(java.lang.Object 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
Parameters:
comparisonOffsetDayTime - the OffsetDayTime to be compared (the declared type is Object but it must be an object that can be cast to OffsetDayTime). 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.
java.lang.ClassCastException - if comparisonOffsetDayTime is not an OffsetDayTime object.
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(java.lang.Object) 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(java.lang.Object) 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(java.lang.Object)

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(java.lang.Object) 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(java.lang.Object) 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(java.lang.Object)

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)


www.degreedays.net/api/