Timestamp (ion-java 1.11.7 API)

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 with IonValue classes, the equals 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 two Timestamp instances that represent the same point in time but are not equals.
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 of Comparable 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 from compareTo(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 and Description

static class Timestamp.Precision
The precision of the Timestamp.

Nested Classes
Modifier and Type	Class and Description
`static class`	`Timestamp.Precision` The precision of the Timestamp.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`DEFAULT_MAXIMUM_DIGITS_TEXT` The default maximum number of digits in the fractional component that will be written when a text representation of a timestamp is requested.
`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 and Description
`Timestamp(java.math.BigDecimal millis, java.lang.Integer localOffset)` Deprecated. Use `forMillis(BigDecimal, Integer)` instead.
`Timestamp(java.util.Calendar cal)` Deprecated. Use `forCalendar(Calendar)` instead.
`Timestamp(int zyear, int zmonth, int zday)` Deprecated. Use `forDay(int, int, int)` instead.
`Timestamp(int year, int month, int day, int hour, int minute, int second, java.math.BigDecimal frac, java.lang.Integer offset)` Deprecated. Use `forSecond(int, int, int, int, int, BigDecimal, Integer)` instead.
`Timestamp(int year, int month, int day, int hour, int minute, java.lang.Integer offset)` Deprecated. Use `forMinute(int, int, int, int, int, Integer)` instead.
`Timestamp(int year, int month, int day, int hour, int minute, int second, java.lang.Integer offset)` Deprecated. Use `forSecond(int, int, int, int, int, int, Integer)` instead.
`Timestamp(long millis, java.lang.Integer localOffset)` Deprecated. Use `forMillis(long, Integer)` instead.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and 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 a `Calendar`, 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 a `Date`, representing the time in UTC.
`boolean`	`equals(java.lang.Object t)` Compares this `Timestamp` to the specified Object.
`boolean`	`equals(Timestamp t)` Compares this `Timestamp` to another `Timestamp` object.
`static Timestamp`	`forCalendar(java.util.Calendar calendar)` Converts a `Calendar` 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 a `Date` 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 is `seconds` from the unix epoch (1970-01-01T00:00:00.000Z), with the `nanoOffset` applied and a given local offset.
`static Timestamp`	`forMillis(java.math.BigDecimal millis, java.lang.Integer localOffset)` The same as `forMillis(long, Integer)` but the millisecond component is specified using a `BigDecimal` and therefore may include fractional milliseconds.
`static Timestamp`	`forMillis(long millis, java.lang.Integer localOffset)` Returns a Timestamp that represents the point in time that is `millis` milliseconds from the epoch, with a given local offset.
`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, java.math.BigDecimal 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, int 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 a `Timestamp` 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. Use `getZDecimalSecond()` 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 with `equals(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 an `Appendable` the string representation (in Ion format) of this Timestamp in its local time.
`void`	`printZ(java.lang.Appendable out)` Prints to an `Appendable` 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 the `CharSequence`.
`Timestamp`	`withLocalOffset(java.lang.Integer offset)` Returns a timestamp at the same point in time, but with the given local offset.

Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - UNKNOWN_OFFSET
```
public static final java.lang.Integer UNKNOWN_OFFSET
```
    Unknown local offset from UTC.
  - UTC_OFFSET
```
public static final java.lang.Integer UTC_OFFSET
```
    Local offset of zero hours from UTC.
  - DEFAULT_MAXIMUM_DIGITS_TEXT
```
public static final int DEFAULT_MAXIMUM_DIGITS_TEXT
```
    The default maximum number of digits in the fractional component that will be written when a text representation of a timestamp is requested. If more precision is needed, timestamps can be serialized using a text IonWriter configured with IonTextWriterBuilder.withMaximumTimestampPrecisionDigits(int).
    
    See Also:
    
    toString(), toZString(), print(Appendable), printZ(Appendable), Constant Field Values
- Constructor Detail
  - Timestamp
```
@Deprecated
public Timestamp(int zyear,
                             int zmonth,
                             int zday)
```
    Deprecated. Use forDay(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. Use forMinute(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, where oo:oo represents the hour and minutes of the local offset from UTC.
    
    Parameters:
    
    offset - the local offset from UTC, measured in minutes; may be null 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. Use forSecond(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, where oo:oo represents the hour and minutes of the local offset from UTC.
    
    Parameters:
    
    offset - the local offset from UTC, measured in minutes; may be null 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. Use forSecond(int, int, int, int, int, BigDecimal, Integer) instead.
    
    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, where oo:oo represents the hour and minutes of the local offset from UTC, and fff represents the fractional seconds.
    
    Parameters:
    
    frac - the fractional seconds; must not be null; if negative, its absolute value is used
    
    offset - the local offset from UTC, measured in minutes; may be null to represent an unknown local offset
    
    Throws:
    
    java.lang.NullPointerException - if frac is null
  - Timestamp
```
@Deprecated
public Timestamp(java.util.Calendar cal)
```
    Deprecated. Use forCalendar(Calendar) instead.
    Creates a new Timestamp from a Calendar, preserving the Calendar'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 offset
    - Calendar.MONTH - month precision, unknown local offset
    - Calendar.DAY_OF_MONTH - day precision, unknown local offset
    - Calendar.HOUR_OF_DAY or Calendar.MINUTE - minute precision
    - Calendar.SECOND - second precision
    - Calendar.MILLISECOND - fractional second precision
    Throws:
    
    java.lang.IllegalArgumentException - if cal has no appropriate calendar fields set.
  - Timestamp
```
@Deprecated
public Timestamp(java.math.BigDecimal millis,
                             java.lang.Integer localOffset)
```
    Deprecated. Use forMillis(BigDecimal, Integer) instead.
    
    Creates a new Timestamp that represents the point in time that is millis 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, a BigDecimal of value 132541995e4 (132541995 × 10⁴) will return a Timestamp of 2012-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, a BigDecimal of value 1325419950555 will return a Timestamp of 2012-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 be null
    
    localOffset - the local offset from UTC, measured in minutes; may be null to represent an unknown local offset
    
    Throws:
    
    java.lang.NullPointerException - if millis is null
  - Timestamp
```
@Deprecated
public Timestamp(long millis,
                             java.lang.Integer localOffset)
```
    Deprecated. Use forMillis(long, Integer) instead.
    
    Creates a new Timestamp that represents the point in time that is millis 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 be null 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 given offset 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 be null 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 the CharSequence.
    
    Parameters:
    
    ionFormattedTimestamp - a sequence of characters that is the Ion representation of a Timestamp
    
    Returns:
    
    null if the CharSequence is "null.timestamp"
    
    Throws:
    
    java.lang.IllegalArgumentException - if the CharSequence is an invalid Ion representation of a Timestamp; or if the CharSequence 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 class java.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, where oo:oo represents the hour and minutes of the local offset from UTC.
    
    The values of the year, month, day, hour, and minute parameters are relative to the local offset.
    
    Parameters:
    
    offset - the local offset from UTC, measured in minutes; may be null 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, where oo:oo represents the hour and minutes of the local offset from UTC.
    
    The values of the year, month, day, hour, minute and second parameters are relative to the local offset.
    
    Parameters:
    
    offset - the local offset from UTC, measured in minutes; may be null 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, where oo:oo represents the hour and minutes of the local offset from UTC.
    
    The values of the year, month, day, hour, minute and second parameters are relative to the local offset.
    
    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 be null 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 is millis 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 for localOffset. This varies from the forMinute(int, int, int, int, int, java.lang.Integer) and forSecond(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 be null to represent an unknown local offset.
  - forMillis
```
public static Timestamp forMillis(java.math.BigDecimal millis,
                                  java.lang.Integer localOffset)
```
    The same as forMillis(long, Integer) but the millisecond component is specified using a BigDecimal 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 be null
    
    localOffset - the local offset from UTC, measured in minutes; may be null to represent an unknown local offset
    
    Throws:
    
    java.lang.NullPointerException - if millis is null
  - forEpochSecond
```
public static Timestamp forEpochSecond(long seconds,
                                       int nanoOffset,
                                       java.lang.Integer localOffset)
```
    Returns a Timestamp that represents the point in time that is seconds from the unix epoch (1970-01-01T00:00:00.000Z), with the nanoOffset 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 Timestamp ts that equivalent to the java.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 for localOffset.
    
    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 be null to represent an unknown local offset.
  - forCalendar
```
public static Timestamp forCalendar(java.util.Calendar calendar)
```
    Converts a Calendar 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; or null if calendar is null
  - forDateZ
```
public static Timestamp forDateZ(java.util.Date date)
```
    Converts a Date 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 if date is null
  - forSqlTimestampZ
```
public static Timestamp forSqlTimestampZ(java.sql.Timestamp sqlTimestamp)
```
    Converts a Timestamp 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 if sqlTimestamp is null
  - 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 a Date, 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 a Calendar, 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 return 420
    - 1969-02-22T22:45:00.00-01:15 will return -75
    - 1969-02-23 (by Ion's definition, equivalent to 1969-02-23T00:00-00:00) will return null
    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 {@link #getDecimalSecond()} 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. Use getZDecimalSecond() 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 class java.lang.Object
    
    Throws:
    
    IonException - if the text representation of the timestamp requires more than DEFAULT_MAXIMUM_DIGITS_TEXT.
    
    See Also:
    
    toZString(), print(Appendable)
  - toZString
```
public java.lang.String toZString()
```
    Returns the string representation (in Ion format) of this Timestamp in UTC.
    
    Throws:
    
    IonException - if the text representation of the timestamp requires more than DEFAULT_MAXIMUM_DIGITS_TEXT.
    
    See Also:
    
    toString(), printZ(Appendable)
  - print
```
public void print(java.lang.Appendable out)
           throws java.io.IOException
```
    Prints to an Appendable the string representation (in Ion format) of this Timestamp in its local time.
    This method produces the same output as toString().
    
    Parameters:
    
    out - not null
    
    Throws:
    
    java.io.IOException - propagated when the Appendable throws it
    
    IonException - if the text representation of the timestamp requires more than DEFAULT_MAXIMUM_DIGITS_TEXT.
    
    See Also:
    
    printZ(Appendable)
  - printZ
```
public void printZ(java.lang.Appendable out)
            throws java.io.IOException
```
    Prints to an Appendable the string representation (in Ion format) of this Timestamp in UTC.
    This method produces the same output as toZString().
    
    Parameters:
    
    out - not null
    
    Throws:
    
    java.io.IOException - propagated when the Appendable throws it.
    
    IonException - if the text representation of the timestamp requires more than DEFAULT_MAXIMUM_DIGITS_TEXT.
    
    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 in 2012-04-01T00:00:00Z; adjusting 2012-04-01T00:00:00.0010Z by -1 millisecond results in 2012-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, use addSecond(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 in 2011-01-01T00:00:00.001-00:00. To receive a Timestamp that always maintains the same precision as the original, use adjustMillis(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 in 2012-04-01T00:00Z; adjusting 2012-04-01T00:00:00Z by -1 second results in 2012-03-31T23:59:59Z. To extend the precision when the original Timestamp has coarser than SECOND precision, use addSecond(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 in 2011-01-01T00:00:01-00:00. To receive a Timestamp that always maintains the same precision as the original, use adjustSecond(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 in 2012-04-01T; adjusting 2012-04-01T00:00-00:00 by -1 minute results in 2012-03-31T23:59-00:00. To extend the precision when the original Timestamp has coarser than MINUTE precision, use addMinute(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 in 2011-01-01T00:01-00:00. To receive a Timestamp that always maintains the same precision as the original, use adjustMinute(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 in 2012-04-01T; adjusting 2012-04-01T00:00-00:00 by -1 hour results in 2012-03-31T23:00-00:00. To extend the precision when the original Timestamp has coarser than MINUTE precision, use addHour(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 in 2011-01-01T01:00-00:00. To receive a Timestamp that always maintains the same precision as the original, use adjustHour(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 in 2012-04T; adjusting 2012-04-01T by -1 days results in 2012-03-31T. To extend the precision when the original Timestamp has coarser than DAY precision, use addDay(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 in 2011T; adding 12 months to 2011T results in 2012T. To extend the precision when the original Timestamp has coarser than MONTH precision, use addMonth(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 to 2011-01-31 results in 2011-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, adjusting 2012-02-29 by one year results in 2013-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 to 2012-02-29 results in 2013-02-28.
    
    Parameters:
    
    amount - a number of years.
  - hashCode
```
public int hashCode()
```
    Returns a hash code consistent with equals(Object).
    
    Overrides:
    
    hashCode in class java.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 of t, then -1 is returned. If t precedes this Timestamp then 1 is returned. If the Timestamps represent the same point in time, then 0 is returned. Note that a 0 result does not imply that the two Timestamps are equals(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 interface java.lang.Comparable<Timestamp>
    
    Parameters:
    
    t - the other Timestamp to compare this Timestamp to
    
    Returns:
    
    -1, 0, or 1 if this Timestamp is less than, equal to, or greater than t respectively
    
    Throws:
    
    java.lang.NullPointerException - if t is null.
    
    See Also:
    
    equals(Timestamp)
  - equals
```
public boolean equals(java.lang.Object t)
```
    Compares this Timestamp to the specified Object. The result is true if and only if the parameter is a Timestamp 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 class java.lang.Object
    
    See Also:
    
    equals(Timestamp), compareTo(Timestamp)
  - equals
```
public boolean equals(Timestamp t)
```
    Compares this Timestamp to another Timestamp object. The result is true 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)

Class Timestamp

Equality and Comparison

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

UNKNOWN_OFFSET

UTC_OFFSET

DEFAULT_MAXIMUM_DIGITS_TEXT

Constructor Detail

Timestamp

Timestamp

Timestamp

Timestamp

Timestamp

Timestamp

Timestamp

Method Detail

createFromUtcFields

Precision "Narrowing"

valueOf

clone

forYear

forMonth

forDay

forMinute

forSecond

forSecond

forMillis

forMillis

forEpochSecond

forCalendar

forDateZ

forSqlTimestampZ

now

nowZ

dateValue

calendarValue

getMillis

getDecimalMillis

getPrecision

getLocalOffset

getYear

getMonth

getDay

getHour

getMinute

getSecond

getDecimalSecond

getFractionalSecond

getZYear

getZMonth

getZDay

getZHour

getZMinute

getZSecond

getZDecimalSecond

getZFractionalSecond

withLocalOffset

toString

toZString

print

printZ

adjustMillis

addMillis

adjustSecond

addSecond

adjustMinute

addMinute

adjustHour

addHour

adjustDay

addDay

adjustMonth

addMonth

adjustYear

addYear

hashCode