Class DateTimeUtils

java.lang.Object
io.deephaven.time.DateTimeUtils

public class DateTimeUtils extends Object
Functions for working with time.
  • Field Details

    • ZERO_LENGTH_INSTANT_ARRAY

      public static final Instant[] ZERO_LENGTH_INSTANT_ARRAY
      A zero length array of instants.
    • MICRO

      public static final long MICRO
      One microsecond in nanoseconds.
      See Also:
    • MILLI

      public static final long MILLI
      One millisecond in nanoseconds.
      See Also:
    • SECOND

      public static final long SECOND
      One second in nanoseconds.
      See Also:
    • MINUTE

      public static final long MINUTE
      One minute in nanoseconds.
      See Also:
    • HOUR

      public static final long HOUR
      One hour in nanoseconds.
      See Also:
    • DAY

      public static final long DAY
      One day in nanoseconds. This is one hour of wall time and does not take into account calendar adjustments.
      See Also:
    • WEEK

      public static final long WEEK
      One week in nanoseconds. This is 7 days of wall time and does not take into account calendar adjustments.
      See Also:
    • YEAR_365

      public static final long YEAR_365
      One 365 day year in nanoseconds. This is 365 days of wall time and does not take into account calendar adjustments.
      See Also:
    • YEAR_AVG

      public static final long YEAR_AVG
      One average year in nanoseconds. This is 365.2425 days of wall time and does not take into account calendar adjustments.
      See Also:
    • SECONDS_PER_NANO

      public static final double SECONDS_PER_NANO
      Number of seconds per nanosecond.
      See Also:
    • MINUTES_PER_NANO

      public static final double MINUTES_PER_NANO
      Number of minutes per nanosecond.
      See Also:
    • HOURS_PER_NANO

      public static final double HOURS_PER_NANO
      Number of hours per nanosecond.
      See Also:
    • DAYS_PER_NANO

      public static final double DAYS_PER_NANO
      Number of days per nanosecond.
      See Also:
    • YEARS_PER_NANO_365

      public static final double YEARS_PER_NANO_365
      Number of 365 day years per nanosecond.
      See Also:
    • YEARS_PER_NANO_AVG

      public static final double YEARS_PER_NANO_AVG
      Number of average (365.2425 day) years per nanosecond.
      See Also:
  • Constructor Details

    • DateTimeUtils

      public DateTimeUtils()
  • Method Details

    • setClock

      @ScriptApi public static void setClock(@Nullable @Nullable Clock clock)
      Set the clock used to compute the current time. This allows a custom clock to be used instead of the current system clock. This is mainly used for replay simulations.
      Parameters:
      clock - the clock used to compute the current time; if null, use the system clock
    • currentClock

      @NotNull @ScriptApi public static @NotNull Clock currentClock()
      Returns the clock used to compute the current time. This may be the current system clock, or it may be an alternative clock used for replay simulations.
      Returns:
      the current clock
      See Also:
    • now

      @ScriptApi @NotNull public static @NotNull Instant now()
      Provides the current instant with nanosecond resolution according to the current clock. Under most circumstances, this method will return the current system time, but during replay simulations, this method can return the replay time.
      Returns:
      the current instant with nanosecond resolution according to the current clock
      See Also:
    • nowMillisResolution

      @ScriptApi @NotNull public static @NotNull Instant nowMillisResolution()
      Provides the current instant with millisecond resolution according to the current clock. Under most circumstances, this method will return the current system time, but during replay simulations, this method can return the replay time.
      Returns:
      the current instant with millisecond resolution according to the current clock
      See Also:
    • nowSystem

      @ScriptApi @NotNull public static @NotNull Instant nowSystem()
      Provides the current instant with nanosecond resolution according to the system clock. Note that the system time may not be desirable during replay simulations.
      Returns:
      the current instant with nanosecond resolution according to the system clock
      See Also:
    • nowSystemMillisResolution

      @ScriptApi @NotNull public static @NotNull Instant nowSystemMillisResolution()
      Provides the current instant with millisecond resolution according to the system clock. Note that the system time may not be desirable during replay simulations.
      Returns:
      the current instant with millisecond resolution according to the system clock
      See Also:
    • today

      @ScriptApi @Nullable public static @Nullable String today(@Nullable @Nullable ZoneId timeZone)
      Provides the current date string according to the current clock. Under most circumstances, this method will return the date according to current system time, but during replay simulations, this method can return the date according to replay time.
      Parameters:
      timeZone - the time zone
      Returns:
      the current date according to the current clock and time zone formatted as "yyyy-MM-dd". null if the input is null.
      See Also:
    • today

      @ScriptApi @NotNull public static @NotNull String today()
      Provides the current date string according to the current clock and the default time zone. Under most circumstances, this method will return the date according to current system time, but during replay simulations, this method can return the date according to replay time.
      Returns:
      the current date according to the current clock and default time zone formatted as "yyyy-MM-dd"
      See Also:
    • todayLocalDate

      @ScriptApi @Nullable public static @Nullable LocalDate todayLocalDate(@Nullable @Nullable ZoneId timeZone)
      Provides the current date according to the current clock. Under most circumstances, this method will return the date according to current system time, but during replay simulations, this method can return the date according to replay time.
      Parameters:
      timeZone - the time zone
      Returns:
      the current date according to the current clock and time zone formatted as "yyyy-MM-dd". null if the input is null.
      See Also:
    • todayLocalDate

      @ScriptApi @NotNull public static @NotNull LocalDate todayLocalDate()
      Provides the current date according to the current clock and the default time zone. Under most circumstances, this method will return the date according to current system time, but during replay simulations, this method can return the date according to replay time.
      Returns:
      the current date according to the current clock and default time zone formatted as "yyyy-MM-dd"
      See Also:
    • timeZone

      @Nullable public static @Nullable ZoneId timeZone(@Nullable @Nullable String timeZone)
      Gets the time zone for a time zone name.
      Parameters:
      timeZone - the time zone name
      Returns:
      the corresponding time zone. null if the input is null.
      Throws:
      DateTimeException - if timeZone has an invalid format
      ZoneRulesException - if timeZone cannot be found
    • timeZone

      public static ZoneId timeZone()
      Returns:
      the system default time zone
      See Also:
    • timeZoneAliasAdd

      public static void timeZoneAliasAdd(@NotNull @NotNull String alias, @NotNull @NotNull String timeZone)
      Adds a new time zone alias.
      Parameters:
      alias - the alias name
      timeZone - the time zone id name
      Throws:
      IllegalArgumentException - if the alias already exists or the time zone is invalid
    • timeZoneAliasRm

      public static boolean timeZoneAliasRm(@NotNull @NotNull String alias)
      Removes a time zone alias.
      Parameters:
      alias - the alias name
      Returns:
      whether alias was present
    • microsToNanos

      @ScriptApi public static long microsToNanos(long micros)
      Converts microseconds to nanoseconds.
      Parameters:
      micros - the microseconds to convert
      Returns:
      QueryConstants.NULL_LONG if the input is QueryConstants.NULL_LONG; otherwise the input microseconds converted to nanoseconds
    • millisToNanos

      @ScriptApi public static long millisToNanos(long millis)
      Converts milliseconds to nanoseconds.
      Parameters:
      millis - the milliseconds to convert
      Returns:
      QueryConstants.NULL_LONG if the input is QueryConstants.NULL_LONG; otherwise the input milliseconds converted to nanoseconds
    • secondsToNanos

      @ScriptApi public static long secondsToNanos(long seconds)
      Converts seconds to nanoseconds.
      Parameters:
      seconds - the seconds to convert
      Returns:
      QueryConstants.NULL_LONG if the input is QueryConstants.NULL_LONG; otherwise the input seconds converted to nanoseconds
    • nanosToMicros

      @ScriptApi public static long nanosToMicros(long nanos)
      Converts nanoseconds to microseconds.
      Parameters:
      nanos - the nanoseconds to convert
      Returns:
      QueryConstants.NULL_LONG if the input is QueryConstants.NULL_LONG; otherwise the input nanoseconds converted to microseconds, rounded down
    • millisToMicros

      @ScriptApi public static long millisToMicros(long millis)
      Converts milliseconds to microseconds.
      Parameters:
      millis - the milliseconds to convert
      Returns:
      QueryConstants.NULL_LONG if the input is QueryConstants.NULL_LONG; otherwise the input milliseconds converted to microseconds, rounded down
    • secondsToMicros

      @ScriptApi public static long secondsToMicros(long seconds)
      Converts seconds to microseconds.
      Parameters:
      seconds - the seconds to convert
      Returns:
      QueryConstants.NULL_LONG if the input is QueryConstants.NULL_LONG; otherwise the input seconds converted to microseconds, rounded down
    • nanosToMillis

      @ScriptApi public static long nanosToMillis(long nanos)
      Converts nanoseconds to milliseconds.
      Parameters:
      nanos - the nanoseconds to convert
      Returns:
      QueryConstants.NULL_LONG if the input is QueryConstants.NULL_LONG; otherwise the input nanoseconds converted to milliseconds, rounded down
    • microsToMillis

      @ScriptApi public static long microsToMillis(long micros)
      Converts microseconds to milliseconds.
      Parameters:
      micros - the microseconds to convert
      Returns:
      QueryConstants.NULL_LONG if the input is QueryConstants.NULL_LONG; otherwise the input microseconds converted to milliseconds, rounded down
    • secondsToMillis

      @ScriptApi public static long secondsToMillis(long seconds)
      Converts seconds to milliseconds.
      Parameters:
      seconds - the nanoseconds to convert
      Returns:
      QueryConstants.NULL_LONG if the input is QueryConstants.NULL_LONG; otherwise the input seconds converted to milliseconds, rounded down
    • nanosToSeconds

      @ScriptApi public static long nanosToSeconds(long nanos)
      Converts nanoseconds to seconds.
      Parameters:
      nanos - the nanoseconds to convert
      Returns:
      QueryConstants.NULL_LONG if the input is QueryConstants.NULL_LONG; otherwise the input nanoseconds converted to seconds, rounded down
    • microsToSeconds

      @ScriptApi public static long microsToSeconds(long micros)
      Converts microseconds to seconds.
      Parameters:
      micros - the microseconds to convert
      Returns:
      QueryConstants.NULL_LONG if the input is QueryConstants.NULL_LONG; otherwise the input microseconds converted to seconds, rounded down
    • millisToSeconds

      @ScriptApi public static long millisToSeconds(long millis)
      Converts milliseconds to seconds.
      Parameters:
      millis - the milliseconds to convert
      Returns:
      QueryConstants.NULL_LONG if the input is QueryConstants.NULL_LONG; otherwise the input milliseconds converted to seconds, rounded down
    • toInstant

      @ScriptApi @Nullable public static @Nullable Instant toInstant(@Nullable @Nullable ZonedDateTime dateTime)
      Converts a ZonedDateTime to an Instant.
      Parameters:
      dateTime - the zoned date time to convert
      Returns:
      the Instant, or null if dateTime is null
    • toInstant

      @ScriptApi @Nullable public static @Nullable Instant toInstant(@Nullable @Nullable LocalDate date, @Nullable @Nullable LocalTime time, @Nullable @Nullable ZoneId timeZone)
      Converts a LocalDate, LocalTime, and ZoneId to an Instant.
      Parameters:
      date - the local date
      time - the local time
      timeZone - the time zone
      Returns:
      the Instant, or null if any input is null
    • toInstant

      @ScriptApi @Nullable @Deprecated public static @Nullable Instant toInstant(@Nullable @Nullable Date date)
      Deprecated.
      Converts a Date to an Instant.
      Parameters:
      date - the date to convert
      Returns:
      the Instant, or null if date is null
    • toZonedDateTime

      @ScriptApi @Nullable public static @Nullable ZonedDateTime toZonedDateTime(@Nullable @Nullable Instant instant, @Nullable @Nullable ZoneId timeZone)
      Converts an Instant to a ZonedDateTime.
      Parameters:
      instant - the instant to convert
      timeZone - the time zone to use
      Returns:
      the ZonedDateTime, or null if any input is null
    • toZonedDateTime

      @ScriptApi @Nullable public static @Nullable ZonedDateTime toZonedDateTime(@Nullable @Nullable LocalDate date, @Nullable @Nullable LocalTime time, @Nullable @Nullable ZoneId timeZone)
      Converts a LocalDate, LocalTime, and ZoneId to a ZonedDateTime.
      Parameters:
      date - the local date
      time - the local time
      timeZone - the time zone to use
      Returns:
      the ZonedDateTime, or null if any input is null
    • toLocalDate

      @Nullable public static @Nullable LocalDate toLocalDate(@Nullable @Nullable Instant instant, @Nullable @Nullable ZoneId timeZone)
      Converts an Instant to a LocalDate with the specified ZoneId.
      Parameters:
      instant - the instant to convert
      timeZone - the time zone
      Returns:
      the LocalDate, or null if any input is null
    • toLocalDate

      @Nullable public static @Nullable LocalDate toLocalDate(@Nullable @Nullable ZonedDateTime dateTime)
      Get the LocalDate portion of a ZonedDateTime.
      Parameters:
      dateTime - the zoned date time to convert
      Returns:
      the LocalDate, or null if dateTime is null
    • toLocalTime

      @Nullable public static @Nullable LocalTime toLocalTime(@Nullable @Nullable Instant instant, @Nullable @Nullable ZoneId timeZone)
      Converts an Instant to a LocalTime with the specified ZoneId.
      Parameters:
      instant - the instant to convert
      timeZone - the time zone
      Returns:
      the LocalTime, or null if any input is null
    • toLocalTime

      @Nullable public static @Nullable LocalTime toLocalTime(@Nullable @Nullable ZonedDateTime dateTime)
      Get the LocalTime portion of a ZonedDateTime.
      Parameters:
      dateTime - the zoned date time to convert
      Returns:
      the LocalTime, or null if dateTime is null
    • millisOfDayToLocalTime

      @Nullable public static @Nullable LocalTime millisOfDayToLocalTime(int millis)
      Converts the number of milliseconds from midnight to a LocalTime
      Parameters:
      millis - milliseconds from midnight
      Returns:
      the LocalTime, or null if any input is NULL_INT
    • microsOfDayToLocalTime

      @Nullable public static @Nullable LocalTime microsOfDayToLocalTime(long micros)
      Converts the number of microseconds from midnight to a LocalTime
      Parameters:
      micros - microseconds from midnight
      Returns:
      the LocalTime, or null if any input is NULL_LONG
    • nanosOfDayToLocalTime

      @Nullable public static @Nullable LocalTime nanosOfDayToLocalTime(long nanos)
      Converts the number of nanoseconds from midnight to a LocalTime
      Parameters:
      nanos - nanoseconds from midnight
      Returns:
      the LocalTime, or null if any input is NULL_LONG
    • toDate

      @Deprecated @Nullable public static @Nullable Date toDate(@Nullable @Nullable Instant instant)
      Deprecated.
      Converts an Instant to a Date. instant will be truncated to millisecond resolution.
      Parameters:
      instant - the instant to convert
      Returns:
      the Date, or null if instant is null
    • toDate

      @Deprecated @Nullable public static @Nullable Date toDate(@Nullable @Nullable ZonedDateTime dateTime)
      Deprecated.
      Converts a ZonedDateTime to a Date. dateTime will be truncated to millisecond resolution.
      Parameters:
      dateTime - the zoned date time to convert
      Returns:
      the Date, or null if dateTime is null
    • epochNanos

      @ScriptApi public static long epochNanos(@Nullable @Nullable Instant instant)
      Returns nanoseconds from the Epoch for an Instant value.
      Parameters:
      instant - instant to compute the Epoch offset for
      Returns:
      nanoseconds since Epoch, or a NULL_LONG value if the instant is null
    • epochNanos

      @ScriptApi public static long epochNanos(@Nullable @Nullable ZonedDateTime dateTime)
      Returns nanoseconds from the Epoch for a ZonedDateTime value.
      Parameters:
      dateTime - the zoned date time to compute the Epoch offset for
      Returns:
      nanoseconds since Epoch, or a NULL_LONG value if the zoned date time is null
    • epochMicros

      @ScriptApi public static long epochMicros(@Nullable @Nullable Instant instant)
      Returns microseconds from the Epoch for an Instant value.
      Parameters:
      instant - instant to compute the Epoch offset for
      Returns:
      microseconds since Epoch, or a NULL_LONG value if the instant is null
    • epochMicros

      @ScriptApi public static long epochMicros(@Nullable @Nullable ZonedDateTime dateTime)
      Returns microseconds from the Epoch for a ZonedDateTime value.
      Parameters:
      dateTime - zoned date time to compute the Epoch offset for
      Returns:
      microseconds since Epoch, or a NULL_LONG value if the zoned date time is null
    • epochMillis

      @ScriptApi public static long epochMillis(@Nullable @Nullable Instant instant)
      Returns milliseconds from the Epoch for an Instant value.
      Parameters:
      instant - instant to compute the Epoch offset for
      Returns:
      milliseconds since Epoch, or a NULL_LONG value if the instant is null
    • epochMillis

      @ScriptApi public static long epochMillis(@Nullable @Nullable ZonedDateTime dateTime)
      Returns milliseconds from the Epoch for a ZonedDateTime value.
      Parameters:
      dateTime - zoned date time to compute the Epoch offset for
      Returns:
      milliseconds since Epoch, or a NULL_LONG value if the zoned date time is null
    • epochSeconds

      @ScriptApi public static long epochSeconds(@Nullable @Nullable Instant instant)
      Returns seconds since from the Epoch for an Instant value.
      Parameters:
      instant - instant to compute the Epoch offset for
      Returns:
      seconds since Epoch, or a NULL_LONG value if the instant is null
    • epochSeconds

      @ScriptApi public static long epochSeconds(@Nullable @Nullable ZonedDateTime dateTime)
      Returns seconds since from the Epoch for a ZonedDateTime value.
      Parameters:
      dateTime - zoned date time to compute the Epoch offset for
      Returns:
      seconds since Epoch, or a NULL_LONG value if the zoned date time is null
    • epochDays

      public static long epochDays(@Nullable @Nullable LocalDate date)
      Returns number of days from the Epoch for a LocalDate value.
      Parameters:
      date - date to compute the Epoch offset for
      Returns:
      days since Epoch, or a NULL_LONG value if the instant is null
    • epochDaysAsInt

      public static int epochDaysAsInt(@Nullable @Nullable LocalDate date)
      Returns number of days (as an int) from the Epoch for a LocalDate value.
      Parameters:
      date - date to compute the Epoch offset for
      Returns:
      days since Epoch, or a NULL_INT value if the instant is null
    • epochNanosToInstant

      @ScriptApi @Nullable public static @Nullable Instant epochNanosToInstant(long nanos)
      Converts nanoseconds from the Epoch to an Instant.
      Parameters:
      nanos - nanoseconds since Epoch
      Returns:
      null if the input is QueryConstants.NULL_LONG; otherwise the input nanoseconds from the Epoch converted to an Instant
    • epochMicrosToInstant

      @ScriptApi @Nullable public static @Nullable Instant epochMicrosToInstant(long micros)
      Converts microseconds from the Epoch to an Instant.
      Parameters:
      micros - microseconds since Epoch
      Returns:
      null if the input is QueryConstants.NULL_LONG; otherwise the input microseconds from the Epoch converted to an Instant
    • epochMillisToInstant

      @ScriptApi @Nullable public static @Nullable Instant epochMillisToInstant(long millis)
      Converts milliseconds from the Epoch to an Instant.
      Parameters:
      millis - milliseconds since Epoch
      Returns:
      null if the input is QueryConstants.NULL_LONG; otherwise the input milliseconds from the Epoch converted to an Instant
    • epochSecondsToInstant

      @ScriptApi @Nullable public static @Nullable Instant epochSecondsToInstant(long seconds)
      Converts seconds from the Epoch to an Instant.
      Parameters:
      seconds - seconds since Epoch
      Returns:
      null if the input is QueryConstants.NULL_LONG; otherwise the input seconds from the Epoch converted to an Instant
    • epochNanosToZonedDateTime

      @ScriptApi @Nullable public static @Nullable ZonedDateTime epochNanosToZonedDateTime(long nanos, ZoneId timeZone)
      Converts nanoseconds from the Epoch to a ZonedDateTime.
      Parameters:
      nanos - nanoseconds since Epoch
      timeZone - time zone
      Returns:
      null if the input is QueryConstants.NULL_LONG; otherwise the input nanoseconds from the Epoch converted to a ZonedDateTime
    • epochMicrosToZonedDateTime

      @ScriptApi @Nullable public static @Nullable ZonedDateTime epochMicrosToZonedDateTime(long micros, @Nullable @Nullable ZoneId timeZone)
      Converts microseconds from the Epoch to a ZonedDateTime.
      Parameters:
      micros - microseconds since Epoch
      timeZone - time zone
      Returns:
      null if the input is QueryConstants.NULL_LONG; otherwise the input microseconds from the Epoch converted to a ZonedDateTime
    • epochMillisToZonedDateTime

      @ScriptApi @Nullable public static @Nullable ZonedDateTime epochMillisToZonedDateTime(long millis, @Nullable @Nullable ZoneId timeZone)
      Converts milliseconds from the Epoch to a ZonedDateTime.
      Parameters:
      millis - milliseconds since Epoch
      timeZone - time zone
      Returns:
      null if the input is QueryConstants.NULL_LONG; otherwise the input milliseconds from the Epoch converted to a ZonedDateTime
    • epochSecondsToZonedDateTime

      @ScriptApi @Nullable public static @Nullable ZonedDateTime epochSecondsToZonedDateTime(long seconds, @Nullable @Nullable ZoneId timeZone)
      Converts seconds from the Epoch to a ZonedDateTime.
      Parameters:
      seconds - seconds since Epoch
      timeZone - time zone
      Returns:
      null if the input is QueryConstants.NULL_LONG; otherwise the input seconds from the Epoch converted to a ZonedDateTime
    • epochAutoToEpochNanos

      @ScriptApi public static long epochAutoToEpochNanos(long epochOffset)
      Converts an offset from the Epoch to a nanoseconds from the Epoch. The offset can be in milliseconds, microseconds, or nanoseconds. Expected date ranges are used to infer the units for the offset.
      Parameters:
      epochOffset - time offset from the Epoch
      Returns:
      null if the input is QueryConstants.NULL_LONG; otherwise the input offset from the Epoch converted to nanoseconds from the Epoch
    • epochAutoToInstant

      @ScriptApi @Nullable public static @Nullable Instant epochAutoToInstant(long epochOffset)
      Converts an offset from the Epoch to an Instant. The offset can be in milliseconds, microseconds, or nanoseconds. Expected date ranges are used to infer the units for the offset.
      Parameters:
      epochOffset - time offset from the Epoch
      Returns:
      null if the input is QueryConstants.NULL_LONG; otherwise the input offset from the Epoch converted to an Instant
    • epochAutoToZonedDateTime

      @ScriptApi @Nullable public static @Nullable ZonedDateTime epochAutoToZonedDateTime(long epochOffset, @Nullable @Nullable ZoneId timeZone)
      Converts an offset from the Epoch to a ZonedDateTime. The offset can be in milliseconds, microseconds, or nanoseconds. Expected date ranges are used to infer the units for the offset.
      Parameters:
      epochOffset - time offset from the Epoch
      timeZone - time zone
      Returns:
      null if any input is null or QueryConstants.NULL_LONG; otherwise the input offset from the Epoch converted to a ZonedDateTime
    • epochDaysToLocalDate

      @Nullable public static @Nullable LocalDate epochDaysToLocalDate(long days)
      Converts days from the Epoch to a LocalDate.
      Parameters:
      days - days since Epoch
      Returns:
      null if the input is QueryConstants.NULL_LONG; otherwise the input days from the Epoch converted to a LocalDate
    • epochDaysAsIntToLocalDate

      @Nullable public static @Nullable LocalDate epochDaysAsIntToLocalDate(int days)
      Converts days from the Epoch (stored as int) to a LocalDate.
      Parameters:
      days - days since Epoch
      Returns:
      null if the input is QueryConstants.NULL_INT; otherwise the input days from the Epoch converted to a LocalDate
    • toExcelTime

      @ScriptApi public static double toExcelTime(@Nullable @Nullable Instant instant, @Nullable @Nullable ZoneId timeZone)
      Converts an Instant to an Excel time represented as a double.
      Parameters:
      instant - instant to convert
      timeZone - time zone to use when interpreting the instant
      Returns:
      0.0 if either input is null; otherwise, the input instant converted to an Excel time represented as a double
    • toExcelTime

      @ScriptApi public static double toExcelTime(@Nullable @Nullable ZonedDateTime dateTime)
      Converts a ZonedDateTime to an Excel time represented as a double.
      Parameters:
      dateTime - zoned date time to convert
      Returns:
      0.0 if either input is null; otherwise, the input zoned date time converted to an Excel time represented as a double
    • excelToInstant

      @ScriptApi @Nullable public static @Nullable Instant excelToInstant(double excel, @Nullable @Nullable ZoneId timeZone)
      Converts an Excel time represented as a double to an Instant.
      Parameters:
      excel - excel time represented as a double
      timeZone - time zone to use when interpreting the Excel time
      Returns:
      null if timeZone is null; otherwise, the input Excel time converted to an Instant
    • excelToZonedDateTime

      @ScriptApi @Nullable public static @Nullable ZonedDateTime excelToZonedDateTime(double excel, @Nullable @Nullable ZoneId timeZone)
      Converts an Excel time represented as a double to a ZonedDateTime.
      Parameters:
      excel - excel time represented as a double
      timeZone - time zone to use when interpreting the Excel time
      Returns:
      null if timeZone is null; otherwise, the input Excel time converted to a ZonedDateTime
    • plusDays

      @ScriptApi @Nullable public static @Nullable LocalDate plusDays(@Nullable @Nullable LocalDate date, long days)
      Adds days to a LocalDate.
      Parameters:
      date - starting date
      days - number of days to add
      Returns:
      null if either input is null or QueryConstants.NULL_LONG; otherwise the starting date plus the specified number of days
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the resultant date time exceeds the supported range
    • plus

      @ScriptApi @Nullable public static @Nullable LocalDate plus(@Nullable @Nullable LocalDate date, Period period)
      Adds a time period to a LocalDate.
      Parameters:
      date - starting date
      period - time period
      Returns:
      null if either input is null; otherwise the starting date plus the specified time period
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the resultant date time exceeds the supported range
    • plus

      @ScriptApi @Nullable public static @Nullable Instant plus(@Nullable @Nullable Instant instant, long nanos)
      Adds nanoseconds to an Instant.
      Parameters:
      instant - starting instant value
      nanos - number of nanoseconds to add
      Returns:
      null if either input is null or QueryConstants.NULL_LONG; otherwise the starting instant plus the specified number of nanoseconds
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the resultant instant exceeds the supported range
    • plus

      @ScriptApi @Nullable public static @Nullable ZonedDateTime plus(@Nullable @Nullable ZonedDateTime dateTime, long nanos)
      Adds nanoseconds to a ZonedDateTime.
      Parameters:
      dateTime - starting zoned date time value
      nanos - number of nanoseconds to add
      Returns:
      null if either input is null or QueryConstants.NULL_LONG; otherwise the starting zoned date time plus the specified number of nanoseconds
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the resultant zoned date time exceeds the supported range
    • plus

      @ScriptApi @Nullable public static @Nullable Instant plus(@Nullable @Nullable Instant instant, @Nullable @Nullable Duration duration)
      Adds a time period to an Instant.
      Parameters:
      instant - starting instant value
      duration - time period
      Returns:
      null if either input is null or QueryConstants.NULL_LONG; otherwise the starting instant plus the specified time period
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the resultant instant exceeds the supported range
    • plus

      @ScriptApi @Nullable public static @Nullable Instant plus(@Nullable @Nullable Instant instant, @Nullable @Nullable Period period)
      Adds a time period to an Instant.
      Parameters:
      instant - starting instant value
      period - time period
      Returns:
      null if either input is null or QueryConstants.NULL_LONG; otherwise the starting instant plus the specified time period
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the resultant instant exceeds the supported range
    • plus

      @ScriptApi @Nullable public static @Nullable ZonedDateTime plus(@Nullable @Nullable ZonedDateTime dateTime, @Nullable @Nullable Duration duration)
      Adds a time period to a ZonedDateTime.
      Parameters:
      dateTime - starting zoned date time value
      duration - time period
      Returns:
      null if either input is null or QueryConstants.NULL_LONG; otherwise the starting zoned date time plus the specified time period
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the resultant zoned date time exceeds the supported range
    • plus

      @ScriptApi @Nullable public static @Nullable ZonedDateTime plus(@Nullable @Nullable ZonedDateTime dateTime, @Nullable @Nullable Period period)
      Adds a time period to a ZonedDateTime.
      Parameters:
      dateTime - starting zoned date time value
      period - time period
      Returns:
      null if either input is null or QueryConstants.NULL_LONG; otherwise the starting zoned date time plus the specified time period
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the resultant zoned date time exceeds the supported range
    • minusDays

      @ScriptApi @Nullable public static @Nullable LocalDate minusDays(@Nullable @Nullable LocalDate date, long days)
      Subtracts days from a LocalDate.
      Parameters:
      date - starting date
      days - number of days to subtract
      Returns:
      null if either input is null or QueryConstants.NULL_LONG; otherwise the starting date plus the specified number of days
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the resultant date time exceeds the supported range
    • minus

      @ScriptApi @Nullable public static @Nullable LocalDate minus(@Nullable @Nullable LocalDate date, Period period)
      Subtracts a time period from a LocalDate.
      Parameters:
      date - starting date
      period - time period
      Returns:
      null if either input is null; otherwise the starting date minus the specified time period
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the resultant date time exceeds the supported range
    • minus

      @ScriptApi @Nullable public static @Nullable Instant minus(@Nullable @Nullable Instant instant, long nanos)
      Subtracts nanoseconds from an Instant.
      Parameters:
      instant - starting instant value
      nanos - number of nanoseconds to subtract
      Returns:
      null if either input is null or QueryConstants.NULL_LONG; otherwise the starting instant minus the specified number of nanoseconds
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the resultant instant exceeds the supported range
    • minus

      @ScriptApi @Nullable public static @Nullable ZonedDateTime minus(@Nullable @Nullable ZonedDateTime dateTime, long nanos)
      Subtracts nanoseconds from a ZonedDateTime.
      Parameters:
      dateTime - starting zoned date time value
      nanos - number of nanoseconds to subtract
      Returns:
      null if either input is null or QueryConstants.NULL_LONG; otherwise the starting zoned date time minus the specified number of nanoseconds
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the resultant zoned date time exceeds the supported range
    • minus

      @ScriptApi @Nullable public static @Nullable Instant minus(@Nullable @Nullable Instant instant, @Nullable @Nullable Duration duration)
      Subtracts a time period to an Instant.
      Parameters:
      instant - starting instant value
      duration - time period
      Returns:
      null if either input is null or QueryConstants.NULL_LONG; otherwise the starting instant minus the specified time period
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the resultant instant exceeds the supported range
    • minus

      @ScriptApi @Nullable public static @Nullable Instant minus(@Nullable @Nullable Instant instant, @Nullable @Nullable Period period)
      Subtracts a time period to an Instant.
      Parameters:
      instant - starting instant value
      period - time period
      Returns:
      null if either input is null or QueryConstants.NULL_LONG; otherwise the starting instant minus the specified time period
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the resultant instant exceeds the supported range
    • minus

      @ScriptApi @Nullable public static @Nullable ZonedDateTime minus(@Nullable @Nullable ZonedDateTime dateTime, @Nullable @Nullable Duration duration)
      Subtracts a time period to a ZonedDateTime.
      Parameters:
      dateTime - starting zoned date time value
      duration - time period
      Returns:
      null if either input is null or QueryConstants.NULL_LONG; otherwise the starting zoned date time minus the specified time period
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the resultant zoned date time exceeds the supported range
    • minus

      @ScriptApi @Nullable public static @Nullable ZonedDateTime minus(@Nullable @Nullable ZonedDateTime dateTime, @Nullable @Nullable Period period)
      Subtracts a time period to a ZonedDateTime.
      Parameters:
      dateTime - starting zoned date time value
      period - time period
      Returns:
      null if either input is null or QueryConstants.NULL_LONG; otherwise the starting zoned date time minus the specified time period
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the resultant zoned date time exceeds the supported range
    • minus

      @ScriptApi public static long minus(@Nullable @Nullable Instant instant1, @Nullable @Nullable Instant instant2)
      Subtract one instant from another and return the difference in nanoseconds.
      Parameters:
      instant1 - first instant
      instant2 - second instant
      Returns:
      QueryConstants.NULL_LONG if either input is null; otherwise the difference in instant1 and instant2 in nanoseconds
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the datetime arithmetic overflows or underflows
    • minus

      @ScriptApi public static long minus(@Nullable @Nullable ZonedDateTime dateTime1, @Nullable @Nullable ZonedDateTime dateTime2)
      Subtract one zoned date time from another and return the difference in nanoseconds.
      Parameters:
      dateTime1 - first zoned date time
      dateTime2 - second zoned date time
      Returns:
      QueryConstants.NULL_LONG if either input is null; otherwise the difference in dateTime1 and dateTime2 in nanoseconds
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the datetime arithmetic overflows or underflows
    • diffNanos

      @ScriptApi public static long diffNanos(@Nullable @Nullable Instant start, @Nullable @Nullable Instant end)
      Returns the difference in nanoseconds between two instant values.
      Parameters:
      start - start time
      end - end time
      Returns:
      QueryConstants.NULL_LONG if either input is null; otherwise the difference in start and end in nanoseconds
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the datetime arithmetic overflows or underflows
    • diffNanos

      @ScriptApi public static long diffNanos(@Nullable @Nullable ZonedDateTime start, @Nullable @Nullable ZonedDateTime end)
      Returns the difference in nanoseconds between two zoned date time values.
      Parameters:
      start - start time
      end - end time
      Returns:
      QueryConstants.NULL_LONG if either input is null; otherwise the difference in start and end in nanoseconds
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the datetime arithmetic overflows or underflows
    • diffMicros

      @ScriptApi public static long diffMicros(@Nullable @Nullable Instant start, @Nullable @Nullable Instant end)
      Returns the difference in microseconds between two instant values.
      Parameters:
      start - start time
      end - end time
      Returns:
      QueryConstants.NULL_LONG if either input is null; otherwise the difference in start and end in microseconds
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the datetime arithmetic overflows or underflows
    • diffMicros

      @ScriptApi public static long diffMicros(@Nullable @Nullable ZonedDateTime start, @Nullable @Nullable ZonedDateTime end)
      Returns the difference in microseconds between two zoned date time values.
      Parameters:
      start - start time
      end - end time
      Returns:
      QueryConstants.NULL_LONG if either input is null; otherwise the difference in start and end in microseconds
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the datetime arithmetic overflows or underflows
    • diffMillis

      @ScriptApi public static long diffMillis(@Nullable @Nullable Instant start, @Nullable @Nullable Instant end)
      Returns the difference in milliseconds between two instant values.
      Parameters:
      start - start time
      end - end time
      Returns:
      QueryConstants.NULL_LONG if either input is null; otherwise the difference in start and end in milliseconds
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the datetime arithmetic overflows or underflows
    • diffMillis

      @ScriptApi public static long diffMillis(@Nullable @Nullable ZonedDateTime start, @Nullable @Nullable ZonedDateTime end)
      Returns the difference in milliseconds between two zoned date time values.
      Parameters:
      start - start time
      end - end time
      Returns:
      QueryConstants.NULL_LONG if either input is null; otherwise the difference in start and end in milliseconds
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the datetime arithmetic overflows or underflows
    • diffSeconds

      @ScriptApi public static double diffSeconds(@Nullable @Nullable Instant start, @Nullable @Nullable Instant end)
      Returns the difference in seconds between two instant values.
      Parameters:
      start - start time
      end - end time
      Returns:
      QueryConstants.NULL_DOUBLE if either input is null; otherwise the difference in start and end in seconds
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the datetime arithmetic overflows or underflows
    • diffSeconds

      @ScriptApi public static double diffSeconds(@Nullable @Nullable ZonedDateTime start, @Nullable @Nullable ZonedDateTime end)
      Returns the difference in seconds between two zoned date time values.
      Parameters:
      start - start time
      end - end time
      Returns:
      QueryConstants.NULL_DOUBLE if either input is null; otherwise the difference in start and end in seconds
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the datetime arithmetic overflows or underflows
    • diffMinutes

      @ScriptApi public static double diffMinutes(@Nullable @Nullable Instant start, @Nullable @Nullable Instant end)
      Returns the difference in minutes between two instant values.
      Parameters:
      start - start time
      end - end time
      Returns:
      QueryConstants.NULL_DOUBLE if either input is null; otherwise the difference in start and end in minutes
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the datetime arithmetic overflows or underflows
    • diffMinutes

      @ScriptApi public static double diffMinutes(@Nullable @Nullable ZonedDateTime start, @Nullable @Nullable ZonedDateTime end)
      Returns the difference in minutes between two zoned date time values.
      Parameters:
      start - start time
      end - end time
      Returns:
      QueryConstants.NULL_DOUBLE if either input is null; otherwise the difference in start and end in minutes
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the datetime arithmetic overflows or underflows
    • diffDays

      @ScriptApi public static double diffDays(@Nullable @Nullable Instant start, @Nullable @Nullable Instant end)
      Returns the difference in days between two instant values.
      Parameters:
      start - start time
      end - end time
      Returns:
      QueryConstants.NULL_DOUBLE if either input is null; otherwise the difference in start and end in days
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the datetime arithmetic overflows or underflows
    • diffDays

      @ScriptApi public static double diffDays(@Nullable @Nullable ZonedDateTime start, @Nullable @Nullable ZonedDateTime end)
      Returns the difference in days between two zoned date time values.
      Parameters:
      start - start time
      end - end time
      Returns:
      QueryConstants.NULL_DOUBLE if either input is null; otherwise the difference in start and end in days
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the datetime arithmetic overflows or underflows
    • diffYears365

      @ScriptApi public static double diffYears365(@Nullable @Nullable Instant start, @Nullable @Nullable Instant end)
      Returns the difference in years between two instant values.

      Years are defined in terms of 365 day years.

      Parameters:
      start - start time
      end - end time
      Returns:
      QueryConstants.NULL_DOUBLE if either input is null; otherwise the difference in start and end in years
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the datetime arithmetic overflows or underflows
    • diffYears365

      @ScriptApi public static double diffYears365(@Nullable @Nullable ZonedDateTime start, @Nullable @Nullable ZonedDateTime end)
      Returns the difference in years between two zoned date time values.

      Years are defined in terms of 365 day years.

      Parameters:
      start - start time
      end - end time
      Returns:
      QueryConstants.NULL_DOUBLE if either input is null; otherwise the difference in start and end in years
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the datetime arithmetic overflows or underflows
    • diffYearsAvg

      @ScriptApi public static double diffYearsAvg(@Nullable @Nullable Instant start, @Nullable @Nullable Instant end)
      Returns the difference in years between two instant values.

      Years are defined in terms of 365.2425 day years.

      Parameters:
      start - start time
      end - end time
      Returns:
      QueryConstants.NULL_DOUBLE if either input is null; otherwise the difference in start and end in years
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the datetime arithmetic overflows or underflows
    • diffYearsAvg

      @ScriptApi public static double diffYearsAvg(@Nullable @Nullable ZonedDateTime start, @Nullable @Nullable ZonedDateTime end)
      Returns the difference in years between two zoned date time values.

      Years are defined in terms of 365.2425 day years.

      Parameters:
      start - start time
      end - end time
      Returns:
      QueryConstants.NULL_DOUBLE if either input is null; otherwise the difference in start and end in years
      Throws:
      DateTimeUtils.DateTimeOverflowException - if the datetime arithmetic overflows or underflows
    • isBefore

      @ScriptApi public static boolean isBefore(@Nullable @Nullable Instant instant1, @Nullable @Nullable Instant instant2)
      Evaluates whether one instant value is before a second instant value.
      Parameters:
      instant1 - first instant
      instant2 - second instant
      Returns:
      true if instant1 is before instant2; otherwise, false if either value is null or if instant2 is equal to or before instant1
    • isBefore

      @ScriptApi public static boolean isBefore(@Nullable @Nullable ZonedDateTime dateTime1, @Nullable @Nullable ZonedDateTime dateTime2)
      Evaluates whether one zoned date time value is before a second zoned date time value.
      Parameters:
      dateTime1 - first zoned date time
      dateTime2 - second zoned date time
      Returns:
      true if dateTime1 is before dateTime2; otherwise, false if either value is null or if dateTime2 is equal to or before dateTime1
    • isBeforeOrEqual

      @ScriptApi public static boolean isBeforeOrEqual(@Nullable @Nullable Instant instant1, @Nullable @Nullable Instant instant2)
      Evaluates whether one instant value is before or equal to a second instant value.
      Parameters:
      instant1 - first instant
      instant2 - second instant
      Returns:
      true if instant1 is before or equal to instant2; otherwise, false if either value is null or if instant2 is before instant1
    • isBeforeOrEqual

      @ScriptApi public static boolean isBeforeOrEqual(@Nullable @Nullable ZonedDateTime dateTime1, @Nullable @Nullable ZonedDateTime dateTime2)
      Evaluates whether one zoned date time value is before or equal to a second zoned date time value.
      Parameters:
      dateTime1 - first zoned date time
      dateTime2 - second zoned date time
      Returns:
      true if dateTime1 is before or equal to dateTime2; otherwise, false if either value is null or if dateTime2 is before dateTime1
    • isAfter

      @ScriptApi public static boolean isAfter(@Nullable @Nullable Instant instant1, @Nullable @Nullable Instant instant2)
      Evaluates whether one instant value is after a second instant value.
      Parameters:
      instant1 - first instant
      instant2 - second instant
      Returns:
      true if instant1 is after instant2; otherwise, false if either value is null or if instant2 is equal to or after instant1
    • isAfter

      @ScriptApi public static boolean isAfter(@Nullable @Nullable ZonedDateTime dateTime1, @Nullable @Nullable ZonedDateTime dateTime2)
      Evaluates whether one zoned date time value is after a second zoned date time value.
      Parameters:
      dateTime1 - first zoned date time
      dateTime2 - second zoned date time
      Returns:
      true if dateTime1 is after dateTime2; otherwise, false if either value is null or if dateTime2 is equal to or after dateTime1
    • isAfterOrEqual

      @ScriptApi public static boolean isAfterOrEqual(@Nullable @Nullable Instant instant1, @Nullable @Nullable Instant instant2)
      Evaluates whether one instant value is after or equal to a second instant value.
      Parameters:
      instant1 - first instant
      instant2 - second instant
      Returns:
      true if instant1 is after or equal to instant2; otherwise, false if either value is null or if instant2 is after instant1
    • isAfterOrEqual

      @ScriptApi public static boolean isAfterOrEqual(@Nullable @Nullable ZonedDateTime dateTime1, @Nullable @Nullable ZonedDateTime dateTime2)
      Evaluates whether one zoned date time value is after or equal to a second zoned date time value.
      Parameters:
      dateTime1 - first zoned date time
      dateTime2 - second zoned date time
      Returns:
      true if dateTime1 is after or equal to dateTime2; otherwise, false if either value is null or if dateTime2 is after dateTime1
    • nanosOfMilli

      @ScriptApi public static int nanosOfMilli(@Nullable @Nullable Instant instant)
      Returns the number of nanoseconds that have elapsed since the top of the millisecond.
      Parameters:
      instant - time
      Returns:
      QueryConstants.NULL_INT if the input is null; otherwise, number of nanoseconds that have elapsed since the top of the millisecond
    • nanosOfMilli

      @ScriptApi public static int nanosOfMilli(@Nullable @Nullable ZonedDateTime dateTime)
      Returns the number of nanoseconds that have elapsed since the top of the millisecond.
      Parameters:
      dateTime - time
      Returns:
      QueryConstants.NULL_INT if the input is null; otherwise, number of nanoseconds that have elapsed since the top of the millisecond
    • microsOfMilli

      @ScriptApi public static int microsOfMilli(@Nullable @Nullable Instant instant)
      Returns the number of microseconds that have elapsed since the top of the millisecond. Nanoseconds are rounded, not dropped -- '20:41:39.123456700' has 457 micros, not 456.
      Parameters:
      instant - time
      Returns:
      QueryConstants.NULL_INT if the input is null; otherwise, number of microseconds that have elapsed since the top of the millisecond
    • microsOfMilli

      @ScriptApi public static int microsOfMilli(@Nullable @Nullable ZonedDateTime dateTime)
      Returns the number of microseconds that have elapsed since the top of the millisecond. Nanoseconds are rounded, not dropped -- '20:41:39.123456700' has 457 micros, not 456.
      Parameters:
      dateTime - time
      Returns:
      QueryConstants.NULL_INT if the input is null; otherwise, number of microseconds that have elapsed since the top of the millisecond
    • nanosOfSecond

      @ScriptApi public static long nanosOfSecond(@Nullable @Nullable Instant instant, @Nullable @Nullable ZoneId timeZone)
      Returns the number of nanoseconds that have elapsed since the top of the second.
      Parameters:
      instant - time
      timeZone - time zone
      Returns:
      QueryConstants.NULL_LONG if either input is null; otherwise, number of nanoseconds that have elapsed since the top of the second
    • nanosOfSecond

      @ScriptApi public static long nanosOfSecond(@Nullable @Nullable ZonedDateTime dateTime)
      Returns the number of nanoseconds that have elapsed since the top of the second.
      Parameters:
      dateTime - time
      Returns:
      QueryConstants.NULL_LONG if either input is null; otherwise, number of nanoseconds that have elapsed since the top of the second
    • microsOfSecond

      @ScriptApi public static long microsOfSecond(@Nullable @Nullable Instant instant, @Nullable @Nullable ZoneId timeZone)
      Returns the number of microseconds that have elapsed since the top of the second.
      Parameters:
      instant - time
      timeZone - time zone
      Returns:
      QueryConstants.NULL_LONG if either input is null; otherwise, number of microseconds that have elapsed since the top of the second
    • microsOfSecond

      @ScriptApi public static long microsOfSecond(@Nullable @Nullable ZonedDateTime dateTime)
      Returns the number of microseconds that have elapsed since the top of the second.
      Parameters:
      dateTime - time
      Returns:
      QueryConstants.NULL_LONG if either input is null; otherwise, number of microseconds that have elapsed since the top of the second
    • millisOfSecond

      @ScriptApi public static int millisOfSecond(@Nullable @Nullable Instant instant, @Nullable @Nullable ZoneId timeZone)
      Returns the number of milliseconds that have elapsed since the top of the second.
      Parameters:
      instant - time
      timeZone - time zone
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, number of milliseconds that have elapsed since the top of the second
    • millisOfSecond

      @ScriptApi public static int millisOfSecond(@Nullable @Nullable ZonedDateTime dateTime)
      Returns the number of milliseconds that have elapsed since the top of the second.
      Parameters:
      dateTime - time
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, number of milliseconds that have elapsed since the top of the second
    • secondOfMinute

      @ScriptApi public static int secondOfMinute(@Nullable @Nullable Instant instant, @Nullable @Nullable ZoneId timeZone)
      Returns the number of seconds that have elapsed since the top of the minute.
      Parameters:
      instant - time
      timeZone - time zone
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, number of seconds that have elapsed since the top of the minute
    • secondOfMinute

      @ScriptApi public static int secondOfMinute(@Nullable @Nullable ZonedDateTime dateTime)
      Returns the number of seconds that have elapsed since the top of the minute.
      Parameters:
      dateTime - time
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, number of seconds that have elapsed since the top of the minute
    • minuteOfHour

      @ScriptApi public static int minuteOfHour(@Nullable @Nullable Instant instant, @Nullable @Nullable ZoneId timeZone)
      Returns the number of minutes that have elapsed since the top of the hour.
      Parameters:
      instant - time
      timeZone - time zone
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, number of minutes that have elapsed since the top of the hour
    • minuteOfHour

      @ScriptApi public static int minuteOfHour(@Nullable @Nullable ZonedDateTime dateTime)
      Returns the number of minutes that have elapsed since the top of the hour.
      Parameters:
      dateTime - time
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, number of minutes that have elapsed since the top of the hour
    • nanosOfDay

      @ScriptApi public static long nanosOfDay(@Nullable @Nullable Instant instant, @Nullable @Nullable ZoneId timeZone)
      Returns the number of nanoseconds that have elapsed since the top of the day.

      On days when daylight savings time events occur, results may be different from what is expected based upon the local time. For example, on daylight savings time change days, 9:30AM may be earlier or later in the day based upon if the daylight savings time adjustment is forwards or backwards.

      Parameters:
      instant - time
      timeZone - time zone
      Returns:
      QueryConstants.NULL_LONG if either input is null; otherwise, number of nanoseconds that have elapsed since the top of the day
    • nanosOfDay

      @ScriptApi public static long nanosOfDay(@Nullable @Nullable ZonedDateTime dateTime)
      Returns the number of nanoseconds that have elapsed since the top of the day.

      On days when daylight savings time events occur, results may be different from what is expected based upon the local time. For example, on daylight savings time change days, 9:30AM may be earlier or later in the day based upon if the daylight savings time adjustment is forwards or backwards.

      Parameters:
      dateTime - time
      Returns:
      QueryConstants.NULL_LONG if either input is null; otherwise, number of nanoseconds that have elapsed since the top of the day
    • nanosOfDay

      public static long nanosOfDay(@Nullable @Nullable LocalTime localTime)
      Returns the number of nanoseconds that have elapsed since the top of the day.
      Parameters:
      localTime - time
      Returns:
      QueryConstants.NULL_LONG if input is null; otherwise, number of nanoseconds that have elapsed since the top of the day
    • millisOfDay

      @ScriptApi public static int millisOfDay(@Nullable @Nullable Instant instant, @Nullable @Nullable ZoneId timeZone)
      Returns the number of milliseconds that have elapsed since the top of the day.

      On days when daylight savings time events occur, results may be different from what is expected based upon the local time. For example, on daylight savings time change days, 9:30AM may be earlier or later in the day based upon if the daylight savings time adjustment is forwards or backwards.

      Parameters:
      instant - time
      timeZone - time zone
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, number of milliseconds that have elapsed since the top of the day
    • millisOfDay

      @ScriptApi public static int millisOfDay(@Nullable @Nullable ZonedDateTime dateTime)
      Returns the number of milliseconds that have elapsed since the top of the day.

      On days when daylight savings time events occur, results may be different from what is expected based upon the local time. For example, on daylight savings time change days, 9:30AM may be earlier or later in the day based upon if the daylight savings time adjustment is forwards or backwards.

      Parameters:
      dateTime - time
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, number of milliseconds that have elapsed since the top of the day
    • secondOfDay

      @ScriptApi public static int secondOfDay(@Nullable @Nullable Instant instant, @Nullable @Nullable ZoneId timeZone)
      Returns the number of seconds that have elapsed since the top of the day.

      On days when daylight savings time events occur, results may be different from what is expected based upon the local time. For example, on daylight savings time change days, 9:30AM may be earlier or later in the day based upon if the daylight savings time adjustment is forwards or backwards.

      Parameters:
      instant - time
      timeZone - time zone
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, number of seconds that have elapsed since the top of the day
    • secondOfDay

      @ScriptApi public static int secondOfDay(@Nullable @Nullable ZonedDateTime dateTime)
      Returns the number of seconds that have elapsed since the top of the day.

      On days when daylight savings time events occur, results may be different from what is expected based upon the local time. For example, on daylight savings time change days, 9:30AM may be earlier or later in the day based upon if the daylight savings time adjustment is forwards or backwards.

      Parameters:
      dateTime - time
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, number of seconds that have elapsed since the top of the day
    • minuteOfDay

      @ScriptApi public static int minuteOfDay(@Nullable @Nullable Instant instant, @Nullable @Nullable ZoneId timeZone)
      Returns the number of minutes that have elapsed since the top of the day.

      On days when daylight savings time events occur, results may be different from what is expected based upon the local time. For example, on daylight savings time change days, 9:30AM may be earlier or later in the day based upon if the daylight savings time adjustment is forwards or backwards.

      Parameters:
      instant - time
      timeZone - time zone
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, number of minutes that have elapsed since the top of the day
    • minuteOfDay

      @ScriptApi public static int minuteOfDay(@Nullable @Nullable ZonedDateTime dateTime)
      Returns the number of minutes that have elapsed since the top of the day.

      On days when daylight savings time events occur, results may be different from what is expected based upon the local time. For example, on daylight savings time change days, 9:30AM may be earlier or later in the day based upon if the daylight savings time adjustment is forwards or backwards.

      Parameters:
      dateTime - time
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, number of minutes that have elapsed since the top of the day
    • hourOfDay

      @ScriptApi public static int hourOfDay(@Nullable @Nullable Instant instant, @Nullable @Nullable ZoneId timeZone)
      Returns the number of hours that have elapsed since the top of the day.

      On days when daylight savings time events occur, results may be different from what is expected based upon the local time. For example, on daylight savings time change days, 9:30AM may be earlier or later in the day based upon if the daylight savings time adjustment is forwards or backwards.

      Parameters:
      instant - time
      timeZone - time zone
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, number of hours that have elapsed since the top of the day
    • hourOfDay

      @ScriptApi public static int hourOfDay(@Nullable @Nullable ZonedDateTime dateTime)
      Returns the number of hours that have elapsed since the top of the day.

      On days when daylight savings time events occur, results may be different from what is expected based upon the local time. For example, on daylight savings time change days, 9:30AM may be earlier or later in the day based upon if the daylight savings time adjustment is forwards or backwards.

      Parameters:
      dateTime - time
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, number of hours that have elapsed since the top of the day
    • dayOfWeek

      @ScriptApi public static DayOfWeek dayOfWeek(@Nullable @Nullable LocalDate date)
      Returns athe day of the week for a ZonedDateTime in the specified time zone.
      Parameters:
      date - date to find the day of the week of
      Returns:
      null if either input is null; otherwise, the day of the week
    • dayOfWeek

      @ScriptApi public static DayOfWeek dayOfWeek(@Nullable @Nullable Instant instant, @Nullable @Nullable ZoneId timeZone)
      Returns the day of the week for an Instant in the specified time zone.
      Parameters:
      instant - time to find the day of the week of
      timeZone - time zone
      Returns:
      null if either input is null; otherwise, the day of the week
    • dayOfWeek

      @ScriptApi public static DayOfWeek dayOfWeek(@Nullable @Nullable ZonedDateTime dateTime)
      Returns the day of the week for a ZonedDateTime in the specified time zone.
      Parameters:
      dateTime - time to find the day of the week of
      Returns:
      null if either input is null; otherwise, the day of the week
    • dayOfWeekValue

      @ScriptApi public static int dayOfWeekValue(@Nullable @Nullable LocalDate date)
      Returns a 1-based int value of the day of the week for a ZonedDateTime in the specified time zone, with 1 being Monday and 7 being Sunday.
      Parameters:
      date - date to find the day of the week of
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, the day of the week
    • dayOfWeekValue

      @ScriptApi public static int dayOfWeekValue(@Nullable @Nullable Instant instant, @Nullable @Nullable ZoneId timeZone)
      Returns a 1-based int value of the day of the week for an Instant in the specified time zone, with 1 being Monday and 7 being Sunday.
      Parameters:
      instant - time to find the day of the week of
      timeZone - time zone
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, the day of the week
    • dayOfWeekValue

      @ScriptApi public static int dayOfWeekValue(@Nullable @Nullable ZonedDateTime dateTime)
      Returns a 1-based int value of the day of the week for a ZonedDateTime in the specified time zone, with 1 being Monday and 7 being Sunday.
      Parameters:
      dateTime - time to find the day of the week of
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, the day of the week
    • dayOfMonth

      @ScriptApi public static int dayOfMonth(@Nullable @Nullable LocalDate date)
      Returns a 1-based int value of the day of the month for a ZonedDateTime and specified time zone. The first day of the month returns 1, the second day returns 2, etc.
      Parameters:
      date - date to find the day of the month of
      Returns:
      A QueryConstants.NULL_INT if either input is null; otherwise, the day of the month
    • dayOfMonth

      @ScriptApi public static int dayOfMonth(@Nullable @Nullable Instant instant, @Nullable @Nullable ZoneId timeZone)
      Returns a 1-based int value of the day of the month for an Instant and specified time zone. The first day of the month returns 1, the second day returns 2, etc.
      Parameters:
      instant - time to find the day of the month of
      timeZone - time zone
      Returns:
      A QueryConstants.NULL_INT if either input is null; otherwise, the day of the month
    • dayOfMonth

      @ScriptApi public static int dayOfMonth(@Nullable @Nullable ZonedDateTime dateTime)
      Returns a 1-based int value of the day of the month for a ZonedDateTime and specified time zone. The first day of the month returns 1, the second day returns 2, etc.
      Parameters:
      dateTime - time to find the day of the month of
      Returns:
      A QueryConstants.NULL_INT if either input is null; otherwise, the day of the month
    • dayOfYear

      @ScriptApi public static int dayOfYear(@Nullable @Nullable LocalDate date)
      Returns a 1-based int value of the day of the year (Julian date) for a ZonedDateTime in the specified time zone. The first day of the year returns 1, the second day returns 2, etc.
      Parameters:
      date - date to find the day of the year of
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, the day of the year
    • dayOfYear

      @ScriptApi public static int dayOfYear(@Nullable @Nullable Instant instant, @Nullable @Nullable ZoneId timeZone)
      Returns a 1-based int value of the day of the year (Julian date) for an Instant in the specified time zone. The first day of the year returns 1, the second day returns 2, etc.
      Parameters:
      instant - time to find the day of the year of
      timeZone - time zone
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, the day of the year
    • dayOfYear

      @ScriptApi public static int dayOfYear(@Nullable @Nullable ZonedDateTime dateTime)
      Returns a 1-based int value of the day of the year (Julian date) for a ZonedDateTime in the specified time zone. The first day of the year returns 1, the second day returns 2, etc.
      Parameters:
      dateTime - time to find the day of the year of
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, the day of the year
    • monthOfYear

      @ScriptApi public static int monthOfYear(@Nullable @Nullable LocalDate date)
      Returns a 1-based int value of the month of the year (Julian date) for a LocalDate. January is 1, February is 2, etc.
      Parameters:
      date - date to find the month of the year of
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, the month of the year
    • monthOfYear

      @ScriptApi public static int monthOfYear(@Nullable @Nullable Instant instant, @Nullable @Nullable ZoneId timeZone)
      Returns a 1-based int value of the month of the year (Julian date) for an Instant in the specified time zone. January is 1, February is 2, etc.
      Parameters:
      instant - time to find the month of the year of
      timeZone - time zone
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, the month of the year
    • monthOfYear

      @ScriptApi public static int monthOfYear(@Nullable @Nullable ZonedDateTime dateTime)
      Returns a 1-based int value of the month of the year (Julian date) for a ZonedDateTime in the specified time zone. January is 1, February is 2, etc.
      Parameters:
      dateTime - time to find the month of the year of
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, the month of the year
    • year

      @ScriptApi public static int year(@Nullable @Nullable LocalDate date)
      Returns the year for a LocalDate.
      Parameters:
      date - date to find the year of
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, the year
    • year

      @ScriptApi public static int year(@Nullable @Nullable Instant instant, @Nullable @Nullable ZoneId timeZone)
      Returns the year for an Instant in the specified time zone.
      Parameters:
      instant - time to find the year of
      timeZone - time zone
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, the year
    • year

      @ScriptApi public static int year(@Nullable @Nullable ZonedDateTime dateTime)
      Returns the year for a ZonedDateTime in the specified time zone.
      Parameters:
      dateTime - time to find the year of
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, the year
    • yearOfCentury

      @ScriptApi public static int yearOfCentury(@Nullable @Nullable LocalDate date)
      Returns the year of the century (two-digit year) for a LocalDate in the specified time zone.
      Parameters:
      date - date to find the year of
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, the year of the century (two-digit year)
    • yearOfCentury

      @ScriptApi public static int yearOfCentury(@Nullable @Nullable Instant instant, @Nullable @Nullable ZoneId timeZone)
      Returns the year of the century (two-digit year) for an Instant in the specified time zone.
      Parameters:
      instant - time to find the year of
      timeZone - time zone
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, the year of the century (two-digit year)
    • yearOfCentury

      @ScriptApi public static int yearOfCentury(@Nullable @Nullable ZonedDateTime dateTime)
      Returns the year of the century (two-digit year) for a ZonedDateTime in the specified time zone.
      Parameters:
      dateTime - time to find the day of the month of
      Returns:
      QueryConstants.NULL_INT if either input is null; otherwise, the year of the century (two-digit year)
    • atMidnight

      @ScriptApi @Nullable public static @Nullable ZonedDateTime atMidnight(@Nullable @Nullable LocalDate date, @Nullable @Nullable ZoneId timeZone)
      Returns an ZonedDateTime for the prior midnight in the specified time zone.
      Parameters:
      date - date to compute the prior midnight for
      timeZone - time zone
      Returns:
      null if either input is null; otherwise an ZonedDateTime representing the prior midnight in the specified time zone
    • atMidnight

      @ScriptApi @Nullable public static @Nullable Instant atMidnight(@Nullable @Nullable Instant instant, @Nullable @Nullable ZoneId timeZone)
      Returns an Instant for the prior midnight in the specified time zone.
      Parameters:
      instant - time to compute the prior midnight for
      timeZone - time zone
      Returns:
      null if either input is null; otherwise an Instant representing the prior midnight in the specified time zone
    • atMidnight

      @ScriptApi @Nullable public static @Nullable ZonedDateTime atMidnight(@Nullable @Nullable ZonedDateTime dateTime)
      Returns a ZonedDateTime for the prior midnight in the specified time zone.
      Parameters:
      dateTime - time to compute the prior midnight for
      Returns:
      null if either input is null; otherwise a ZonedDateTime representing the prior midnight in the specified time zone
    • lowerBin

      @ScriptApi @Nullable public static @Nullable Instant lowerBin(@Nullable @Nullable Instant instant, long intervalNanos)
      Returns an Instant value, which is at the starting (lower) end of a time range defined by the interval nanoseconds. For example, a 5*MINUTE intervalNanos value would return the instant value for the start of the five-minute window that contains the input instant.
      Parameters:
      instant - instant for which to evaluate the start of the containing window
      intervalNanos - size of the window in nanoseconds
      Returns:
      null if either input is null; otherwise, an Instant representing the start of the window
    • lowerBin

      @ScriptApi @Nullable public static @Nullable ZonedDateTime lowerBin(@Nullable @Nullable ZonedDateTime dateTime, long intervalNanos)
      Returns a ZonedDateTime value, which is at the starting (lower) end of a time range defined by the interval nanoseconds. For example, a 5*MINUTE intervalNanos value would return the zoned date time value for the start of the five-minute window that contains the input zoned date time.
      Parameters:
      dateTime - zoned date time for which to evaluate the start of the containing window
      intervalNanos - size of the window in nanoseconds
      Returns:
      null if either input is null; otherwise, a ZonedDateTime representing the start of the window
    • lowerBin

      @ScriptApi @Nullable public static @Nullable Instant lowerBin(@Nullable @Nullable Instant instant, long intervalNanos, long offset)
      Returns an Instant value, which is at the starting (lower) end of a time range defined by the interval nanoseconds. For example, a 5*MINUTE intervalNanos value would return the instant value for the start of the five-minute window that contains the input instant.
      Parameters:
      instant - instant for which to evaluate the start of the containing window
      intervalNanos - size of the window in nanoseconds
      offset - The window start offset in nanoseconds. For example, a value of MINUTE would offset all windows by one minute.
      Returns:
      null if either input is null; otherwise, an Instant representing the start of the window
    • lowerBin

      @ScriptApi @Nullable public static @Nullable ZonedDateTime lowerBin(@Nullable @Nullable ZonedDateTime dateTime, long intervalNanos, long offset)
      Returns a ZonedDateTime value, which is at the starting (lower) end of a time range defined by the interval nanoseconds. For example, a 5*MINUTE intervalNanos value would return the zoned date time value for the start of the five-minute window that contains the input zoned date time.
      Parameters:
      dateTime - zoned date time for which to evaluate the start of the containing window
      intervalNanos - size of the window in nanoseconds
      offset - The window start offset in nanoseconds. For example, a value of MINUTE would offset all windows by one minute.
      Returns:
      null if either input is null; otherwise, a ZonedDateTime representing the start of the window
    • upperBin

      @ScriptApi @Nullable public static @Nullable Instant upperBin(@Nullable @Nullable Instant instant, long intervalNanos)
      Returns an Instant value, which is at the ending (upper) end of a time range defined by the interval nanoseconds. For example, a 5*MINUTE intervalNanos value would return the instant value for the end of the five-minute window that contains the input instant.
      Parameters:
      instant - instant for which to evaluate the start of the containing window
      intervalNanos - size of the window in nanoseconds
      Returns:
      null if either input is null; otherwise, an Instant representing the end of the window
    • upperBin

      @ScriptApi @Nullable public static @Nullable ZonedDateTime upperBin(@Nullable @Nullable ZonedDateTime dateTime, long intervalNanos)
      Returns a ZonedDateTime value, which is at the ending (upper) end of a time range defined by the interval nanoseconds. For example, a 5*MINUTE intervalNanos value would return the zoned date time value for the end of the five-minute window that contains the input zoned date time.
      Parameters:
      dateTime - zoned date time for which to evaluate the start of the containing window
      intervalNanos - size of the window in nanoseconds
      Returns:
      null if either input is null; otherwise, a ZonedDateTime representing the end of the window
    • upperBin

      @ScriptApi @Nullable public static @Nullable Instant upperBin(@Nullable @Nullable Instant instant, long intervalNanos, long offset)
      Returns an Instant value, which is at the ending (upper) end of a time range defined by the interval nanoseconds. For example, a 5*MINUTE intervalNanos value would return the instant value for the end of the five-minute window that contains the input instant.
      Parameters:
      instant - instant for which to evaluate the start of the containing window
      intervalNanos - size of the window in nanoseconds
      offset - The window start offset in nanoseconds. For example, a value of MINUTE would offset all windows by one minute.
      Returns:
      null if either input is null; otherwise, an Instant representing the end of the window
    • upperBin

      @ScriptApi @Nullable public static @Nullable ZonedDateTime upperBin(@Nullable @Nullable ZonedDateTime dateTime, long intervalNanos, long offset)
      Returns a ZonedDateTime value, which is at the ending (upper) end of a time range defined by the interval nanoseconds. For example, a 5*MINUTE intervalNanos value would return the zoned date time value for the end of the five-minute window that contains the input zoned date time.
      Parameters:
      dateTime - zoned date time for which to evaluate the start of the containing window
      intervalNanos - size of the window in nanoseconds
      offset - The window start offset in nanoseconds. For example, a value of MINUTE would offset all windows by one minute.
      Returns:
      null if either input is null; otherwise, a ZonedDateTime representing the end of the window
    • formatDurationNanos

      @ScriptApi @Nullable public static @Nullable String formatDurationNanos(long nanos)
      Returns a nanosecond duration formatted as a "[-]PThhh:mm:ss.nnnnnnnnn" string.
      Parameters:
      nanos - nanoseconds, or null if the input is QueryConstants.NULL_LONG
      Returns:
      the nanosecond duration formatted as a "[-]PThhh:mm:ss.nnnnnnnnn" string
    • formatDateTime

      @ScriptApi @Nullable public static @Nullable String formatDateTime(@Nullable @Nullable Instant instant, @Nullable @Nullable ZoneId timeZone)
      Returns an Instant formatted as a "yyyy-MM-ddThh:mm:ss.SSSSSSSSS TZ" string.
      Parameters:
      instant - time to format as a string
      timeZone - time zone to use when formatting the string.
      Returns:
      null if either input is null; otherwise, the time formatted as a "yyyy-MM-ddThh:mm:ss.nnnnnnnnn TZ" string
    • formatDateTime

      @ScriptApi @Nullable public static @Nullable String formatDateTime(@Nullable @Nullable ZonedDateTime dateTime)
      Returns a ZonedDateTime formatted as a "yyyy-MM-ddThh:mm:ss.SSSSSSSSS TZ" string.
      Parameters:
      dateTime - time to format as a string
      Returns:
      null if either input is null; otherwise, the time formatted as a "yyyy-MM-ddThh:mm:ss.nnnnnnnnn TZ" string
    • formatDate

      @ScriptApi @Nullable public static @Nullable String formatDate(@Nullable @Nullable Instant instant, @Nullable @Nullable ZoneId timeZone)
      Returns an Instant formatted as a "yyyy-MM-dd" string.
      Parameters:
      instant - time to format as a string
      timeZone - time zone to use when formatting the string.
      Returns:
      null if either input is null; otherwise, the time formatted as a "yyyy-MM-dd" string
    • formatDate

      @ScriptApi @Nullable public static @Nullable String formatDate(@Nullable @Nullable ZonedDateTime dateTime)
      Returns a ZonedDateTime formatted as a "yyyy-MM-dd" string.
      Parameters:
      dateTime - time to format as a string
      Returns:
      null if either input is null; otherwise, the time formatted as a "yyyy-MM-dd" string
    • formatDate

      @ScriptApi @Nullable public static @Nullable String formatDate(@Nullable @Nullable LocalDate date)
      Returns a LocalDate formatted as a "yyyy-MM-dd" string.
      Parameters:
      date - date to format as a string
      Returns:
      null if either input is null; otherwise, the time formatted as a "yyyy-MM-dd" string
    • parseTimeZone

      @ScriptApi @NotNull public static @NotNull ZoneId parseTimeZone(@NotNull @NotNull String s)
      Parses the string argument as a time zone.
      Parameters:
      s - string to be converted
      Returns:
      a ZoneId represented by the input string
      Throws:
      DateTimeUtils.DateTimeParseException - if the string cannot be converted
      See Also:
    • parseTimeZoneQuiet

      @ScriptApi @Nullable public static @Nullable ZoneId parseTimeZoneQuiet(@Nullable @Nullable String s)
      Parses the string argument as a time zone.
      Parameters:
      s - string to be converted
      Returns:
      a ZoneId represented by the input string, or null if the string can not be parsed
      See Also:
    • parseDurationNanos

      @ScriptApi public static long parseDurationNanos(@NotNull @NotNull String s)
      Parses the string argument as a time duration in nanoseconds.

      Time duration strings can be formatted as [-]PT[-]hh:mm:[ss.nnnnnnnnn] or as a duration string formatted as [-]PnDTnHnMn.nS.

      Parameters:
      s - string to be converted
      Returns:
      the number of nanoseconds represented by the string
      Throws:
      DateTimeUtils.DateTimeParseException - if the string cannot be parsed
      See Also:
    • parseDurationNanosQuiet

      @ScriptApi public static long parseDurationNanosQuiet(@Nullable @Nullable String s)
      Parses the string argument as a time duration in nanoseconds.

      Time duration strings can be formatted as [-]PT[-]hh:mm:[ss.nnnnnnnnn] or as a duration string formatted as [-]PnDTnHnMn.nS.

      Parameters:
      s - string to be converted
      Returns:
      the number of nanoseconds represented by the string, or QueryConstants.NULL_LONG if the string cannot be parsed
      See Also:
    • parsePeriod

      @ScriptApi @NotNull public static @NotNull Period parsePeriod(@NotNull @NotNull String s)
      Parses the string argument as a period, which is a unit of time in terms of calendar time (days, weeks, months, years, etc.).

      Period strings are formatted according to the ISO-8601 duration format as PnYnMnD and PnW, where the coefficients can be positive or negative. Zero coefficients can be omitted. Optionally, the string can begin with a negative sign.

      Examples:

         "P2Y"             -- Period.ofYears(2)
         "P3M"             -- Period.ofMonths(3)
         "P4W"             -- Period.ofWeeks(4)
         "P5D"             -- Period.ofDays(5)
         "P1Y2M3D"         -- Period.of(1, 2, 3)
         "P1Y2M3W4D"       -- Period.of(1, 2, 25)
         "P-1Y2M"          -- Period.of(-1, 2, 0)
         "-P1Y2M"          -- Period.of(-1, -2, 0)
       
      Parameters:
      s - period string
      Returns:
      the period
      Throws:
      DateTimeUtils.DateTimeParseException - if the string cannot be parsed
      See Also:
    • parsePeriodQuiet

      @ScriptApi @Nullable public static @Nullable Period parsePeriodQuiet(@Nullable @Nullable String s)
      Parses the string argument as a period, which is a unit of time in terms of calendar time (days, weeks, months, years, etc.).

      Period strings are formatted according to the ISO-8601 duration format as PnYnMnD and PnW, where the coefficients can be positive or negative. Zero coefficients can be omitted. Optionally, the string can begin with a negative sign.

      Examples:

         "P2Y"             -- Period.ofYears(2)
         "P3M"             -- Period.ofMonths(3)
         "P4W"             -- Period.ofWeeks(4)
         "P5D"             -- Period.ofDays(5)
         "P1Y2M3D"         -- Period.of(1, 2, 3)
         "P1Y2M3W4D"       -- Period.of(1, 2, 25)
         "P-1Y2M"          -- Period.of(-1, 2, 0)
         "-P1Y2M"          -- Period.of(-1, -2, 0)
       
      Parameters:
      s - period string
      Returns:
      the period, or null if the string can not be parsed
      See Also:
    • parseDuration

      @ScriptApi @NotNull public static @NotNull Duration parseDuration(@NotNull @NotNull String s)
      Parses the string argument as a duration, which is a unit of time in terms of clock time (24-hour days, hours, minutes, seconds, and nanoseconds).

      Duration strings are formatted according to the ISO-8601 duration format as [-]PnDTnHnMn.nS, where the coefficients can be positive or negative. Zero coefficients can be omitted. Optionally, the string can begin with a negative sign.

      Examples:

          "PT20.345S" -- parses as "20.345 seconds"
          "PT15M"     -- parses as "15 minutes" (where a minute is 60 seconds)
          "PT10H"     -- parses as "10 hours" (where an hour is 3600 seconds)
          "P2D"       -- parses as "2 days" (where a day is 24 hours or 86400 seconds)
          "P2DT3H4M"  -- parses as "2 days, 3 hours and 4 minutes"
          "PT-6H3M"    -- parses as "-6 hours and +3 minutes"
          "-PT6H3M"    -- parses as "-6 hours and -3 minutes"
          "-PT-6H+3M"  -- parses as "+6 hours and -3 minutes"
       
      Parameters:
      s - duration string
      Returns:
      the duration
      Throws:
      DateTimeUtils.DateTimeParseException - if the string cannot be parsed
      See Also:
    • parseDurationQuiet

      @ScriptApi @Nullable public static @Nullable Duration parseDurationQuiet(@Nullable @Nullable String s)
      Parses the string argument as a duration, which is a unit of time in terms of clock time (24-hour days, hours, minutes, seconds, and nanoseconds).

      Duration strings are formatted according to the ISO-8601 duration format as [-]PnDTnHnMn.nS, where the coefficients can be positive or negative. Zero coefficients can be omitted. Optionally, the string can begin with a negative sign.

      Examples:

          "PT20.345S" -- parses as "20.345 seconds"
          "PT15M"     -- parses as "15 minutes" (where a minute is 60 seconds)
          "PT10H"     -- parses as "10 hours" (where an hour is 3600 seconds)
          "P2D"       -- parses as "2 days" (where a day is 24 hours or 86400 seconds)
          "P2DT3H4M"  -- parses as "2 days, 3 hours and 4 minutes"
          "PT-6H3M"    -- parses as "-6 hours and +3 minutes"
          "-PT6H3M"    -- parses as "-6 hours and -3 minutes"
          "-PT-6H+3M"  -- parses as "+6 hours and -3 minutes"
       
      Parameters:
      s - duration string
      Returns:
      the duration, or null if the string can not be parsed
      See Also:
    • parseEpochNanos

      @ScriptApi public static long parseEpochNanos(@NotNull @NotNull String s)
      Parses the string argument as nanoseconds since the Epoch.

      Date time strings are formatted according to the ISO 8601 date time format yyyy-MM-ddThh:mm:ss[.SSSSSSSSS] TZ and others. Additionally, date time strings can be integer values that are nanoseconds, milliseconds, or seconds from the Epoch. Expected date ranges are used to infer the units.

      Parameters:
      s - date time string
      Returns:
      a long number of nanoseconds since the Epoch, matching the instant represented by the input string
      Throws:
      DateTimeUtils.DateTimeParseException - if the string cannot be parsed
      See Also:
    • parseEpochNanosQuiet

      @ScriptApi public static long parseEpochNanosQuiet(@Nullable @Nullable String s)
      Parses the string argument as a nanoseconds since the Epoch.

      Date time strings are formatted according to the ISO 8601 date time format yyyy-MM-ddThh:mm:ss[.SSSSSSSSS] TZ and others. Additionally, date time strings can be integer values that are nanoseconds, milliseconds, or seconds from the Epoch. Expected date ranges are used to infer the units.

      Parameters:
      s - date time string
      Returns:
      a long number of nanoseconds since the Epoch, matching the instant represented by the input string, or null if the string can not be parsed
      See Also:
    • parseInstant

      @ScriptApi @NotNull public static @NotNull Instant parseInstant(@NotNull @NotNull String s)
      Parses the string argument as an Instant.

      Date time strings are formatted according to the ISO 8601 date time format yyyy-MM-ddThh:mm:ss[.SSSSSSSSS] TZ and others. Additionally, date time strings can be integer values that are nanoseconds, milliseconds, or seconds from the Epoch. Expected date ranges are used to infer the units.

      Parameters:
      s - date time string
      Returns:
      an Instant represented by the input string
      Throws:
      DateTimeUtils.DateTimeParseException - if the string cannot be parsed
      See Also:
    • parseInstantQuiet

      @ScriptApi @Nullable public static @Nullable Instant parseInstantQuiet(@Nullable @Nullable String s)
      Parses the string argument as an Instant.

      Date time strings are formatted according to the ISO 8601 date time format yyyy-MM-ddThh:mm:ss[.SSSSSSSSS] TZ and others. Additionally, date time strings can be integer values that are nanoseconds, milliseconds, or seconds from the Epoch. Expected date ranges are used to infer the units.

      Parameters:
      s - date time string
      Returns:
      an Instant represented by the input string, or null if the string can not be parsed
      See Also:
    • parseZonedDateTime

      @ScriptApi @NotNull public static @NotNull ZonedDateTime parseZonedDateTime(@NotNull @NotNull String s)
      Parses the string argument as a ZonedDateTime.

      Date time strings are formatted according to the ISO 8601 date time format yyyy-MM-ddThh:mm:ss[.SSSSSSSSS] TZ and others.

      Parameters:
      s - date time string
      Returns:
      a ZonedDateTime represented by the input string
      Throws:
      DateTimeUtils.DateTimeParseException - if the string cannot be parsed
      See Also:
    • parseZonedDateTimeQuiet

      @ScriptApi @Nullable public static @Nullable ZonedDateTime parseZonedDateTimeQuiet(@Nullable @Nullable String s)
      Parses the string argument as a ZonedDateTime.

      Date time strings are formatted according to the ISO 8601 date time format yyyy-MM-ddThh:mm:ss[.SSSSSSSSS] TZ and others.

      Parameters:
      s - date time string
      Returns:
      a ZonedDateTime represented by the input string, or null if the string can not be parsed
      See Also:
    • parseTimePrecision

      @ScriptApi @NotNull public static @NotNull ChronoField parseTimePrecision(@NotNull @NotNull String s)
      Returns a ChronoField indicating the level of precision in a time, datetime, or period nanos string.
      Parameters:
      s - time string
      Returns:
      ChronoField for the finest units in the string (e.g. "10:00:00" would yield SecondOfMinute)
      Throws:
      RuntimeException - if the string cannot be parsed
    • parseTimePrecisionQuiet

      @ScriptApi @Nullable public static @Nullable ChronoField parseTimePrecisionQuiet(@Nullable @Nullable String s)
      Returns a ChronoField indicating the level of precision in a time or datetime string.
      Parameters:
      s - time string
      Returns:
      null if the time string cannot be parsed; otherwise, a ChronoField for the finest units in the string (e.g. "10:00:00" would yield SecondOfMinute)
      Throws:
      RuntimeException - if the string cannot be parsed
    • parseLocalDate

      @ScriptApi @NotNull public static @NotNull LocalDate parseLocalDate(@NotNull @NotNull String s)
      Parses the string argument as a local date, which is a date without a time or time zone.

      Date strings are formatted according to the ISO 8601 date time format as YYYY-MM-DD.

      Parameters:
      s - date string
      Returns:
      local date parsed according to the default date style
      Throws:
      DateTimeUtils.DateTimeParseException - if the string cannot be parsed
      See Also:
    • parseLocalDateQuiet

      @ScriptApi @Nullable public static @Nullable LocalDate parseLocalDateQuiet(@Nullable @Nullable String s)
      Parses the string argument as a local date, which is a date without a time or time zone.

      Date strings are formatted according to the ISO 8601 date time format as YYYY-MM-DD.

      Parameters:
      s - date string
      Returns:
      local date parsed according to the default date style, or null if the string can not be parsed
      See Also:
    • parseLocalTime

      @ScriptApi @NotNull public static @NotNull LocalTime parseLocalTime(@NotNull @NotNull String s)
      Parses the string argument as a local time, which is the time that would be read from a clock and does not have a date or timezone.

      Local time strings can be formatted as hh:mm:ss[.nnnnnnnnn].

      Parameters:
      s - string to be converted
      Returns:
      a LocalTime represented by the input string.
      Throws:
      DateTimeUtils.DateTimeParseException - if the string cannot be converted, otherwise a LocalTime from the parsed string
    • parseLocalTimeQuiet

      @ScriptApi @Nullable public static @Nullable LocalTime parseLocalTimeQuiet(@Nullable @Nullable String s)
      Parses the string argument as a local time, which is the time that would be read from a clock and does not have a date or timezone.

      Local time strings can be formatted as hh:mm:ss[.nnnnnnnnn].

      Parameters:
      s - string to be converted
      Returns:
      a LocalTime represented by the input string, or null if the string can not be parsed