Package net.time4j.range

Class ClockInterval

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

Defines a finite wall time interval on the local timeline.

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

  • Field Details

    • FULL_DAY

      public static final ClockInterval FULL_DAY

      Represents the full day from 00:00 inclusive to 24:00 exclusive.

      Since:
      5.4

  • Method Details

    • comparator

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

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

      Returns:
      Comparator
      Since:
      2.0

    • between

      public static ClockInterval between​(PlainTime start, PlainTime end)

      Creates a finite half-open interval between given wall times.

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

    • between

      public static ClockInterval between​(LocalTime start, LocalTime end)

      Creates a finite half-open interval between given wall times.

      For better handling of time 24:00, it is recommended to directly use the overloaded variant with arguments of type PlainTime.

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

    • since

      public static ClockInterval since​(PlainTime start)

      Creates a finite half-open interval between given start time and midnight at end of day (exclusive).

      Note: The special wall time 24:00 does not belong to the created interval.

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

    • since

      public static ClockInterval since​(LocalTime start)

      Creates a finite half-open interval between given start time and midnight at end of day (exclusive).

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

    • until

      public static ClockInterval until​(PlainTime end)

      Creates a finite half-open interval between midnight at start of day and given end time.

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

    • until

      public static ClockInterval until​(LocalTime end)

      Creates a finite half-open interval between midnight at start of day and given end time.

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

    • from

      public static ClockInterval from​(ChronoInterval<PlainTime> interval)

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

      Parameters:
      interval - any kind of clock interval
      Returns:
      ClockInterval
      Since:
      3.34/4.29

    • on

      public TimestampInterval on​(PlainDate date)

      Creates a timestamp interval for given calendar date based on this clock interval.

      Parameters:
      date - gregorian calendar date
      Returns:
      new timestamp interval
      Since:
      5.0

    • getStartAsClockTime

      public PlainTime getStartAsClockTime()

      Yields the start time point.

      Returns:
      start time point
      Since:
      4.11

    • getStartAsLocalTime

      public LocalTime getStartAsLocalTime()

      Yields the start time point.

      Returns:
      start time point
      Since:
      4.11

    • getEndAsClockTime

      public PlainTime getEndAsClockTime()

      Yields the end time point.

      Returns:
      end time point
      Since:
      4.11

    • getEndAsLocalTime

      public LocalTime getEndAsLocalTime()

      Yields the end time point.

      The end time 24:00 (midnight at end of day) will be mapped to midnight at start of next day (00:00).

      Returns:
      end time point
      Since:
      4.11

    • getDuration

      public Duration<ClockUnit> getDuration()

      Yields the length of this interval.

      Returns:
      duration in hours, minutes, seconds and nanoseconds
      Since:
      2.0

    • move

      public ClockInterval move​(long amount, ClockUnit unit)

      Moves this interval along the time axis by given units.

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

    • stream

      public Stream<PlainTime> stream​(Duration<ClockUnit> duration)

      Obtains a stream iterating over every clock time 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 clock times which are the result of adding the duration to the start
      Throws:
      IllegalArgumentException - if the duration is not positive
      IllegalStateException - if this interval has no canonical form
      Since:
      4.18
      See Also:
      IsoInterval.toCanonical(), stream(Duration, PlainTime, PlainTime)

    • stream

      public static Stream<PlainTime> stream​(Duration<ClockUnit> duration, PlainTime start, PlainTime end)

      Obtains a stream iterating over every clock time 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 ClockInterval. 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 clock times 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.18

    • random

      public PlainTime random()

      Obtains a random time within this interval.

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

    • formatBasicISO

      public String formatBasicISO​(IsoDecimalStyle decimalStyle, ClockUnit precision)

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

      Parameters:
      decimalStyle - iso-compatible decimal style
      precision - controls the precision of output format with constant length
      Returns:
      String
      Throws:
      IllegalStateException - if there is no canonical form (for example for [00:00/24:00])
      Since:
      4.18
      See Also:
      IsoInterval.toCanonical()

    • formatExtendedISO

      public String formatExtendedISO​(IsoDecimalStyle decimalStyle, ClockUnit precision)

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

      Parameters:
      decimalStyle - iso-compatible decimal style
      precision - controls the precision of output format with constant length
      Returns:
      String
      Throws:
      IllegalStateException - if there is no canonical form (for example for [00:00/24:00])
      Since:
      4.18
      See Also:
      IsoInterval.toCanonical()

    • parse

      public static ClockInterval parse​(String text, ChronoParser<PlainTime> 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 ClockInterval parse​(String text, ChronoParser<PlainTime> 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 ClockInterval parse​(CharSequence text, ChronoParser<PlainTime> 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.

      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 ClockInterval parse​(CharSequence text, ChronoParser<PlainTime> startFormat, char separator, ChronoParser<PlainTime> 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.

      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 ClockInterval parseISO​(String text) throws ParseException

      Interpretes given ISO-conforming text as interval.

      Examples for supported formats:

      • 09:45/PT5H
      • PT5H/14:45
      • 0945/PT5H
      • PT5H/1445
      • PT01:55:30/14:15:30
      • 04:01:30.123/24:00:00.000
      • 04:01:30,123/24:00:00,000
      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.1
      See Also:
      BracketPolicy.SHOW_NEVER