Package org.daiitech.naftah.utils.time

Class TemporalUtils

java.lang.Object
org.daiitech.naftah.utils.time.TemporalUtils
public final class TemporalUtils extends Object
Utility class for creating and manipulating Java Temporal instances from Naftah date and time components.

Provides methods to create:

Handles conversion between 12-hour and 24-hour formats, applies AM/PM logic, and supports both ISO and Hijrah (Islamic) chronologies.

Author:
Chakib Daii

  • Constructor Details

    • TemporalUtils

      private TemporalUtils()
      Private constructor to prevent instantiation. Always throws a NaftahBugError when called.

  • Method Details

    • createTime

      public static Temporal createTime(NaftahTime.Time time, NaftahTime.ZoneOrOffset zoneOrOffset)
      Creates a Temporal representing the given Naftah time, optionally including a time zone or offset.
      Parameters:
      time - the Naftah time component
      zoneOrOffset - the optional time zone or offset
      Returns:
      a Temporal representing the time, either LocalTime, OffsetTime, or ZonedDateTime depending on the zone/offset

    • createTimeOfNanoOfDay

      public static NTuple createTimeOfNanoOfDay(long nanoOfDay, NaftahTime.ZoneOrOffset zoneOrOffset)
      Creates a LocalTime and a corresponding Temporal from the total number of nanoseconds since midnight.

      The returned tuple contains:

      Parameters:
      nanoOfDay - the nano-of-day (0–86,399,999,999,999)
      zoneOrOffset - the optional time zone or offset, may be null
      Returns:
      an NTuple containing the LocalTime and corresponding Temporal

    • createTimeOfSecondOfDay

      public static NTuple createTimeOfSecondOfDay(long secondOfDay, NaftahTime.ZoneOrOffset zoneOrOffset)
      Creates a LocalTime and a corresponding Temporal from the total number of seconds since midnight.

      The returned tuple contains:

      Parameters:
      secondOfDay - the second-of-day (0–86,399)
      zoneOrOffset - the optional time zone or offset, may be null
      Returns:
      an NTuple containing the LocalTime and corresponding Temporal

    • createTime

      public static Temporal createTime(int hour24, Integer minute, Integer second, Integer nano, NaftahTime.ZoneOrOffset zoneOrOffset)
      Creates a Temporal representing a time using explicit components and an optional time zone or offset.

      Any null minute, second, or nanosecond value will default to 0.

      Parameters:
      hour24 - the hour in 24-hour format (0–23)
      minute - the minute of the hour, may be null
      second - the second of the minute, may be null
      nano - the nanosecond part, may be null
      zoneOrOffset - the optional time zone or offset, may be null
      Returns:
      a Temporal representing the specified time, never null

    • createTime

      public static Temporal createTime(int hour24, Integer minute, Integer second, Integer nano, ZoneId zoneId)
      Creates a Temporal representing a time with explicit components.
      Parameters:
      hour24 - the hour in 24-hour format
      minute - the minute of the hour, may be null
      second - the second of the minute, may be null
      nano - the nanosecond part, may be null
      zoneId - the optional ZoneId, may be null
      Returns:
      a Temporal representing the specified time

    • currentTime

      public static Temporal currentTime(NaftahTime.ZoneOrOffset zoneOrOffset)
      Returns the current Temporal representing the time in the specified zone or offset.
      Parameters:
      zoneOrOffset - the optional NaftahTime.ZoneOrOffset, may be null
      Returns:
      a Temporal representing the current time in the given zone or offset

    • currentTime

      public static Temporal currentTime(ZoneId zoneId)
      Returns the current Temporal representing the time in the specified ZoneId.
      Parameters:
      zoneId - the optional ZoneId, may be null
      Returns:
      a Temporal representing the current time in the given zone

    • createTime

      public static Temporal createTime(LocalTime time, ZoneId zoneId)
      Creates a Temporal from a LocalTime and an optional ZoneId.

      If a ZoneId is provided:

      If no ZoneId is provided, returns the LocalTime as-is.

      Parameters:
      time - the LocalTime to wrap
      zoneId - the optional ZoneId, may be null
      Returns:
      a Temporal representing the given time with the zone applied if present

    • createChronoLocalDate

      private static ChronoLocalDate createChronoLocalDate(int day, int monthValue, int year, Chronology chronology)
      Creates a ChronoLocalDate using the specified day, month, year, and chronology.

      This method preserves the original chronology, so it can represent dates in non-ISO calendars such as HijrahChronology.

      Parameters:
      day - the day of the month (1–31, depending on month and chronology)
      monthValue - the month number (1–12)
      year - the year in the specified chronology
      chronology - the Chronology to use (e.g., IsoChronology or * HijrahChronology)
      Returns:
      a ChronoLocalDate representing the specified date in the given chronology

    • createDate

      public static LocalDate createDate(int day, int monthValue, int year, Chronology chronology)
      Creates a LocalDate (ISO calendar) from the specified day, month, year, and chronology.

      If a non-ISO chronology is provided (e.g., HijrahChronology), the date is converted to the ISO calendar system. This is useful for storing or processing dates in a standardized ISO format while preserving the original calendar's meaning.

      Parameters:
      day - the day of the month (1–31)
      monthValue - the month number (1–12)
      year - the year in the specified chronology
      chronology - the Chronology to use (e.g., ISO or Hijrah)
      Returns:
      a LocalDate in the ISO calendar representing the same date as the specified chronology

    • currentDate

      public static Temporal currentDate(NaftahDate.Calendar calendar, NaftahTime.ZoneOrOffset zoneOrOffset)
      Returns the current Temporal for the specified NaftahDate.Calendar and optional NaftahTime.ZoneOrOffset.
      Parameters:
      calendar - the Naftah calendar
      zoneOrOffset - the optional zone or offset, may be null
      Returns:
      a Temporal representing the current date in the given calendar and zone

    • currentDate

      public static ChronoLocalDate currentDate(Chronology chronology, ZoneId zoneId)
      Returns the current ChronoLocalDate for the specified Chronology and optional ZoneId.
      Parameters:
      chronology - the chronology to use (e.g., ISO or Hijrah)
      zoneId - the optional ZoneId, may be null
      Returns:
      a ChronoLocalDate representing the current date in the given chronology and zone

    • createDateTime

      public static Temporal createDateTime(NaftahDate.Date date, NaftahDate.Calendar calendar, NaftahTime.Time time, NaftahTime.ZoneOrOffset zoneOrOffset)
      Creates a Temporal representing the given Naftah date and time, optionally including a time zone or offset.
      Parameters:
      date - the Naftah date component
      calendar - the Naftah calendar component
      time - the Naftah time component
      zoneOrOffset - the optional time zone or offset
      Returns:
      a Temporal representing the date and time

    • createDateTime

      public static Temporal createDateTime(int day, int monthValue, int year, Chronology chronology, int hour24, Integer minute, Integer second, Integer nano, ZoneId zoneId)
      Creates a Temporal representing a date and time with optional time zone or offset.

      This method constructs the appropriate temporal object based on the inputs:

      Supports both ISO and non-ISO chronologies (e.g., Hijrah) and applies the correct conversions.

      Parameters:
      day - the day of the month
      monthValue - the month (1–12)
      year - the year
      chronology - the chronology to use (ISO, Hijrah, etc.)
      hour24 - the hour in 24-hour format
      minute - the minute of the hour, may be null
      second - the second of the minute, may be null
      nano - the nanosecond fraction, may be null
      zoneId - the optional ZoneId or ZoneOffset, may be null
      Returns:
      a Temporal representing the date and time with optional zone/offset

    • isPM

      public static boolean isPM(String ampm)
      Returns true if the given AM/PM marker represents PM.
      Parameters:
      ampm - the AM/PM marker string
      Returns:
      true if PM, false if AM

    • createOffsetTime

      public static OffsetTime createOffsetTime(LocalTime time, ZoneId zoneId)
      Creates an OffsetTime from a LocalTime and ZoneId.

      The actual offset is determined for the given zone at a fixed epoch date.

      Parameters:
      time - the local time
      zoneId - the zone to apply
      Returns:
      an OffsetTime representing the time at the given zone offset

    • createLocalDateTime

      public static LocalDateTime createLocalDateTime(Chronology chronology, Supplier<ChronoLocalDateTime<?>> chronoLocalDateTimeSupplier, Supplier<LocalDateTime> localDateTimeSupplier)
      Creates a LocalDateTime from a chronology and suppliers for ISO and non-ISO dates.

      For Hijrah chronology, converts to ISO LocalDateTime; otherwise uses ISO directly.

      Parameters:
      chronology - the chronology of the date
      chronoLocalDateTimeSupplier - supplier for ChronoLocalDateTime
      localDateTimeSupplier - supplier for ISO LocalDateTime
      Returns:
      the resulting LocalDateTime

    • createOffsetDateTime

      public static OffsetDateTime createOffsetDateTime(Chronology chronology, Supplier<ChronoLocalDateTime<?>> chronoLocalDateTimeSupplier, Supplier<LocalDateTime> localDateTimeSupplier, ZoneOffset offset)
      Creates an OffsetDateTime from a chronology, suppliers, and a ZoneOffset.

      For Hijrah chronology, converts to ISO and applies the offset; otherwise uses ISO directly.

      Parameters:
      chronology - the chronology of the date
      chronoLocalDateTimeSupplier - supplier for ChronoLocalDateTime
      localDateTimeSupplier - supplier for ISO LocalDateTime
      offset - the zone offset to apply
      Returns:
      the resulting OffsetDateTime

    • createZonedDateTime

      public static ZonedDateTime createZonedDateTime(Chronology chronology, Supplier<ChronoLocalDateTime<?>> chronoLocalDateTimeSupplier, Supplier<LocalDateTime> localDateTimeSupplier, ZoneId zoneId)
      Creates a ZonedDateTime from a chronology, suppliers, and a ZoneId.

      For Hijrah chronology, converts to ISO and applies the zone; otherwise uses ISO directly.

      Parameters:
      chronology - the chronology of the date
      chronoLocalDateTimeSupplier - supplier for ChronoLocalDateTime
      localDateTimeSupplier - supplier for ISO LocalDateTime
      zoneId - the time zone to apply
      Returns:
      the resulting ZonedDateTime

    • getHour24

      public static int getHour24(Integer hour, Boolean isPM)
      Converts an hour and AM/PM indicator to 24-hour format.

      If the hour is in 12-hour format, AM/PM is applied to produce a 24-hour value.

      Parameters:
      hour - the hour (1–12 or 0–23)
      isPM - true if PM, false if AM, null if 24-hour format
      Returns:
      the hour in 24-hour format

    • between

      public static NTuple between(Temporal start, Temporal end)
      Computes the temporal difference between two Temporal instances.

      The result is returned as an NTuple containing:

      • a Duration if the difference is less than 24 hours
      • a Period if the difference is date-based only
      • a Period and a Duration if the difference spans both date and time components
      Parameters:
      start - the start temporal point
      end - the end temporal point
      Returns:
      an NTuple containing the computed temporal amount(s)
      Throws:
      IllegalArgumentException - if the temporal type is not supported

    • toLocalDateTime

      private static LocalDateTime toLocalDateTime(Temporal t)
      Converts a Temporal instance to a LocalDateTime.

      Supported types: LocalDateTime, LocalDate, LocalTime, ZonedDateTime, OffsetDateTime, and Instant.

      Conversion rules:

      Parameters:
      t - the temporal value to convert
      Returns:
      a LocalDateTime representation of the temporal value
      Throws:
      IllegalArgumentException - if the temporal type is not supported

    • toInstant

      public static Instant toInstant(Temporal t)
      Converts a Temporal instance to an Instant.

      Supported types: Instant, ZonedDateTime, OffsetDateTime, LocalDateTime, LocalDate, and LocalTime.

      Conversion rules:

      Parameters:
      t - the temporal value to convert
      Returns:
      an Instant representing the temporal value
      Throws:
      IllegalArgumentException - if the temporal type is not supported

    • compare

      public static int compare(Period p1, Period p2)
      Compares two Period instances by years, then months, then days.

      Comparison is performed lexicographically: years → months → days.

      Parameters:
      p1 - the first period to compare
      p2 - the second period to compare
      Returns:
      a negative integer, zero, or a positive integer as p1 is less than, equal to, or greater than p2

    • parseMillisFraction

      public static int parseMillisFraction(String fraction)
      Parses the fractional part after seconds as milliseconds.

      The fraction must contain at most 3 digits:

      • .5 -> 500 ms
      • .25 -> 250 ms
      • .125 -> 125 ms
      Parameters:
      fraction - the fractional part without the dot
      Returns:
      milliseconds value (0–999)
      Throws:
      IllegalArgumentException - if the fraction exceeds 3 digits

    • parseFractionToNanos

      public static int parseFractionToNanos(String fraction)
      Parses the fractional part after seconds into nanoseconds.

      Supported formats:

      • 1–3 digits → milliseconds
      • 4–9 digits → nanoseconds
      Parameters:
      fraction - the fractional part without the dot
      Returns:
      nanoseconds value (0–999,999,999)
      Throws:
      IllegalArgumentException - if the fraction exceeds 9 digits

    • isHijrah

      private static boolean isHijrah(Chronology chronology)
      Determines whether the given Chronology represents the Hijrah (Islamic) calendar.

      This method compares the provided chronology against the system-supported Hijrah chronology used by the library.

      Parameters:
      chronology - the chronology to test, may be null
      Returns:
      true if the chronology is the Hijrah calendar, false otherwise