Class Timestamp
- java.lang.Object
-
- com.amazon.ion.Timestamp
-
- All Implemented Interfaces:
java.lang.Cloneable
,java.lang.Comparable<Timestamp>
public final class Timestamp extends java.lang.Object implements java.lang.Comparable<Timestamp>, java.lang.Cloneable
An immutable representation of a point in time. Ion defines a simple representation of time based on Coordinated Universal Time (UTC). In practice the use of time could be more accurately described as UTC-SLS (UTC Smoothed Leap Seconds) as there is no representation for the leap second discontinuities that UTC has added.Timestamps preserve precision, meaning the fields that are included, and the significant digits of any fractional second. Only common break points in the values are supported. Any unspecified fields are handled as the start of the new year/month/day.
Equality and Comparison
As withIonValue
classes, theequals
methods on this class perform a strict equivalence that observes the precision and local offset of each timestamp. This means that it's possible to have twoTimestamp
instances that represent the same point in time but are notequals
.On the other hand, the
compareTo(com.amazon.ion.Timestamp)
methods perform point in time comparison, ignoring precision and local offset. Thus the natural comparison method of this class is not consistent with equals. See the documentation ofComparable
for further discussion.To illustrate this distinction, consider the following timestamps. None are
equals(java.lang.Object)
to each other, but any pair will return a zero result fromcompareTo(com.amazon.ion.Timestamp)
.2009T
2009-01T
2009-01-01T
2009-01-01T00:00Z
2009-01-01T00:00:00Z
2009-01-01T00:00:00.0Z
2009-01-01T00:00:00.00Z
2009-01-01T00:00:00.000Z
etc.
- See Also:
equals(Timestamp)
,compareTo(Timestamp)
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
Timestamp.Precision
The precision of the Timestamp.
-
Field Summary
Fields Modifier and Type Field Description static java.lang.Integer
UNKNOWN_OFFSET
Unknown local offset from UTC.static java.lang.Integer
UTC_OFFSET
Local offset of zero hours from UTC.
-
Constructor Summary
Constructors Constructor Description Timestamp(int zyear, int zmonth, int zday)
Deprecated.UseforDay(int, int, int)
instead.Timestamp(int year, int month, int day, int hour, int minute, int second, java.lang.Integer offset)
Deprecated.UseforSecond(int, int, int, int, int, int, Integer)
instead.Timestamp(int year, int month, int day, int hour, int minute, int second, java.math.BigDecimal frac, java.lang.Integer offset)
Deprecated.Timestamp(int year, int month, int day, int hour, int minute, java.lang.Integer offset)
Deprecated.UseforMinute(int, int, int, int, int, Integer)
instead.Timestamp(long millis, java.lang.Integer localOffset)
Deprecated.UseforMillis(long, Integer)
instead.Timestamp(java.math.BigDecimal millis, java.lang.Integer localOffset)
Deprecated.UseforMillis(BigDecimal, Integer)
instead.Timestamp(java.util.Calendar cal)
Deprecated.UseforCalendar(Calendar)
instead.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description Timestamp
addDay(int amount)
Returns a timestamp relative to this one by the given number of days.Timestamp
addHour(int amount)
Returns a timestamp relative to this one by the given number of hours.Timestamp
addMillis(long amount)
Returns a timestamp relative to this one by the given number of milliseconds.Timestamp
addMinute(int amount)
Returns a timestamp relative to this one by the given number of minutes.Timestamp
addMonth(int amount)
Returns a timestamp relative to this one by the given number of months.Timestamp
addSecond(int amount)
Returns a timestamp relative to this one by the given number of seconds.Timestamp
addYear(int amount)
Returns a timestamp relative to this one by the given number of years.Timestamp
adjustDay(int amount)
Returns a timestamp relative to this one by the given number of days.Timestamp
adjustHour(int amount)
Returns a timestamp relative to this one by the given number of hours.Timestamp
adjustMillis(long amount)
Returns a timestamp relative to this one by the given number of milliseconds.Timestamp
adjustMinute(int amount)
Returns a timestamp relative to this one by the given number of minutes.Timestamp
adjustMonth(int amount)
Returns a timestamp relative to this one by the given number of months.Timestamp
adjustSecond(int amount)
Returns a timestamp relative to this one by the given number of seconds.Timestamp
adjustYear(int amount)
Returns a timestamp relative to this one by the given number of years.java.util.Calendar
calendarValue()
Converts the value of this Timestamp as aCalendar
, in its local time.Timestamp
clone()
Creates a copy of this Timestamp.int
compareTo(Timestamp t)
Performs a comparison of the two points in time represented by two Timestamps.static Timestamp
createFromUtcFields(Timestamp.Precision p, int zyear, int zmonth, int zday, int zhour, int zminute, int zsecond, java.math.BigDecimal frac, java.lang.Integer offset)
Deprecated.java.util.Date
dateValue()
Converts the value of this Timestamp into aDate
, representing the time in UTC.boolean
equals(Timestamp t)
boolean
equals(java.lang.Object t)
Compares thisTimestamp
to the specified Object.static Timestamp
forCalendar(java.util.Calendar calendar)
Converts aCalendar
to a Timestamp, preserving the calendar's time zone as the equivalent local offset when it has at least minutes precision.static Timestamp
forDateZ(java.util.Date date)
Converts aDate
to a Timestamp in UTC representing the same point in time.static Timestamp
forDay(int yearZ, int monthZ, int dayZ)
Returns a Timestamp, precise to the day, with unknown local offset.static Timestamp
forEpochSecond(long seconds, int nanoOffset, java.lang.Integer localOffset)
Returns a Timestamp that represents the point in time that isseconds
from the unix epoch (1970-01-01T00:00:00.000Z), with thenanoOffset
applied and a given local offset.static Timestamp
forMillis(long millis, java.lang.Integer localOffset)
Returns a Timestamp that represents the point in time that ismillis
milliseconds from the epoch, with a given local offset.static Timestamp
forMillis(java.math.BigDecimal millis, java.lang.Integer localOffset)
The same asforMillis(long, Integer)
but the millisecond component is specified using aBigDecimal
and therefore may include fractional milliseconds.static Timestamp
forMinute(int year, int month, int day, int hour, int minute, java.lang.Integer offset)
Returns a Timestamp, precise to the minute, with a given local offset.static Timestamp
forMonth(int yearZ, int monthZ)
Returns a Timestamp, precise to the month, with unknown local offset.static Timestamp
forSecond(int year, int month, int day, int hour, int minute, int second, java.lang.Integer offset)
Returns a Timestamp, precise to the second, with a given local offset.static Timestamp
forSecond(int year, int month, int day, int hour, int minute, java.math.BigDecimal second, java.lang.Integer offset)
Returns a Timestamp, precise to the second, with a given local offset.static Timestamp
forSqlTimestampZ(java.sql.Timestamp sqlTimestamp)
Converts aTimestamp
to a Timestamp in UTC representing the same point in time.static Timestamp
forYear(int yearZ)
Returns a Timestamp, precise to the year, with unknown local offset.int
getDay()
Returns the day (within the month) of this Timestamp, in its local time.java.math.BigDecimal
getDecimalMillis()
Returns a BigDecimal representing the Timestamp's point in time that is the number of milliseconds (including any fractional milliseconds) from the epoch.java.math.BigDecimal
getDecimalSecond()
Returns the seconds of this Timestamp.java.math.BigDecimal
getFractionalSecond()
Deprecated.int
getHour()
Returns the hour of this Timestamp, in its local time.java.lang.Integer
getLocalOffset()
Returns the offset of this Timestamp, measured in minutes, for the local timezone in UTC.long
getMillis()
Returns a number representing the Timestamp's point in time that is the number of milliseconds (ignoring any fractional milliseconds) from the epoch.int
getMinute()
Returns the minute of this Timestamp, in its local time.int
getMonth()
Returns the month of this Timestamp, in its local time.Timestamp.Precision
getPrecision()
Returns the precision of this Timestamp.int
getSecond()
Returns the seconds of this Timestamp, truncated to an integer.int
getYear()
Returns the year of this Timestamp, in its local time.int
getZDay()
Returns the day of this Timestamp, in UTC.java.math.BigDecimal
getZDecimalSecond()
Returns the seconds of this Timestamp.java.math.BigDecimal
getZFractionalSecond()
Deprecated.UsegetZDecimalSecond()
instead.int
getZHour()
Returns the hour of this Timestamp, in UTC.int
getZMinute()
Returns the minute of this Timestamp, in UTC.int
getZMonth()
Returns the month of this Timestamp, in UTC.int
getZSecond()
Returns the second of this Timestamp.int
getZYear()
Returns the year of this Timestamp, in UTC.int
hashCode()
Returns a hash code consistent withequals(Object)
.static Timestamp
now()
Returns a Timestamp representing the current time (based on the JVM clock), with an unknown local offset.static Timestamp
nowZ()
Returns a Timestamp in UTC representing the current time (based on the the JVM clock).void
print(java.lang.Appendable out)
Prints to anAppendable
the string representation (in Ion format) of this Timestamp in its local time.void
printZ(java.lang.Appendable out)
Prints to anAppendable
the string representation (in Ion format) of this Timestamp in UTC.java.lang.String
toString()
Returns the string representation (in Ion format) of this Timestamp in its local time.java.lang.String
toZString()
Returns the string representation (in Ion format) of this Timestamp in UTC.static Timestamp
valueOf(java.lang.CharSequence ionFormattedTimestamp)
Returns a new Timestamp that represents the point in time, precision and local offset defined in Ion format by theCharSequence
.Timestamp
withLocalOffset(java.lang.Integer offset)
Returns a timestamp at the same point in time, but with the given local offset.
-
-
-
Constructor Detail
-
Timestamp
@Deprecated public Timestamp(int zyear, int zmonth, int zday)
Deprecated.UseforDay(int, int, int)
instead.Creates a new Timestamp, precise to the day, with unknown local offset.This is equivalent to the corresponding Ion value
YYYY-MM-DD
.
-
Timestamp
@Deprecated public Timestamp(int year, int month, int day, int hour, int minute, java.lang.Integer offset)
Deprecated.UseforMinute(int, int, int, int, int, Integer)
instead.Creates a new Timestamp, precise to the minute, with a given local offset.This is equivalent to the corresponding Ion value
YYYY-MM-DDThh:mm+-oo:oo
, whereoo:oo
represents the hour and minutes of the local offset from UTC.- Parameters:
offset
- the local offset from UTC, measured in minutes; may benull
to represent an unknown local offset
-
Timestamp
@Deprecated public Timestamp(int year, int month, int day, int hour, int minute, int second, java.lang.Integer offset)
Deprecated.UseforSecond(int, int, int, int, int, int, Integer)
instead.Creates a new Timestamp, precise to the second, with a given local offset.This is equivalent to the corresponding Ion value
YYYY-MM-DDThh:mm:ss+-oo:oo
, whereoo:oo
represents the hour and minutes of the local offset from UTC.- Parameters:
offset
- the local offset from UTC, measured in minutes; may benull
to represent an unknown local offset.
-
Timestamp
@Deprecated public Timestamp(int year, int month, int day, int hour, int minute, int second, java.math.BigDecimal frac, java.lang.Integer offset)
Deprecated.Creates a new Timestamp, precise to the second or fractional second, with a given local offset.This is equivalent to the corresponding Ion value
YYYY-MM-DDThh:mm:ss.fff+-oo:oo
, whereoo:oo
represents the hour and minutes of the local offset from UTC, andfff
represents the fractional seconds.- Parameters:
frac
- the fractional seconds; must not benull
; if negative, its absolute value is usedoffset
- the local offset from UTC, measured in minutes; may benull
to represent an unknown local offset- Throws:
java.lang.NullPointerException
- iffrac
isnull
-
Timestamp
@Deprecated public Timestamp(java.util.Calendar cal)
Deprecated.UseforCalendar(Calendar)
instead.Creates a new Timestamp from aCalendar
, preserving theCalendar
's precision and local offset from UTC.The most precise calendar field of
cal
will be used to determine the precision of the resulting Timestamp. For example, the calendar field will have a Timestamp precision accordingly:Calendar.YEAR
- year precision, unknown local offsetCalendar.MONTH
- month precision, unknown local offsetCalendar.DAY_OF_MONTH
- day precision, unknown local offsetCalendar.HOUR_OF_DAY
orCalendar.MINUTE
- minute precisionCalendar.SECOND
- second precisionCalendar.MILLISECOND
- fractional second precision
- Throws:
java.lang.IllegalArgumentException
- ifcal
has no appropriate calendar fields set.
-
Timestamp
@Deprecated public Timestamp(java.math.BigDecimal millis, java.lang.Integer localOffset)
Deprecated.UseforMillis(BigDecimal, Integer)
instead.Creates a new Timestamp that represents the point in time that ismillis
milliseconds (including any fractional milliseconds) from the epoch, with a given local offset.The resulting Timestamp will be precise to the second if
millis
doesn't contain information that is more granular than seconds. For example, aBigDecimal
of value 132541995e4 (132541995 × 104) will return a Timestamp of2012-01-01T12:12:30Z
, precise to the second.The resulting Timestamp will be precise to the fractional second if
millis
contains information that is at least granular to milliseconds. For example, aBigDecimal
of value 1325419950555 will return a Timestamp of2012-01-01T12:12:30.555Z
, precise to the fractional second.- Parameters:
millis
- number of milliseconds (including any fractional milliseconds) from the epoch (1970-01-01T00:00:00.000Z); must not benull
localOffset
- the local offset from UTC, measured in minutes; may benull
to represent an unknown local offset- Throws:
java.lang.NullPointerException
- ifmillis
isnull
-
Timestamp
@Deprecated public Timestamp(long millis, java.lang.Integer localOffset)
Deprecated.UseforMillis(long, Integer)
instead.Creates a new Timestamp that represents the point in time that ismillis
milliseconds from the epoch, with a given local offset.The resulting Timestamp will be precise to the fractional second.
- Parameters:
millis
- number of milliseconds from the epoch (1970-01-01T00:00:00.000Z)localOffset
- the local offset from UTC, measured in minutes; may benull
to represent an unknown local offset.
-
-
Method Detail
-
createFromUtcFields
@Deprecated public static Timestamp createFromUtcFields(Timestamp.Precision p, int zyear, int zmonth, int zday, int zhour, int zminute, int zsecond, java.math.BigDecimal frac, java.lang.Integer offset)
Deprecated.Creates a new Timestamp from the individual time components. The individual time components are expected to be in UTC, with the local offset from UTC (i.e.offset
) already applied to the time components. As such, if the givenoffset
is non-null or zero, the resulting Timestamp will have time values that DO NOT match the time parameters. This method also has a behavior of precision "narrowing", detailed in the sub-section below.For example, the following method calls will return Timestamps with values (in its local time) respectively:
createFromUtcFields(Precision.SECOND, 2012, 2, 3, 4, 5, 6, 0.007, null) will return 2012-02-03T04:05:06.007-00:00 (match) createFromUtcFields(Precision.SECOND, 2012, 2, 3, 4, 5, 6, 0.007, 0) will return 2012-02-03T04:05:06.007+00:00 (match) createFromUtcFields(Precision.SECOND, 2012, 2, 3, 4, 5, 6, 0.007, 480) will return 2012-02-03T12:05:06.007+08:00 (do not match) createFromUtcFields(Precision.SECOND, 2012, 2, 3, 4, 5, 6, 0.007, -480) will return 2012-02-02T20:05:06.007-08:00 (do not match) createFromUtcFields(Precision.SECOND, 2012, 2, 3, 4, 5, 6, 0.007, 720) will return 2012-02-03T16:05:06.007+12:00 (do not match) createFromUtcFields(Precision.SECOND, 2012, 2, 3, 4, 5, 6, 0.007, -720) will return 2012-02-02T16:05:06.007-12:00 (do not match)
Note: All of these resulting Timestamps have the similar value (in UTC) 2012-02-03T04:05:06.007Z.Precision "Narrowing"
Any time component that is more precise than the precision parameter
p
will be excluded from the calculation of the resulting Timestamp's point in time.For example, the following method calls will return Timestamps with values respectively:
createFromUtcFields(Precision.YEAR , 2012, 2, 3, 4, 5, 6, 0.007, 0) will return 2012T createFromUtcFields(Precision.MONTH , 2012, 2, 3, 4, 5, 6, 0.007, 0) will return 2012-02T createFromUtcFields(Precision.DAY , 2012, 2, 3, 4, 5, 6, 0.007, 0) will return 2012-02-03T createFromUtcFields(Precision.MINUTE , 2012, 2, 3, 4, 5, 6, 0.007, 0) will return 2012-02-03T04:05Z createFromUtcFields(Precision.SECOND , 2012, 2, 3, 4, 5, 6, null, 0) will return 2012-02-03T04:05:06Z createFromUtcFields(Precision.SECOND , 2012, 2, 3, 4, 5, 6, 0.007, 0) will return 2012-02-03T04:05:06.007Z
- Parameters:
p
- the desired timestamp precision. The result may have a different precision if the input data isn't precise enough.offset
- the local offset from UTC, measured in minutes; may benull
to represent an unknown local offset.
-
valueOf
public static Timestamp valueOf(java.lang.CharSequence ionFormattedTimestamp)
Returns a new Timestamp that represents the point in time, precision and local offset defined in Ion format by theCharSequence
.- Parameters:
ionFormattedTimestamp
- a sequence of characters that is the Ion representation of a Timestamp- Returns:
null
if theCharSequence
is "null.timestamp"- Throws:
java.lang.IllegalArgumentException
- if theCharSequence
is an invalid Ion representation of a Timestamp; or if theCharSequence
has excess characters which are not one of the following valid thirteen numeric-stop characters (escaped accordingly for readability):{}[](),\"\'\ \t\n\r}
- See Also:
- Ion Timestamp Page, W3C Note on Date and Time Formats
-
clone
public Timestamp clone()
Creates a copy of this Timestamp. The resulting Timestamp will represent the same point in time and has the same precision and local offset.- Overrides:
clone
in classjava.lang.Object
-
forYear
public static Timestamp forYear(int yearZ)
Returns a Timestamp, precise to the year, with unknown local offset.This is equivalent to the corresponding Ion value
YYYYT
.
-
forMonth
public static Timestamp forMonth(int yearZ, int monthZ)
Returns a Timestamp, precise to the month, with unknown local offset.This is equivalent to the corresponding Ion value
YYYY-MMT
.
-
forDay
public static Timestamp forDay(int yearZ, int monthZ, int dayZ)
Returns a Timestamp, precise to the day, with unknown local offset.This is equivalent to the corresponding Ion value
YYYY-MM-DD
.
-
forMinute
public static Timestamp forMinute(int year, int month, int day, int hour, int minute, java.lang.Integer offset)
Returns a Timestamp, precise to the minute, with a given local offset.This is equivalent to the corresponding Ion value
YYYY-MM-DDThh:mm+-oo:oo
, whereoo:oo
represents the hour and minutes of the local offset from UTC.The values of the
year
,month
,day
,hour
, andminute
parameters are relative to the localoffset
.- Parameters:
offset
- the local offset from UTC, measured in minutes; may benull
to represent an unknown local offset
-
forSecond
public static Timestamp forSecond(int year, int month, int day, int hour, int minute, int second, java.lang.Integer offset)
Returns a Timestamp, precise to the second, with a given local offset.This is equivalent to the corresponding Ion value
YYYY-MM-DDThh:mm:ss+-oo:oo
, whereoo:oo
represents the hour and minutes of the local offset from UTC.The values of the
year
,month
,day
,hour
,minute
andsecond
parameters are relative to the localoffset
.- Parameters:
offset
- the local offset from UTC, measured in minutes; may benull
to represent an unknown local offset
-
forSecond
public static Timestamp forSecond(int year, int month, int day, int hour, int minute, java.math.BigDecimal second, java.lang.Integer offset)
Returns a Timestamp, precise to the second, with a given local offset.This is equivalent to the corresponding Ion value
YYYY-MM-DDThh:mm:ss.sss+-oo:oo
, whereoo:oo
represents the hour and minutes of the local offset from UTC.The values of the
year
,month
,day
,hour
,minute
andsecond
parameters are relative to the localoffset
.- Parameters:
second
- must be at least zero and less than 60. Must not be null.offset
- the local offset from UTC, measured in minutes; may benull
to represent an unknown local offset
-
forMillis
public static Timestamp forMillis(long millis, java.lang.Integer localOffset)
Returns a Timestamp that represents the point in time that ismillis
milliseconds from the epoch, with a given local offset.The resulting Timestamp will be precise to the millisecond.
millis
is relative to UTC, regardless of the value supplied forlocalOffset
. This varies from theforMinute(int, int, int, int, int, java.lang.Integer)
andforSecond(int, int, int, int, int, int, java.lang.Integer)
methods that assume the specified date and time values are relative to the local offset. For example, the following two Timestamps represent the same point in time:Timestamp theEpoch = Timestamp.forMillis(0, 0); Timestamp alsoTheEpoch = Timestamp.forSecond(1969, 12, 31, 23, 0, BigDecimal.ZERO, -60);
- Parameters:
millis
- the number of milliseconds from the epoch (1970-01-01T00:00:00.000Z) in UTC.localOffset
- the local offset from UTC, measured in minutes; may benull
to represent an unknown local offset.
-
forMillis
public static Timestamp forMillis(java.math.BigDecimal millis, java.lang.Integer localOffset)
The same asforMillis(long, Integer)
but the millisecond component is specified using aBigDecimal
and therefore may include fractional milliseconds.- Parameters:
millis
- number of milliseconds (including any fractional milliseconds) from the epoch (1970-01-01T00:00:00.000Z); must not benull
localOffset
- the local offset from UTC, measured in minutes; may benull
to represent an unknown local offset- Throws:
java.lang.NullPointerException
- ifmillis
isnull
-
forEpochSecond
public static Timestamp forEpochSecond(long seconds, int nanoOffset, java.lang.Integer localOffset)
Returns a Timestamp that represents the point in time that isseconds
from the unix epoch (1970-01-01T00:00:00.000Z), with thenanoOffset
applied and a given local offset.This function is intended to allow easy conversion to Timestamp from Java 8's
java.time.Instant
without having to port this library to Java 8. The following snippet will yield a Timestampts
that equivalent to thejava.time.Instant
i
:Instant i = Instant.now(); Timestamp ts = Timestamp.forEpochSecond(i.getEpochSecond(), i.getNano(), 0);
Like
forMillis(long, java.lang.Integer)
,seconds
is relative to UTC, regardless of the value supplied forlocalOffset
.- Parameters:
seconds
- The number of seconds from the unix epoch (1970-01-01T00:00:00.000Z) UTC.nanoOffset
- The number of nanoseconds for the fractional component. Must be between 0 and 999,999,999.localOffset
- the local offset from UTC, measured in minutes; may benull
to represent an unknown local offset.
-
forCalendar
public static Timestamp forCalendar(java.util.Calendar calendar)
Converts aCalendar
to a Timestamp, preserving the calendar's time zone as the equivalent local offset when it has at least minutes precision.- Returns:
- a Timestamp instance, with precision determined by the smallest
field set in the
Calendar
; ornull
ifcalendar
isnull
-
forDateZ
public static Timestamp forDateZ(java.util.Date date)
Converts aDate
to a Timestamp in UTC representing the same point in time.The resulting Timestamp will be precise to the millisecond.
- Returns:
- a new Timestamp instance, in UTC, precise to the millisecond;
null
ifdate
isnull
-
forSqlTimestampZ
public static Timestamp forSqlTimestampZ(java.sql.Timestamp sqlTimestamp)
Converts aTimestamp
to a Timestamp in UTC representing the same point in time.The resulting Timestamp will be precise to the nanosecond.
- Parameters:
sqlTimestamp
- assumed to have nanoseconds precision- Returns:
- a new Timestamp instance, in UTC, precise to the
nanosecond
null
ifsqlTimestamp
isnull
-
now
public static Timestamp now()
Returns a Timestamp representing the current time (based on the JVM clock), with an unknown local offset.The resulting Timestamp will be precise to the millisecond.
- Returns:
- a new Timestamp instance representing the current time.
-
nowZ
public static Timestamp nowZ()
Returns a Timestamp in UTC representing the current time (based on the the JVM clock).The resulting Timestamp will be precise to the millisecond.
- Returns:
- a new Timestamp instance, in UTC, representing the current time.
-
dateValue
public java.util.Date dateValue()
Converts the value of this Timestamp into aDate
, representing the time in UTC.This method will return the same result for all Timestamps representing the same point in time, regardless of the local offset.
Because
Date
instances are mutable, this method returns a new instance from each call.- Returns:
- a new
Date
instance, in UTC
-
calendarValue
public java.util.Calendar calendarValue()
Converts the value of this Timestamp as aCalendar
, in its local time.Because
Calendar
instances are mutable, this method returns a new instance from each call.- Returns:
- a new
Calendar
instance, in its local time.
-
getMillis
public long getMillis()
Returns a number representing the Timestamp's point in time that is the number of milliseconds (ignoring any fractional milliseconds) from the epoch.This method will return the same result for all Timestamps representing the same point in time, regardless of the local offset.
- Returns:
- number of milliseconds (ignoring any fractional milliseconds) from the epoch (1970-01-01T00:00:00.000Z)
-
getDecimalMillis
public java.math.BigDecimal getDecimalMillis()
Returns a BigDecimal representing the Timestamp's point in time that is the number of milliseconds (including any fractional milliseconds) from the epoch.This method will return the same result for all Timestamps representing the same point in time, regardless of the local offset.
- Returns:
- number of milliseconds (including any fractional milliseconds) from the epoch (1970-01-01T00:00:00.000Z)
-
getPrecision
public Timestamp.Precision getPrecision()
Returns the precision of this Timestamp.
-
getLocalOffset
public java.lang.Integer getLocalOffset()
Returns the offset of this Timestamp, measured in minutes, for the local timezone in UTC.For example, calling this method on Timestamps of:
1969-02-23T07:00+07:00
will return420
1969-02-22T22:45:00.00-01:15
will return-75
1969-02-23
(by Ion's definition, equivalent to1969-02-23T00:00-00:00
) will returnnull
- Returns:
null
if the local offset is unknown (i.e.-00:00
)
-
getYear
public int getYear()
Returns the year of this Timestamp, in its local time.- Returns:
- a number within the range [1, 9999], in its local time
-
getMonth
public int getMonth()
Returns the month of this Timestamp, in its local time.- Returns:
- a number within the range [1, 12], whereby 1 refers to January and 12 refers to December, in its local time; 1 is returned if the Timestamp isn't precise to the month
-
getDay
public int getDay()
Returns the day (within the month) of this Timestamp, in its local time.- Returns:
- a number within the range [1, 31], in its local time; 1 is returned if the Timestamp isn't precise to the day
-
getHour
public int getHour()
Returns the hour of this Timestamp, in its local time.- Returns:
- a number within the range [0, 23], in its local time; 0 is returned if the Timestamp isn't precise to the hour
-
getMinute
public int getMinute()
Returns the minute of this Timestamp, in its local time.- Returns:
- a number within the range [0, 59], in its local time; 0 is returned if the Timestamp isn't precise to the minute
-
getSecond
public int getSecond()
Returns the seconds of this Timestamp, truncated to an integer.Seconds are not affected by local offsets. As such, this method produces the same output as
getZSecond()
.- Returns:
- a number within the range [0, 59]; 0 is returned if the Timestamp isn't precise to the second
- See Also:
getZSecond()
-
getDecimalSecond
public java.math.BigDecimal getDecimalSecond()
Returns the seconds of this Timestamp.Seconds are not affected by local offsets. As such, this method produces the same output as
getZDecimalSecond()
.- Returns:
- a number within the range [0, 60); 0 is returned if the Timestamp isn't precise to the second
- See Also:
getZDecimalSecond()
-
getFractionalSecond
@Deprecated public java.math.BigDecimal getFractionalSecond()
Deprecated.Returns the fractional second of this Timestamp.Fractional seconds are not affected by local offsets. As such, this method produces the same output as
getZFractionalSecond()
.- Returns:
- a BigDecimal within the range [0, 1);
null
is returned if the Timestamp isn't precise to the fractional second - See Also:
Use instead.
-
getZYear
public int getZYear()
Returns the year of this Timestamp, in UTC.- Returns:
- a number within the range [1, 9999], in UTC
-
getZMonth
public int getZMonth()
Returns the month of this Timestamp, in UTC.- Returns:
- a number within the range [1, 12], whereby 1 refers to January and 12 refers to December, in UTC; 1 is returned if the Timestamp isn't precise to the month
-
getZDay
public int getZDay()
Returns the day of this Timestamp, in UTC.- Returns:
- a number within the range [1, 31], in UTC; 1 is returned if the Timestamp isn't precise to the day
-
getZHour
public int getZHour()
Returns the hour of this Timestamp, in UTC.- Returns:
- a number within the range [0, 23], in UTC; 0 is returned if the Timestamp isn't precise to the hour
-
getZMinute
public int getZMinute()
Returns the minute of this Timestamp, in UTC.- Returns:
- a number within the range [0, 59], in UTC; 0 is returned if the Timestamp isn't precise to the minute
-
getZSecond
public int getZSecond()
Returns the second of this Timestamp.Seconds are not affected by local offsets. As such, this method produces the same output as
getSecond()
.- Returns:
- a number within the range [0, 59]; 0 is returned if the Timestamp isn't precise to the second
- See Also:
getSecond()
-
getZDecimalSecond
public java.math.BigDecimal getZDecimalSecond()
Returns the seconds of this Timestamp.Seconds are not affected by local offsets. As such, this method produces the same output as
getDecimalSecond()
.- Returns:
- a number within the range [0, 60); 0 is returned if the Timestamp isn't precise to the second
- See Also:
getDecimalSecond()
-
getZFractionalSecond
@Deprecated public java.math.BigDecimal getZFractionalSecond()
Deprecated.UsegetZDecimalSecond()
instead.Returns the fractional second of this Timestamp.Fractional seconds are not affected by local offsets. As such, this method produces the same output as
getFractionalSecond()
.- Returns:
- a BigDecimal within the range [0, 1);
null
is returned if the Timestamp isn't precise to the fractional second - See Also:
getFractionalSecond()
-
withLocalOffset
public Timestamp withLocalOffset(java.lang.Integer offset)
Returns a timestamp at the same point in time, but with the given local offset. If this timestamp has precision coarser than minutes, then it is returned unchanged since such timestamps always have an unknown offset.
-
toString
public java.lang.String toString()
Returns the string representation (in Ion format) of this Timestamp in its local time.- Overrides:
toString
in classjava.lang.Object
- See Also:
toZString()
,print(Appendable)
-
toZString
public java.lang.String toZString()
Returns the string representation (in Ion format) of this Timestamp in UTC.- See Also:
toString()
,printZ(Appendable)
-
print
public void print(java.lang.Appendable out) throws java.io.IOException
Prints to anAppendable
the string representation (in Ion format) of this Timestamp in its local time.This method produces the same output as
toString()
.- Parameters:
out
- notnull
- Throws:
java.io.IOException
- propagated when theAppendable
throws it- See Also:
printZ(Appendable)
-
printZ
public void printZ(java.lang.Appendable out) throws java.io.IOException
Prints to anAppendable
the string representation (in Ion format) of this Timestamp in UTC.This method produces the same output as
toZString()
.- Parameters:
out
- notnull
- Throws:
java.io.IOException
- propagated when theAppendable
throws it.- See Also:
print(Appendable)
-
adjustMillis
public final Timestamp adjustMillis(long amount)
Returns a timestamp relative to this one by the given number of milliseconds.This method always returns a Timestamp with the same precision as the original. After performing the arithmetic, the resulting Timestamp's seconds value will be truncated to the same fractional precision as the original. For example, adjusting
2012-04-01T00:00:00Z
by one millisecond results in2012-04-01T00:00:00Z
; adjusting2012-04-01T00:00:00.0010Z
by -1 millisecond results in2012-04-01T00:00:00.0000Z
. To extend the precision when the original Timestamp has coarser than SECOND precision and to avoid truncation of the seconds value, useaddSecond(int)
.- Parameters:
amount
- a number of milliseconds.
-
addMillis
public final Timestamp addMillis(long amount)
Returns a timestamp relative to this one by the given number of milliseconds.This method always returns a Timestamp with SECOND precision and a seconds value precise at least to the millisecond. For example, adding one millisecond to
2011T
results in2011-01-01T00:00:00.001-00:00
. To receive a Timestamp that always maintains the same precision as the original, useadjustMillis(long)
. milliseconds.- Parameters:
amount
- a number of milliseconds.
-
adjustSecond
public final Timestamp adjustSecond(int amount)
Returns a timestamp relative to this one by the given number of seconds.This method always returns a Timestamp with the same precision as the original. For example, adjusting
2012-04-01T00:00Z
by one second results in2012-04-01T00:00Z
; adjusting2012-04-01T00:00:00Z
by -1 second results in2012-03-31T23:59:59Z
. To extend the precision when the original Timestamp has coarser than SECOND precision, useaddSecond(int)
.- Parameters:
amount
- a number of seconds.
-
addSecond
public final Timestamp addSecond(int amount)
Returns a timestamp relative to this one by the given number of seconds.This method always returns a Timestamp with SECOND precision. For example, adding one second to
2011T
results in2011-01-01T00:00:01-00:00
. To receive a Timestamp that always maintains the same precision as the original, useadjustSecond(int)
.- Parameters:
amount
- a number of seconds.
-
adjustMinute
public final Timestamp adjustMinute(int amount)
Returns a timestamp relative to this one by the given number of minutes.This method always returns a Timestamp with the same precision as the original. For example, adjusting
2012-04-01T
by one minute results in2012-04-01T
; adjusting2012-04-01T00:00-00:00
by -1 minute results in2012-03-31T23:59-00:00
. To extend the precision when the original Timestamp has coarser than MINUTE precision, useaddMinute(int)
.- Parameters:
amount
- a number of minutes.
-
addMinute
public final Timestamp addMinute(int amount)
Returns a timestamp relative to this one by the given number of minutes.This method always returns a Timestamp with at least MINUTE precision. For example, adding one minute to
2011T
results in2011-01-01T00:01-00:00
. To receive a Timestamp that always maintains the same precision as the original, useadjustMinute(int)
.- Parameters:
amount
- a number of minutes.
-
adjustHour
public final Timestamp adjustHour(int amount)
Returns a timestamp relative to this one by the given number of hours.This method always returns a Timestamp with the same precision as the original. For example, adjusting
2012-04-01T
by one hour results in2012-04-01T
; adjusting2012-04-01T00:00-00:00
by -1 hour results in2012-03-31T23:00-00:00
. To extend the precision when the original Timestamp has coarser than MINUTE precision, useaddHour(int)
.- Parameters:
amount
- a number of hours.
-
addHour
public final Timestamp addHour(int amount)
Returns a timestamp relative to this one by the given number of hours.This method always returns a Timestamp with at least MINUTE precision. For example, adding one hour to
2011T
results in2011-01-01T01:00-00:00
. To receive a Timestamp that always maintains the same precision as the original, useadjustHour(int)
.- Parameters:
amount
- a number of hours.
-
adjustDay
public final Timestamp adjustDay(int amount)
Returns a timestamp relative to this one by the given number of days.This method always returns a Timestamp with the same precision as the original. For example, adjusting
2012-04T
by one day results in2012-04T
; adjusting2012-04-01T
by -1 days results in2012-03-31T
. To extend the precision when the original Timestamp has coarser than DAY precision, useaddDay(int)
.- Parameters:
amount
- a number of days.
-
addDay
public final Timestamp addDay(int amount)
Returns a timestamp relative to this one by the given number of days.- Parameters:
amount
- a number of days.
-
adjustMonth
public final Timestamp adjustMonth(int amount)
Returns a timestamp relative to this one by the given number of months. The day field may be adjusted to account for different month length and leap days.This method always returns a Timestamp with the same precision as the original. For example, adjusting
2011T
by one month results in2011T
; adding 12 months to2011T
results in2012T
. To extend the precision when the original Timestamp has coarser than MONTH precision, useaddMonth(int)
.- Parameters:
amount
- a number of months.
-
addMonth
public final Timestamp addMonth(int amount)
Returns a timestamp relative to this one by the given number of months. The day field may be adjusted to account for different month length and leap days. For example, adding one month to2011-01-31
results in2011-02-28
.- Parameters:
amount
- a number of months.
-
adjustYear
public final Timestamp adjustYear(int amount)
Returns a timestamp relative to this one by the given number of years. The day field may be adjusted to account for leap days. For example, adjusting2012-02-29
by one year results in2013-02-28
.Because YEAR is the coarsest precision possible, this method always returns a Timestamp with the same precision as the original and behaves identically to
addYear(int)
.- Parameters:
amount
- a number of years.
-
addYear
public final Timestamp addYear(int amount)
Returns a timestamp relative to this one by the given number of years. The day field may be adjusted to account for leap days. For example, adding one year to2012-02-29
results in2013-02-28
.- Parameters:
amount
- a number of years.
-
hashCode
public int hashCode()
Returns a hash code consistent withequals(Object)
.- Overrides:
hashCode
in classjava.lang.Object
-
compareTo
public int compareTo(Timestamp t)
Performs a comparison of the two points in time represented by two Timestamps. If the point in time represented by this Timestamp precedes that oft
, then-1
is returned. Ift
precedes this Timestamp then1
is returned. If the Timestamps represent the same point in time, then0
is returned. Note that a0
result does not imply that the two Timestamps areequals(java.lang.Object)
, as the local offset or precision of the two Timestamps may be different.This method is provided in preference to individual methods for each of the six boolean comparison operators (<, ==, >, >=, !=, <=). The suggested idiom for performing these comparisons is:
(x.compareTo(y)
<op>0)
, where <op> is one of the six comparison operators.For example, the pairs below will return a
0
result:2009T
2009-01T
2009-01-01T
2009-01-01T00:00Z
2009-01-01T00:00:00Z
2009-01-01T00:00:00.0Z
2009-01-01T00:00:00.00Z
2008-12-31T16:00-08:00
2008-12-31T12:00-12:00
2009-01-01T12:00+12:00
Use the
equals(Timestamp)
method to compare the point in time, including precision and local offset.- Specified by:
compareTo
in interfacejava.lang.Comparable<Timestamp>
- Parameters:
t
- the otherTimestamp
to compare thisTimestamp
to- Returns:
- -1, 0, or 1 if this
Timestamp
is less than, equal to, or greater thant
respectively - Throws:
java.lang.NullPointerException
- ift
is null.- See Also:
equals(Timestamp)
-
equals
public boolean equals(java.lang.Object t)
Compares thisTimestamp
to the specified Object. The result istrue
if and only if the parameter is aTimestamp
object that represents the same point in time, precision and local offset as this Timestamp.Use the
compareTo(Timestamp)
method to compare only the point in time, ignoring precision and local offset.- Overrides:
equals
in classjava.lang.Object
- See Also:
equals(Timestamp)
,compareTo(Timestamp)
-
equals
public boolean equals(Timestamp t)
Compares thisTimestamp
to anotherTimestamp
object. The result istrue
if and only if the parameter represents the same point in time and has the same precision and local offset as this object.These pairs are
equals(java.lang.Object)
to each other, as they represent the same points in time, precision and local offset:2001-01-01T11:22+00:00
(minute precision, in UTC)2001-01-01T11:22Z
(minute precision, in UTC)
On the other hand, none of these pairs are
equals(java.lang.Object)
to each other, they represent the same points in time, but with different precisions and/or local offsets:2001T
(year precision, unknown local offset)2001-01T
(month precision, unknown local offset)2001-01-01T
(day precision, unknown local offset)2001-01-01T00:00-00:00
(second precision, unknown local offset)2001-01-01T00:00+00:00
(second precision, in UTC)2001-01-01T00:00.000-00:00
(millisecond precision, unknown local offset)2001-01-01T00:00.000+00:00
(millisecond precision, in UTC)
Use the
compareTo(Timestamp)
method to compare only the point in time, ignoring precision and local offset.- See Also:
compareTo(Timestamp)
-
-