Module org.threeten.extra
Package org.threeten.extra

Class Temporals

  • public final class Temporals
extends java.lang.Object
    Additional utilities for working with temporal classes.

    This includes:

    • adjusters that ignore Saturday/Sunday weekends
    • conversion between TimeUnit and ChronoUnit
    • converting an amount to another unit

    Implementation Requirements:

    This is a thread-safe utility class. All returned classes are immutable and thread-safe.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static java.time.temporal.ChronoUnit chronoUnit​(java.util.concurrent.TimeUnit unit)
      Converts a TimeUnit to a ChronoUnit.
      static long[] convertAmount​(long amount, java.time.temporal.TemporalUnit fromUnit, java.time.temporal.TemporalUnit toUnit)
      Converts an amount from one unit to another.
      static java.time.temporal.TemporalAdjuster nextWorkingDay()
      Returns an adjuster that returns the next working day, ignoring Saturday and Sunday.
      static java.time.temporal.TemporalAdjuster nextWorkingDayOrSame()
      Returns an adjuster that returns the next working day or same day if already working day, ignoring Saturday and Sunday.
      static <T> T parseFirstMatching​(java.lang.CharSequence text, java.time.temporal.TemporalQuery<T> query, java.time.format.DateTimeFormatter... formatters)
      Parses the text using one of the formatters.
      static java.time.temporal.TemporalAdjuster previousWorkingDay()
      Returns an adjuster that returns the previous working day, ignoring Saturday and Sunday.
      static java.time.temporal.TemporalAdjuster previousWorkingDayOrSame()
      Returns an adjuster that returns the previous working day or same day if already working day, ignoring Saturday and Sunday.
      static java.util.concurrent.TimeUnit timeUnit​(java.time.temporal.ChronoUnit unit)
      Converts a ChronoUnit to a TimeUnit.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • nextWorkingDay

        public static java.time.temporal.TemporalAdjuster nextWorkingDay()
        Returns an adjuster that returns the next working day, ignoring Saturday and Sunday.

        Some territories have weekends that do not consist of Saturday and Sunday. No implementation is supplied to support this, however an adjuster can be easily written to do so.

        Returns:
        the next working day adjuster, not null

      • nextWorkingDayOrSame

        public static java.time.temporal.TemporalAdjuster nextWorkingDayOrSame()
        Returns an adjuster that returns the next working day or same day if already working day, ignoring Saturday and Sunday.

        Some territories have weekends that do not consist of Saturday and Sunday. No implementation is supplied to support this, however an adjuster can be easily written to do so.

        Returns:
        the next working day or same adjuster, not null

      • previousWorkingDay

        public static java.time.temporal.TemporalAdjuster previousWorkingDay()
        Returns an adjuster that returns the previous working day, ignoring Saturday and Sunday.

        Some territories have weekends that do not consist of Saturday and Sunday. No implementation is supplied to support this, however an adjuster can be easily written to do so.

        Returns:
        the previous working day adjuster, not null

      • previousWorkingDayOrSame

        public static java.time.temporal.TemporalAdjuster previousWorkingDayOrSame()
        Returns an adjuster that returns the previous working day or same day if already working day, ignoring Saturday and Sunday.

        Some territories have weekends that do not consist of Saturday and Sunday. No implementation is supplied to support this, however an adjuster can be easily written to do so.

        Returns:
        the previous working day or same adjuster, not null

      • parseFirstMatching

        public static <T> T parseFirstMatching​(java.lang.CharSequence text,
                                       java.time.temporal.TemporalQuery<T> query,
                                       java.time.format.DateTimeFormatter... formatters)
        Parses the text using one of the formatters.

        This will try each formatter in turn, attempting to fully parse the specified text. The temporal query is typically a method reference to a from(TemporalAccessor) method. For example: 

          LocalDateTime dt = Temporals.parseFirstMatching(str, LocalDateTime::from, fmt1, fm2, fm3);
        If the parse completes without reading the entire length of the text, or a problem occurs during parsing or merging, then an exception is thrown.
        Type Parameters:
        T - the type of the parsed date-time
        Parameters:
        text - the text to parse, not null
        query - the query defining the type to parse to, not null
        formatters - the formatters to try, not null
        Returns:
        the parsed date-time, not null
        Throws:
        java.time.format.DateTimeParseException - if unable to parse the requested result

      • chronoUnit

        public static java.time.temporal.ChronoUnit chronoUnit​(java.util.concurrent.TimeUnit unit)
        Converts a TimeUnit to a ChronoUnit.

        This handles the seven units declared in TimeUnit.

        Parameters:
        unit - the unit to convert, not null
        Returns:
        the converted unit, not null

      • timeUnit

        public static java.util.concurrent.TimeUnit timeUnit​(java.time.temporal.ChronoUnit unit)
        Converts a ChronoUnit to a TimeUnit.

        This handles the seven units declared in TimeUnit.

        Parameters:
        unit - the unit to convert, not null
        Returns:
        the converted unit, not null
        Throws:
        java.lang.IllegalArgumentException - if the unit cannot be converted

      • convertAmount

        public static long[] convertAmount​(long amount,
                                   java.time.temporal.TemporalUnit fromUnit,
                                   java.time.temporal.TemporalUnit toUnit)
        Converts an amount from one unit to another.

        This works on the units in ChronoUnit and IsoFields. The DAYS and WEEKS units are handled as exact multiple of 24 hours. The ERAS and FOREVER units are not supported.

        Parameters:
        amount - the input amount in terms of the fromUnit
        fromUnit - the unit to convert from, not null
        toUnit - the unit to convert to, not null
        Returns:
        the conversion array, element 0 is the signed whole number, element 1 is the signed remainder in terms of the input unit, not null
        Throws:
        java.time.DateTimeException - if the units cannot be converted
        java.time.temporal.UnsupportedTemporalTypeException - if the units are not supported
        java.lang.ArithmeticException - if numeric overflow occurs