Moment (Time4J-Core 2.0 API)

java.lang.Object
- net.time4j.engine.ChronoEntity<T>
- - net.time4j.engine.TimePoint<TimeUnit,Moment>
  - - net.time4j.Moment

All Implemented Interfaces:

Serializable, Comparable<Moment>, UnixTime, ChronoDisplay, Temporal<UniversalTime>, UniversalTime
```
@CalendarType(value="iso8601")
public final class Moment
extends TimePoint<TimeUnit,Moment>
implements UniversalTime, Temporal<UniversalTime>
```
Represents an instant/moment on the universal timeline with reference to the timezone UTC (UTC+00:00 / Greenwich-meridian).

The JDK-equivalent is traditionally the class java.util.Date. In contrast to that old class this class stores the elapsed time not just in millisecond but in nanosecond precision on 96-bit base.

Following elements which are declared as constants are registered by this class with access in UTC timezone:
- POSIX_TIME
- FRACTION
Furthermore, most local elements like PlainTime.ISO_HOUR etc. registered in class PlainTimestamp or those defined in Weekmodel are indirectly supported via the queries in the interface ZonalElement. A Moment is also capable of delivering the date- and time-values in a different timezone if the method toZonalTimestamp(TZID) is called. If zonal operators are defined by any elements then manipulations of related data are possible in any timezone.

Time arithmetic

The main time units are defined by SI (counting possible UTC-leapseconds) and TimeUnit. Latter unit type can be used if a better interoperability is needed for external APIs which ignore leapseconds. Both kinds of time units can be used in the methods plus(long, unit), minus(long, unit) and until(Moment, unit).
Author:

Meno Hochschild

See Also:
Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`static ChronoElement<Integer>`	`FRACTION` Represents the nano-fraction of current second.
`static ChronoElement<Long>`	`POSIX_TIME` Represents the POSIX-time in seconds since UNIX-epoch.
`static Moment`	`UNIX_EPOCH` Start of UNIX-era = [1970-01-01T00:00:00,000000000Z].

Method Summary

Methods
Modifier and Type	Method and Description
`static TimeAxis<TimeUnit,Moment>`	`axis()` Provides a static access to the associated time axis respective chronology which contains the chronological rules.
`int`	`compareTo(Moment moment)` Compares two time points preferably by their temporal positions on the common time axis.
`boolean`	`equals(Object obj)` Compares the whole state of this instance with given object.
`static ChronoFormatter<Moment>`	`formatter(DisplayMode mode, Locale locale, TZID tzid)` Creates a new formatter which uses the given display mode and locale for formatting and parsing moments in given timezone.
`static ChronoFormatter<Moment>`	`formatter(String formatPattern, ChronoPattern patternType, Locale locale, TZID tzid)` Creates a new formatter which uses the given pattern and locale for formatting and parsing moments in given timezone.
`static ChronoFormatter<Moment>`	`formatterRFC1123()` Defines the RFC-1123-format which is for example used in mail headers.
`static Moment`	`from(UnixTime ut)` Common conversion method.
`long`	`getElapsedTime(TimeScale scale)` Represents this timestamp as elpased seconds on given time scale.
`int`	`getNanosecond()` Yields the nanosecond fraction of current second.
`int`	`getNanosecond(TimeScale scale)` Represents the nanosecond part on the given time scale.
`long`	`getPosixTime()` Counts the seconds elapsed since UNIX epoch [1970-01-01T00:00:00Z] in UTC timezone.
`int`	`hashCode()` Subclasses must redefine this method corresponding to the behaviour of `equals()`.
`ZonalMoment`	`inLocalView()` Creates a combination of this moment and system timezone.
`ZonalMoment`	`inZonalView(String tzid)` Creates a combination of this moment and given timezone.
`ZonalMoment`	`inZonalView(TZID tzid)` Creates a combination of this moment and given timezone.
`boolean`	`isAfter(UniversalTime temporal)` Queries if this object is after given object on a timeline.
`boolean`	`isBefore(UniversalTime temporal)` Queries if this object is before given object on a timeline.
`boolean`	`isLeapSecond()` Queries if this time point is within a positive leapsecond.
`boolean`	`isSimultaneous(UniversalTime temporal)` Queries if this object and given object have the same position on the time axis.
`static ChronoFormatter<Moment>`	`localFormatter(DisplayMode mode)` Creates a new formatter which uses the given display mode in the default locale for formatting and parsing UTC-timestamps.
`static ChronoFormatter<Moment>`	`localFormatter(String formatPattern, ChronoPattern patternType)` Creates a new formatter which uses the given pattern in the default locale for formatting and parsing UTC-timestamps.
`Moment`	`minus(long amount, SI unit)` Subtracts an amount of given SI-unit from this timestamp on the UTC time scale.
`Moment`	`minus(MachineTime<SI> duration)` Subtracts the given machine time duration in SI-seconds from this moment.
`static Moment`	`of(long elapsedTime, int nanosecond, TimeScale scale)` Creates a new UTC-timestamp by given time coordinates on given time scale.
`static Moment`	`of(long elapsedTime, TimeScale scale)` Equivalent to `Moment.of(elapsedTime, 0, scale)`.
`Moment`	`plus(long amount, SI unit)` Adds an amount of given SI-unit to this timestamp on the UTC time scale.
`Moment`	`plus(MachineTime<SI> duration)` Adds the given machine time duration in SI-seconds to this moment.
`PlainTimestamp`	`toLocalTimestamp()` Converts this instance to a local timestamp in the system timezone.
`String`	`toString()` Provides a canonical representation in the ISO-format [yyyy-MM-ddTHH:mm:ss,fffffffffZ].
`String`	`toString(TimeScale scale)` Creates a formatted view of this instance taking in account given time scale.
`PlainTimestamp`	`toZonalTimestamp(String tzid)` Converts this instance to a local timestamp in given timezone.
`PlainTimestamp`	`toZonalTimestamp(TZID tzid)` Converts this instance to a local timestamp in given timezone.
`BigDecimal`	`transform(TimeScale scale)` Represents this timestamp as decimal value in given time scale.
`long`	`until(Moment end, SI unit)` Calculates the time distance between this timestamp and given end timestamp in given SI-unit on the UTC time scale.

