Class Temporals


  • public final class Temporals
    extends 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 Detail

      • nextWorkingDay

        public static 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 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 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 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​(CharSequence text,
                                               TemporalQuery<T> query,
                                               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:
        DateTimeParseException - if unable to parse the requested result
      • chronoUnit

        public static ChronoUnit chronoUnit​(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 TimeUnit timeUnit​(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:
        IllegalArgumentException - if the unit cannot be converted
      • convertAmount

        public static long[] convertAmount​(long amount,
                                           TemporalUnit fromUnit,
                                           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:
        DateTimeException - if the units cannot be converted
        UnsupportedTemporalTypeException - if the units are not supported
        ArithmeticException - if numeric overflow occurs
      • durationToBigDecimalSeconds

        public static BigDecimal durationToBigDecimalSeconds​(Duration duration)
        Converts a duration to a BigDecimal with a scale of 9.
        Parameters:
        duration - the duration to convert, not null
        Returns:
        the BigDecimal equivalent of the duration, in seconds with a scale of 9
      • durationFromBigDecimalSeconds

        public static Duration durationFromBigDecimalSeconds​(BigDecimal seconds)
        Converts a BigDecimal representing seconds to a duration, saturating if necessary.

        No exception is thrown by this method. Numbers are rounded up to the nearest nanosecond (away from zero). The duration will saturate at the biggest positive or negative Duration.

        Parameters:
        seconds - the number of seconds to convert, positive or negative
        Returns:
        a Duration, not null
      • durationToDoubleSeconds

        public static double durationToDoubleSeconds​(Duration duration)
        Converts a duration to a double.
        Parameters:
        duration - the duration to convert, not null
        Returns:
        the double equivalent of the duration, in seconds
      • durationFromDoubleSeconds

        public static Duration durationFromDoubleSeconds​(double seconds)
        Converts a double representing seconds to a duration, saturating if necessary.

        No exception is thrown by this method. Numbers are rounded up to the nearest nanosecond (away from zero). The duration will saturate at the biggest positive or negative Duration.

        Parameters:
        seconds - the number of seconds to convert, positive or negative
        Returns:
        a Duration, not null
      • multiply

        public static Duration multiply​(Duration duration,
                                        double multiplicand)
        Multiplies a duration by a double.

        The amount is rounded away from zero, thus the result is only zero if zero is passed in. See durationToBigDecimalSeconds(Duration) and durationFromBigDecimalSeconds(BigDecimal). Note that due to the rounding up, 1 nanosecond multiplied by any number smaller than 1 will still be 1 nanosecond.

        Parameters:
        duration - the duration to multiply, not null
        multiplicand - the multiplication factor
        Returns:
        the multiplied duration, not null