Package net.time4j.range

Class MomentInterval

java.lang.Object
net.time4j.range.IsoInterval<Moment,​MomentInterval>
net.time4j.range.MomentInterval
All Implemented Interfaces:
Serializable, ChronoInterval<Moment>
public final class MomentInterval extends IsoInterval<Moment,​MomentInterval> implements Serializable

Defines a moment interval on global timeline.

Since:
2.0
Author:
Meno Hochschild
See Also:
Serialized Form

  • Field Details

  • Method Details

    • comparator

      public static Comparator<ChronoInterval<Moment>> comparator()

      Defines a comparator which sorts intervals first by start boundary and then by length.

      Returns:
      Comparator
      Throws:
      IllegalArgumentException - if applied on intervals which have boundaries with extreme values
      Since:
      2.0

    • between

      public static MomentInterval between​(Moment start, Moment end)

      Creates a finite half-open interval between given time points.

      Parameters:
      start - moment of lower boundary (inclusive)
      end - moment of upper boundary (exclusive)
      Returns:
      new moment interval
      Throws:
      IllegalArgumentException - if start is after end
      Since:
      2.0

    • between

      public static MomentInterval between​(Instant start, Instant end)

      Creates a finite half-open interval between given time points.

      Parameters:
      start - moment of lower boundary (inclusive)
      end - moment of upper boundary (exclusive)
      Returns:
      new moment interval
      Throws:
      IllegalArgumentException - if start is after end
      Since:
      4.11
      See Also:
      between(Moment, Moment)

    • since

      public static MomentInterval since​(Moment start)

      Creates an infinite half-open interval since given start.

      Parameters:
      start - moment of lower boundary (inclusive)
      Returns:
      new moment interval
      Since:
      2.0

    • since

      public static MomentInterval since​(Instant start)

      Creates an infinite half-open interval since given start.

      Parameters:
      start - moment of lower boundary (inclusive)
      Returns:
      new moment interval
      Since:
      4.11
      See Also:
      since(Moment)

    • until

      public static MomentInterval until​(Moment end)

      Creates an infinite open interval until given end.

      Parameters:
      end - moment of upper boundary (exclusive)
      Returns:
      new moment interval
      Since:
      2.0

    • until

      public static MomentInterval until​(Instant end)

      Creates an infinite open interval until given end.

      Parameters:
      end - moment of upper boundary (exclusive)
      Returns:
      new moment interval
      Since:
      4.11
      See Also:
      until(Moment)

    • surrounding

      public static MomentInterval surrounding​(Moment moment, MachineTime<?> duration, double alignment)

      Creates an interval surrounding given moment.

      Alignment:

      • If the alignment is 0.0 then the new interval will start at given moment.
      • If the alignment is 0.5 then the new interval will be centered around given moment.
      • If the alignment is 1.0 then the new interval will end at given moment.
      Parameters:
      moment - embedded moment at focus of alignment
      duration - machine time duration
      alignment - determines how to align the interval around moment (in range 0.0 <= x <= 1.0)
      Returns:
      new moment interval
      Throws:
      IllegalArgumentException - if the duration is negative or the alignment is not finite or out of range
      UnsupportedOperationException - if any given or calculated moment is before 1972 (only for SI-duration)
      Since:
      3.34/4.29
      See Also:
      LEFT_ALIGNED, CENTERED, RIGHT_ALIGNED

    • surrounding

      public static MomentInterval surrounding​(Instant instant, Duration duration, double alignment)

      Creates an interval surrounding given instant.

      Equivalent to surrounding(Moment.from(instant), MachineTime.from(duration), alignment).

      Parameters:
      instant - embedded instant at focus of alignment
      duration - machine time duration
      alignment - determines how to align the interval around instant (in range 0.0 <= x <= 1.0)
      Returns:
      new moment interval
      Throws:
      IllegalArgumentException - if the duration is negative or the alignment is not finite or out of range
      Since:
      4.31
      See Also:
      LEFT_ALIGNED, CENTERED, RIGHT_ALIGNED

    • from

      public static MomentInterval from​(ChronoInterval<Moment> interval)

      Converts an arbitrary moment interval to an interval of this type.

      Parameters:
      interval - any kind of moment interval
      Returns:
      MomentInterval
      Since:
      3.34/4.29

    • getStartAsMoment

      public Moment getStartAsMoment()

      Yields the start time point.

      Returns:
      start time point or null if infinite
      Since:
      4.11
      See Also:
      Boundary.isInfinite()

    • getStartAsInstant

      public Instant getStartAsInstant()

      Yields the start time point.

      Note: Leap seconds will be lost here.

      Returns:
      start time point or null if infinite
      Since:
      4.11
      See Also:
      Boundary.isInfinite()

    • getEndAsMoment

      public Moment getEndAsMoment()

      Yields the end time point.

      Returns:
      end time point or null if infinite
      Since:
      4.11
      See Also:
      Boundary.isInfinite()

    • getEndAsInstant

      public Instant getEndAsInstant()

      Yields the end time point.

      Note: Leap seconds will be lost here.

      Returns:
      end time point or null if infinite
      Since:
      4.11
      See Also:
      Boundary.isInfinite()

    • toLocalInterval

      public TimestampInterval toLocalInterval()

      Converts this instance to a local timestamp interval in the system timezone.

      Returns:
      local timestamp interval in system timezone (leap seconds will always be lost)
      Since:
      2.0
      See Also:
      Timezone.ofSystem(), toZonalInterval(TZID), toZonalInterval(String)

    • toZonalInterval

      public TimestampInterval toZonalInterval​(TZID tzid)

      Converts this instance to a zonal timestamp interval in given timezone.

      Parameters:
      tzid - timezone id
      Returns:
      zonal timestamp interval in given timezone (leap seconds will always be lost)
      Throws:
      IllegalArgumentException - if given timezone cannot be loaded
      Since:
      2.0
      See Also:
      toLocalInterval()

    • toZonalInterval

      public TimestampInterval toZonalInterval​(String tzid)

      Converts this instance to a zonal timestamp interval in given timezone.

      Parameters:
      tzid - timezone id
      Returns:
      zonal timestamp interval in given timezone (leap seconds will always be lost)
      Throws:
      IllegalArgumentException - if given timezone cannot be loaded
      Since:
      2.0
      See Also:
      toZonalInterval(TZID), toLocalInterval()

    • getNominalDuration

      public Duration<IsoUnit> getNominalDuration​(Timezone tz, IsoUnit... units)

      Yields the nominal duration of this interval in given timezone and units.

      Parameters:
      tz - timezone
      units - time units to be used in calculation
      Returns:
      nominal duration
      Throws:
      UnsupportedOperationException - if this interval is infinite
      Since:
      3.0
      See Also:
      getSimpleDuration(), getRealDuration()

    • getSimpleDuration

      public MachineTime<TimeUnit> getSimpleDuration()

      Yields the length of this interval on the POSIX-scale.

      Returns:
      machine time duration on POSIX-scale
      Throws:
      UnsupportedOperationException - if this interval is infinite
      Since:
      2.0
      See Also:
      getRealDuration()

    • getRealDuration

      public MachineTime<SI> getRealDuration()

      Yields the length of this interval on the UTC-scale.

      Returns:
      machine time duration on UTC-scale
      Throws:
      UnsupportedOperationException - if start is before year 1972 or if this interval is infinite
      Since:
      2.0
      See Also:
      getSimpleDuration()

    • move

      public MomentInterval move​(long amount, TimeUnit unit)

      Moves this interval along the POSIX-axis by given time units.

      Parameters:
      amount - amount of units
      unit - time unit for moving
      Returns:
      moved copy of this interval

    • move

      public MomentInterval move​(long amount, SI unit)

      Moves this interval along the UTC-axis by given SI-units.

      Parameters:
      amount - amount of units
      unit - time unit for moving
      Returns:
      moved copy of this interval

    • stream

      public Stream<Moment> stream​(MachineTime<?> duration)

      Obtains a stream iterating over every moment which is the result of addition of given duration to start until the end of this interval is reached.

      The stream size is limited to Integer.MAX_VALUE - 1 else an ArithmeticException will be thrown.

      Parameters:
      duration - duration which has to be added to the start multiple times
      Returns:
      stream consisting of distinct moments which are the result of adding the duration to the start
      Throws:
      IllegalArgumentException - if the duration is not positive
      IllegalStateException - if this interval is infinite or if there is no canonical form
      Since:
      4.35
      See Also:
      IsoInterval.toCanonical(), stream(MachineTime, Moment, Moment)

    • stream

      public static Stream<Moment> stream​(MachineTime<?> duration, Moment start, Moment end)

      Obtains a stream iterating over every moment which is the result of addition of given duration to start until the end is reached.

      This static method avoids the costs of constructing an instance of MomentInterval. The stream size is limited to Integer.MAX_VALUE - 1 else an ArithmeticException will be thrown.

      Parameters:
      duration - duration which has to be added to the start multiple times
      start - start boundary - inclusive
      end - end boundary - exclusive
      Returns:
      stream consisting of distinct moments which are the result of adding the duration to the start
      Throws:
      IllegalArgumentException - if start is after end or if the duration is not positive
      Since:
      4.35

    • random

      public Moment random()

      Obtains a random moment within this interval.

      Returns:
      random moment within this interval
      Throws:
      IllegalStateException - if this interval is infinite or empty or if there is no canonical form
      Since:
      5.0
      See Also:
      IsoInterval.toCanonical()

    • formatISO

      public String formatISO​(IsoDateStyle dateStyle, IsoDecimalStyle decimalStyle, ClockUnit precision, ZonalOffset offset, InfinityStyle infinityStyle)

      Prints the canonical form of this interval in given ISO-8601 style.

      Parameters:
      dateStyle - iso-compatible date style
      decimalStyle - iso-compatible decimal style
      precision - controls the precision of output format with constant length
      offset - timezone offset
      infinityStyle - controlling the format of infinite boundaries
      Returns:
      String
      Throws:
      IllegalStateException - if there is no canonical form or given infinity style prevents infinite intervals
      Since:
      4.18
      See Also:
      IsoInterval.toCanonical()

    • formatReduced

      public String formatReduced​(IsoDateStyle dateStyle, IsoDecimalStyle decimalStyle, ClockUnit precision, ZonalOffset offset, InfinityStyle infinityStyle)

      Prints the canonical form of this interval in given reduced ISO-8601 style.

      The term "reduced" means that higher-order elements like the year can be left out in the end component if it is equal to the value of the start component. And the offset is never printed in the end component of finite intervals. Example: 

           MomentInterval interval =
          MomentInterval.between(
              PlainTimestamp.of(2012, 6, 29, 10, 45),
              PlainTimestamp.of(2012, 6, 30, 23, 59, 59).atUTC().plus(1, SI.SECONDS));
     System.out.println(
          interval.formatReduced(
              IsoDateStyle.EXTENDED_CALENDAR_DATE,
              IsoDecimalStyle.DOT,
              ClockUnit.SECONDS,
              ZonalOffset.UTC,
              InfinityStyle.SYMBOL));
     // Output: 2016-02-29T10:45:00Z/30T23:59:60
      Parameters:
      dateStyle - iso-compatible date style
      decimalStyle - iso-compatible decimal style
      precision - controls the precision of output format with constant length
      offset - timezone offset
      infinityStyle - controlling the format of infinite boundaries
      Returns:
      String
      Throws:
      IllegalStateException - if there is no canonical form or given infinity style prevents infinite intervals
      Since:
      4.18
      See Also:
      IsoInterval.toCanonical()

    • parse

      public static MomentInterval parse​(String text, ChronoParser<Moment> parser) throws ParseException

      Interpretes given text as interval using a localized interval pattern.

      If given parser does not contain a reference to a locale then the interval pattern "{0}/{1}" will be used.

      Parameters:
      text - text to be parsed
      parser - format object for parsing start and end components
      Returns:
      parsed interval
      Throws:
      IndexOutOfBoundsException - if given text is empty
      ParseException - if the text is not parseable
      Since:
      3.9/4.6
      See Also:
      parse(String, ChronoParser, String), FormatPatternProvider.getIntervalPattern(Locale)

    • parse

      public static MomentInterval parse​(String text, ChronoParser<Moment> parser, String intervalPattern) throws ParseException

      Interpretes given text as interval using given interval pattern.

      About usage see also DateInterval.parse(String, ChronoParser, String).

      Parameters:
      text - text to be parsed
      parser - format object for parsing start and end components
      intervalPattern - interval pattern containing placeholders {0} and {1} (for start and end)
      Returns:
      parsed interval
      Throws:
      IndexOutOfBoundsException - if given text is empty
      ParseException - if the text is not parseable
      Since:
      3.9/4.6

    • parse

      public static MomentInterval parse​(CharSequence text, ChronoParser<Moment> parser, BracketPolicy policy) throws ParseException

      Interpretes given text as interval.

      This method can also accept a hyphen as alternative to solidus as separator between start and end component unless the start component is a period. Infinity symbols are understood.

      Parameters:
      text - text to be parsed
      parser - format object for parsing start and end components
      policy - strategy for parsing interval boundaries
      Returns:
      result
      Throws:
      ParseException - if parsing does not work
      IndexOutOfBoundsException - if the start position is at end of text or even behind
      Since:
      4.18

    • parse

      public static MomentInterval parse​(CharSequence text, ChronoParser<Moment> startFormat, char separator, ChronoParser<Moment> endFormat, BracketPolicy policy, ParseLog status)

      Interpretes given text as interval.

      This method is mainly intended for parsing technical interval formats similar to ISO-8601 which are not localized. Infinity symbols are understood.

      Parameters:
      text - text to be parsed
      startFormat - format object for parsing start component
      separator - char separating start and end component
      endFormat - format object for parsing end component
      policy - strategy for parsing interval boundaries
      status - parser information (always as new instance)
      Returns:
      result or null if parsing does not work
      Throws:
      IndexOutOfBoundsException - if the start position is at end of text or even behind
      Since:
      3.9/4.6

    • parseISO

      public static MomentInterval parseISO​(String text) throws ParseException

      Interpretes given ISO-conforming text as interval.

      All styles are supported, namely calendar dates, ordinal dates and week dates, either in basic or in extended format. Mixed date styles for start and end are not allowed however. Furthermore, one of start or end can also be represented by a period string. If not then the end component may exist in an abbreviated form as documented in ISO-8601-paper leaving out higher-order elements like the calendar year (which will be overtaken from the start component instead). In latter case, the timezone offset of the end component is optional, too. Infinity symbols are understood as extension although strictly spoken ISO-8601 does not know or specify infinite intervals. Examples for supported formats: 

        System.out.println(
      MomentInterval.parseISO(
          "2012-01-01T14:15Z/2014-06-20T16:00Z"));
  // output: [2012-01-01T14:15:00Z/2014-06-20T16:00:00Z)

  System.out.println(
      MomentInterval.parseISO(
          "2012-01-01T14:15Z/08-11T16:00+00:01"));
  // output: [2012-01-01T14:15:00Z/2012-08-11T15:59:00Z)

  System.out.println(
      MomentInterval.parseISO(
          "2012-01-01T14:15Z/16:00"));
  // output: [2012-01-01T14:15:00Z/2012-01-01T16:00:00Z)

  System.out.println(
      MomentInterval.parseISO(
          "2012-01-01T14:15Z/P2DT1H45M"));
  // output: [2012-01-01T14:15:00Z/2012-01-03T16:00:00Z)

  System.out.println(
      MomentInterval.parseISO(
          "2015-01-01T08:45Z/-"));
  // output: [2015-01-01T08:45:00Z/+∞)

      This method dynamically creates an appropriate interval format for reduced forms. If performance is more important then a static fixed formatter might be considered.

      Parameters:
      text - text to be parsed
      Returns:
      parsed interval
      Throws:
      IndexOutOfBoundsException - if given text is empty
      ParseException - if the text is not parseable
      Since:
      2.0
      See Also:
      BracketPolicy.SHOW_NEVER