Methods inherited from class net.time4j.engine.TimePoint
max, min, minus, minus, plus, plus, until, until

Methods inherited from class net.time4j.engine.ChronoEntity
contains, get, get, getMaximum, getMinimum, getTimezone, hasTimezone, isValid, isValid, isValid, matches, with, with, with, with

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

- Field Detail
  - UNIX_EPOCH
```
public static final Moment UNIX_EPOCH
```
    Start of UNIX-era = [1970-01-01T00:00:00,000000000Z].
  - POSIX_TIME
```
public static final ChronoElement<Long> POSIX_TIME
```
    Represents the POSIX-time in seconds since UNIX-epoch.
    
    Since:
    
    2.0
  - FRACTION
```
public static final ChronoElement<Integer> FRACTION
```
    Represents the nano-fraction of current second.
    
    Since:
    
    2.0
- Method Detail
  - of
```
public static Moment of(long elapsedTime,
        TimeScale scale)
```
    Equivalent to Moment.of(elapsedTime, 0, scale).
    
    Parameters:
    elapsedTime - elapsed seconds on given time scale
    scale - time scale reference
    
    Returns:
    new moment instance
    
    Throws:
    
    IllegalArgumentException - if elapsed time is out of range limits beyond year +/-999,999,999 or out of time scale range
    
    IllegalStateException - if time scale is not POSIX but leap second support is switched off by configuration
    See Also:
    LeapSeconds.isEnabled()
  - of
```
public static Moment of(long elapsedTime,
        int nanosecond,
        TimeScale scale)
```
    Creates a new UTC-timestamp by given time coordinates on given time scale.
    
    The given elapsed time elapsedTime will be internally transformed into the UTC-epochtime, should another time scale than UTC be given. The time scale TAI will only be supported earliest on UTC start 1972-01-01, the time scale GPS earliest on 1980-01-06.
    
    Parameters:
    elapsedTime - elapsed seconds on given time scale
    nanosecond - nanosecond fraction of last second
    scale - time scale reference
    
    Returns:
    new moment instance
    
    Throws:
    
    IllegalArgumentException - if the nanosecond is not in the range 0 <= nanosecond <= 999,999,999 or if elapsed time is out of supported range limits beyond year +/-999,999,999 or out of time scale range
    
    IllegalStateException - if time scale is not POSIX but leap second support is switched off by configuration
    See Also:
    LeapSeconds.isEnabled()
  - from
```
public static Moment from(UnixTime ut)
```
    Common conversion method.
    
    Parameters:
    ut - UNIX-timestamp
    
    Returns:
    corresponding Moment
  - getPosixTime
```
public long getPosixTime()
```
    Description copied from interface: UnixTime
    
    Counts the seconds elapsed since UNIX epoch [1970-01-01T00:00:00Z] in UTC timezone.
    
    Specified by:
    
    getPosixTime in interface UnixTime
    
    Returns:
    count of seconds since UNIX-epoch at [1970-01-01T00:00:00Z] without leap seconds in the timezone UTC (Greenwich)
  - getElapsedTime
```
public long getElapsedTime(TimeScale scale)
```
    Description copied from interface: UniversalTime
    
    Represents this timestamp as elpased seconds on given time scale.
    
    The method getPosixTime() inherited from UnixTime is equivalent to getElapsedTime(TimeScale.POSIX) and relates to the UNIX-epoch 1970-01-01. The time scale UTC starts two years later however and also counts leapseconds.
    
    Specified by:
    
    getElapsedTime in interface UniversalTime
    
    Parameters:
    scale - time scale reference
    
    Returns:
    elapsed seconds in given time scale
  - getNanosecond
```
public int getNanosecond()
```
    Description copied from interface: UnixTime
    
    Yields the nanosecond fraction of current second.
    
    As time unit, the nanosecond is defined as one billionth part of a second).
    
    Specified by:
    
    getNanosecond in interface UnixTime
    
    Returns:
    count of nanoseconds as fraction of last second in the range 0 - 999.999.999
  - getNanosecond
```
public int getNanosecond(TimeScale scale)
```
    Description copied from interface: UniversalTime
    
    Represents the nanosecond part on the given time scale.
    
    The method with the same name and without argument inherited from super interface UnixTime is identical to this method if the time scale is either POSIX or UTC.
    
    Specified by:
    
    getNanosecond in interface UniversalTime
    
    Parameters:
    scale - time scale reference
    
    Returns:
    nanosecond fraction in given time scale
  - isLeapSecond
```
public boolean isLeapSecond()
```
    Description copied from interface: UniversalTime
    
    Queries if this time point is within a positive leapsecond.
    
    If the support for UTC-leapseconds is switched off per configuration then this method will always yield false.
    
    Specified by:
    
    isLeapSecond in interface UniversalTime
    
    Returns:
    true if this instance represents a positive leap second else false
    See Also:
    LeapSeconds.isEnabled()
  - transform
```
public BigDecimal transform(TimeScale scale)
```
    Represents this timestamp as decimal value in given time scale.
    
    Parameters:
    scale - time scale reference
    
    Returns:
    decimal value in given time scale as seconds inclusive fraction
    
    Throws:
    
    IllegalArgumentException - if this instance is out of range for given time scale
  - isAfter
```
public boolean isAfter(UniversalTime temporal)
```
    Description copied from interface: Temporal
    
    Queries if this object is after given object on a timeline.
    
    Specified by:
    
    isAfter in interface Temporal<UniversalTime>
    
    Parameters:
    temporal - object this instance is compared to
    
    Returns:
    true if this instance is temporally after temporal else false
  - isBefore
```
public boolean isBefore(UniversalTime temporal)
```
    Description copied from interface: Temporal
    
    Queries if this object is before given object on a timeline.
    
    Specified by:
    
    isBefore in interface Temporal<UniversalTime>
    
    Parameters:
    temporal - object this instance is compared to
    
    Returns:
    true if this instance is temporally before temporal else false
  - isSimultaneous
```
public boolean isSimultaneous(UniversalTime temporal)
```
    Description copied from interface: Temporal
    
    Queries if this object and given object have the same position on the time axis.
    
    Is equivalent to !isAfter(temporal) && !isBefore(temporal). This method differs from the Object-method equals() such that first the comparison type must be a temporal one and second that only temporal-only state will be considered.
    
    Specified by:
    
    isSimultaneous in interface Temporal<UniversalTime>
    
    Parameters:
    temporal - object this instance is compared to
    
    Returns:
    true if this instance is temporally equal to temporal else false
  - toLocalTimestamp
```
public PlainTimestamp toLocalTimestamp()
```
    Converts this instance to a local timestamp in the system timezone.
    
    Returns:
    local timestamp in system timezone (leap seconds will always be lost)
    Since:
    
    1.2
    
    See Also:
    Timezone.ofSystem(), toZonalTimestamp(TZID), toZonalTimestamp(String)
  - toZonalTimestamp
```
public PlainTimestamp toZonalTimestamp(TZID tzid)
```
    Converts this instance to a local timestamp in given timezone.
    
    Parameters:
    tzid - timezone id
    
    Returns:
    local timestamp in given timezone (leap seconds will always be lost)
    
    Throws:
    
    IllegalArgumentException - if given timezone cannot be loaded
    Since:
    
    1.2
    
    See Also:
    toLocalTimestamp()
  - toZonalTimestamp
```
public PlainTimestamp toZonalTimestamp(String tzid)
```
    Converts this instance to a local timestamp in given timezone.
    
    Parameters:
    tzid - timezone id
    
    Returns:
    local timestamp in given timezone (leap seconds will always be lost)
    
    Throws:
    
    IllegalArgumentException - if given timezone cannot be loaded
    Since:
    
    1.2
    
    See Also:
    toZonalTimestamp(TZID), toLocalTimestamp()
  - inLocalView
```
public ZonalMoment inLocalView()
```
    Creates a combination of this moment and system timezone.
    
    A direct conversion to a local timestamp can be achieved by toLocalTimestamp().
    
    Returns:
    moment in system timezone
    
    Throws:
    
    IllegalArgumentException - if this moment is a leapsecond and shall be combined with a non-full-minute-timezone-offset
    Since:
    
    2.0
  - inZonalView
```
public ZonalMoment inZonalView(TZID tzid)
```
    Creates a combination of this moment and given timezone.
    
    A direct conversion to a zonal timestamp can be achieved by toZonalTimestamp(TZID).
    
    Returns:
    moment in given timezone
    
    Throws:
    
    IllegalArgumentException - if this moment is a leapsecond and shall be combined with a non-full-minute-timezone-offset or if given timezone cannot be loaded
    Since:
    
    2.0
  - inZonalView
```
public ZonalMoment inZonalView(String tzid)
```
    Creates a combination of this moment and given timezone.
    
    A direct conversion to a zonal timestamp can be achieved by toZonalTimestamp(String).
    
    Returns:
    moment in given timezone
    
    Throws:
    
    IllegalArgumentException - if this moment is a leapsecond and shall be combined with a non-full-minute-timezone-offset or if given timezone cannot be loaded
    Since:
    
    2.0
  - plus
```
public Moment plus(long amount,
          SI unit)
```
    Adds an amount of given SI-unit to this timestamp on the UTC time scale.
    
    Parameters:
    amount - amount in units to be added
    unit - time unit defined in UTC time space
    
    Returns:
    changed copy of this instance
    
    Throws:
    
    UnsupportedOperationException - if either this moment or the result are before 1972
    
    ArithmeticException - in case of overflow
    
    IllegalArgumentException - if new moment is out of range limits
  - minus
```
public Moment minus(long amount,
           SI unit)
```
    Subtracts an amount of given SI-unit from this timestamp on the UTC time scale.
    
    Parameters:
    amount - amount in SI-units to be subtracted
    unit - time unit defined in UTC time space
    
    Returns:
    changed copy of this instance
    
    Throws:
    
    UnsupportedOperationException - if either this moment or the result are before 1972
    
    ArithmeticException - in case of overflow
  - plus
```
public Moment plus(MachineTime<SI> duration)
```
    Adds the given machine time duration in SI-seconds to this moment.
    
    Parameters:
    duration - machine time in SI-seconds
    
    Returns:
    result of addition
    
    Throws:
    
    UnsupportedOperationException - if either this moment or the result are before 1972
    
    ArithmeticException - in case of overflow
    Since:
    
    2.0
  - minus
```
public Moment minus(MachineTime<SI> duration)
```
    Subtracts the given machine time duration in SI-seconds from this moment.
    
    Parameters:
    duration - machine time in SI-seconds
    
    Returns:
    result of subtraction
    
    Throws:
    
    UnsupportedOperationException - if either this moment or the result are before 1972
    
    ArithmeticException - in case of overflow
    Since:
    
    2.0
  - until
```
public long until(Moment end,
         SI unit)
```
    Calculates the time distance between this timestamp and given end timestamp in given SI-unit on the UTC time scale.
    
    Parameters:
    end - end time point
    unit - time unit defined in UTC time space
    
    Returns:
    count of SI-units between this instance and end time point
    
    Throws:
    
    UnsupportedOperationException - if any moment is before 1972
  - localFormatter
```
public static ChronoFormatter<Moment> localFormatter(String formatPattern,
                                     ChronoPattern patternType)
```
    Creates a new formatter which uses the given pattern in the default locale for formatting and parsing UTC-timestamps.
    
    Note: The formatter can be adjusted to other locales and timezones however.
    
    Parameters:
    formatPattern - format definition as pattern
    patternType - pattern dialect
    
    Returns:
    format object for formatting Moment-objects using system locale and system timezone
    
    Throws:
    
    IllegalArgumentException - if resolving of pattern fails
    See Also:
    PatternType, ChronoFormatter.with(Locale), ChronoFormatter.withTimezone(net.time4j.tz.TZID)
  - localFormatter
```
public static ChronoFormatter<Moment> localFormatter(DisplayMode mode)
```
    Creates a new formatter which uses the given display mode in the default locale for formatting and parsing UTC-timestamps.
    
    Note: The formatter can be adjusted to other locales and timezones however.
    
    Parameters:
    mode - formatting style
    
    Returns:
    format object for formatting Moment-objects using system locale and system timezone
    
    Throws:
    
    IllegalStateException - if format pattern cannot be retrieved
    See Also:
    ChronoFormatter.with(Locale), ChronoFormatter.withTimezone(net.time4j.tz.TZID)
  - formatter
```
public static ChronoFormatter<Moment> formatter(String formatPattern,
                                ChronoPattern patternType,
                                Locale locale,
                                TZID tzid)
```
    Creates a new formatter which uses the given pattern and locale for formatting and parsing moments in given timezone.
    
    Note: The given timezone will be used in printing while it serves as replacement value during parsing (if the text is missing a timezone information). The formatter can be adjusted to other locales and timezones however.
    
    Parameters:
    formatPattern - format definition as pattern
    patternType - pattern dialect
    locale - locale setting
    tzid - timezone id
    
    Returns:
    format object for formatting Moment-objects using given locale and timezone
    
    Throws:
    
    IllegalArgumentException - if resolving of pattern fails
    Since:
    
    2.0
    
    See Also:
    PatternType, localFormatter(String,ChronoPattern), ChronoFormatter.with(Locale), ChronoFormatter.withTimezone(TZID)
  - formatter
```
public static ChronoFormatter<Moment> formatter(DisplayMode mode,
                                Locale locale,
                                TZID tzid)
```
    Creates a new formatter which uses the given display mode and locale for formatting and parsing moments in given timezone.
    
    Note: The given timezone will be used in printing while it serves as replacement value during parsing (if the text is missing a timezone information). The formatter can be adjusted to other locales and timezones however.
    
    Parameters:
    mode - formatting style
    locale - locale setting
    tzid - timezone id
    
    Returns:
    format object for formatting Moment-objects using given locale
    
    Throws:
    
    IllegalStateException - if format pattern cannot be retrieved
    Since:
    
    2.0
    
    See Also:
    localFormatter(DisplayMode), ChronoFormatter.with(Locale), ChronoFormatter.withTimezone(TZID)
  - formatterRFC1123
```
public static ChronoFormatter<Moment> formatterRFC1123()
```
    Defines the RFC-1123-format which is for example used in mail headers.
    
    Equivalent to the pattern "[EEE, ]d MMM yyyy HH:mm[:ss] XX" where the timezone offset XX is modified such that in case of zero offset the expression "GMT" is preferred. As zero offset will also be accepted "UT" or "Z". The text elements will always be interpreted in English and are case-insensitive.
    
    Note: In contrast to the RFC-1123-standard this method does not support military timezone abbreviations (A-Y) or north-american timezone names (EST, EDT, CST, CDT, MST, MDT, PST, PDT).
    
    Returns:
    formatter object for RFC-1123 (technical internet-timestamp)
  - compareTo
```
public int compareTo(Moment moment)
```
    Description copied from class: TimePoint
    
    Compares two time points preferably by their temporal positions on the common time axis.
    
    Implementation note: In order to make the natural order consistent with equals() the whole state must be taken into account, with preference for those attributes which define the temporal position on the time axis.
    
    Specified by:
    
    compareTo in interface Comparable<Moment>
    
    Specified by:
    
    compareTo in class TimePoint<TimeUnit,Moment>
    
    See Also:
    TimePoint.equals(Object)
  - equals
```
public boolean equals(Object obj)
```
    Description copied from class: TimePoint
    
    Compares the whole state of this instance with given object.
    
    Implementations will usually define their state only based on the temporal position on the time axis because this is the most intuitive approach. Exceptions from this rule should be explicitly documented and reasoned.
    
    Specified by:
    
    equals in class TimePoint<TimeUnit,Moment>
    
    See Also:
    TimePoint.compareTo(TimePoint)
  - hashCode
```
public int hashCode()
```
    Description copied from class: TimePoint
    
    Subclasses must redefine this method corresponding to the behaviour of equals().
    
    Specified by:
    
    hashCode in class TimePoint<TimeUnit,Moment>
  - toString
```
public String toString()
```
    Provides a canonical representation in the ISO-format [yyyy-MM-ddTHH:mm:ss,fffffffffZ].
    
    The fraction will only be printed if not zero. Example: The expression Moment.of(1341100824, 210, TimeScale.UTC) has the representation "2012-06-30T23:59:60,000000210Z".
    
    Specified by:
    
    toString in class TimePoint<TimeUnit,Moment>
    
    Returns:
    ISO-8601-formatted string
  - toString
```
public String toString(TimeScale scale)
```
    Creates a formatted view of this instance taking in account given time scale.
```
  Moment moment =
      PlainDate.of(2012, Month.JUNE, 30)
      .at(PlainTime.of(23, 59, 59, 999999999))
      .atUTC()
      .plus(1, SI.SECONDS); // move to leap second

  System.out.println(moment.toString(TimeScale.POSIX));
  // Output: POSIX-2012-06-30T23:59:59,999999999Z

  System.out.println(moment.toString(TimeScale.UTC));
  // Output: UTC-2012-06-30T23:59:60,999999999Z

  System.out.println(moment.toString(TimeScale.TAI));
  // Output: TAI-2012-07-01T00:00:34,999999999Z

  System.out.println(moment.toString(TimeScale.GPS));
  // Output: GPS-2012-07-01T00:00:15,999999999Z
 
```
    Parameters:
    scale - time scale to be used for formatting
    
    Returns:
    formatted string with date-time fields in timezone UTC
    
    Throws:
    
    IllegalArgumentException - if this instance is out of range for given time scale
    See Also:
    getElapsedTime(TimeScale)
  - axis
```
public static TimeAxis<TimeUnit,Moment> axis()
```
    Provides a static access to the associated time axis respective chronology which contains the chronological rules.
    
    Returns:
    chronological system as time axis (never null)

Class Moment

Time arithmetic

Field Summary

Method Summary

Methods inherited from class net.time4j.engine.TimePoint

Methods inherited from class net.time4j.engine.ChronoEntity

Methods inherited from class java.lang.Object

Field Detail

UNIX_EPOCH

POSIX_TIME

FRACTION

Method Detail

of

of

from

getPosixTime

getElapsedTime

getNanosecond

getNanosecond

isLeapSecond

transform

isAfter

isBefore

isSimultaneous

toLocalTimestamp

toZonalTimestamp

toZonalTimestamp

inLocalView

inZonalView

inZonalView

plus

minus

plus

minus

until

localFormatter

localFormatter

formatter

formatter

formatterRFC1123

compareTo

equals

hashCode

toString

toString

axis