Package org.daiitech.naftah.builtin.time

Record Class NaftahPeriodWithDuration

java.lang.Object
java.lang.Record
org.daiitech.naftah.builtin.time.NaftahPeriodWithDuration
Record Components:
naftahPeriod - the period part in Arabic
naftahDuration - the duration part in Arabic
All Implemented Interfaces:
NaftahTemporal, NaftahTemporalAmount
public record NaftahPeriodWithDuration(NaftahPeriod naftahPeriod, NaftahDuration naftahDuration) extends Record implements NaftahTemporalAmount
Represents a combined period and duration expressed in Arabic text.

This class wraps an NaftahPeriod and an NaftahDuration, allowing you to work with both periods (years, months, days) and durations (hours, minutes, seconds) together in Arabic formatting.

Author:
Chakib Daii

  • Field Details

  • Constructor Details

    • NaftahPeriodWithDuration

      public NaftahPeriodWithDuration(NaftahPeriod naftahPeriod, NaftahDuration naftahDuration)
      Creates an instance of a NaftahPeriodWithDuration record class.
      Parameters:
      naftahPeriod - the value for the naftahPeriod record component
      naftahDuration - the value for the naftahDuration record component

  • Method Details

    • of

      public static NaftahPeriodWithDuration of(NaftahPeriod naftahPeriod, NaftahDuration naftahDuration)
      Creates a new ArabicPeriodWithDuration instance.
      Parameters:
      naftahPeriod - the period part in Arabic
      naftahDuration - the duration part in Arabic
      Returns:
      a new ArabicPeriodWithDuration instance

    • ofZero

      public static NaftahPeriodWithDuration ofZero()
      Returns an NaftahPeriodWithDuration representing a zero period and zero duration.

      The returned object has all components of both the period (years, months, days) and the duration (hours, minutes, seconds, milliseconds, nanoseconds) set to zero.

      Returns:
      an NaftahPeriodWithDuration with zero period and zero duration

    • ofYears

      public static NaftahPeriodWithDuration ofYears(int years)
      Obtains a ArabicPeriodWithDuration representing a number of years.

      The resulting period will have the specified years. The months and days units will be zero.

      Parameters:
      years - the number of years, positive or negative
      Returns:
      the period of years, not null

    • ofMonths

      public static NaftahPeriodWithDuration ofMonths(int months)
      Obtains a ArabicPeriodWithDuration representing a number of months.

      The resulting period will have the specified months. The years and days units will be zero.

      Parameters:
      months - the number of months, positive or negative
      Returns:
      the period of months, not null

    • ofWeeks

      public static NaftahPeriodWithDuration ofWeeks(int weeks)
      Obtains a ArabicPeriodWithDuration representing a number of weeks.

      The resulting period will be day-based, with the amount of days equal to the number of weeks multiplied by 7. The years and months units will be zero.

      Parameters:
      weeks - the number of weeks, positive or negative
      Returns:
      the period, with the input weeks converted to days, not null

    • ofDays

      public static NaftahPeriodWithDuration ofDays(int days)
      Obtains a ArabicPeriodWithDuration representing a number of days.

      The resulting period will have the specified days. The years and months units will be zero.

      Parameters:
      days - the number of days, positive or negative
      Returns:
      the period of days, not null

    • ofHours

      public static NaftahPeriodWithDuration ofHours(long hours)
      Obtains a ArabicPeriodWithDuration representing a number of standard hours.

      The seconds are calculated based on the standard definition of an hour, where each hour is 3600 seconds. The nanosecond in second field is set to zero.

      Parameters:
      hours - the number of hours, positive or negative
      Returns:
      a ArabicPeriodWithDuration, not null
      Throws:
      ArithmeticException - if the input hours exceeds the capacity of Duration

    • ofMinutes

      public static NaftahPeriodWithDuration ofMinutes(long minutes)
      Obtains a ArabicPeriodWithDuration representing a number of standard minutes.

      The seconds are calculated based on the standard definition of a minute, where each minute is 60 seconds. The nanosecond in second field is set to zero.

      Parameters:
      minutes - the number of minutes, positive or negative
      Returns:
      a ArabicPeriodWithDuration, not null
      Throws:
      ArithmeticException - if the input minutes exceeds the capacity of Duration

    • ofSeconds

      public static NaftahPeriodWithDuration ofSeconds(long seconds)
      Obtains a ArabicPeriodWithDuration representing a number of seconds.

      The nanosecond in second field is set to zero.

      Parameters:
      seconds - the number of seconds, positive or negative
      Returns:
      a ArabicPeriodWithDuration, not null

    • ofSeconds

      public static NaftahPeriodWithDuration ofSeconds(long seconds, long nanoAdjustment)
      Obtains a ArabicPeriodWithDuration representing a number of seconds and an adjustment in nanoseconds.

      This method allows an arbitrary number of nanoseconds to be passed in. The factory will alter the values of the second and nanosecond in order to ensure that the stored nanosecond is in the range 0 to 999,999,999. For example, the following will result in exactly the same duration: 

       Duration.ofSeconds(3, 1);
 Duration.ofSeconds(4, -999_999_999);
 Duration.ofSeconds(2, 1000_000_001);
      Parameters:
      seconds - the number of seconds, positive or negative
      nanoAdjustment - the nanosecond adjustment to the number of seconds, positive or negative
      Returns:
      a ArabicPeriodWithDuration, not null
      Throws:
      ArithmeticException - if the adjustment causes the seconds to exceed the capacity of Duration

    • ofMillis

      public static NaftahPeriodWithDuration ofMillis(long millis)
      Obtains a ArabicPeriodWithDuration representing a number of milliseconds.

      The seconds and nanoseconds are extracted from the specified milliseconds.

      Parameters:
      millis - the number of milliseconds, positive or negative
      Returns:
      a ArabicPeriodWithDuration, not null

    • ofNanos

      public static NaftahPeriodWithDuration ofNanos(long nanos)
      Obtains a ArabicPeriodWithDuration representing a number of nanoseconds.

      The seconds and nanoseconds are extracted from the specified nanoseconds.

      Parameters:
      nanos - the number of nanoseconds, positive or negative
      Returns:
      a ArabicPeriodWithDuration, not null

    • adjustDurationIntoPeriod

      private static NaftahPeriodWithDuration adjustDurationIntoPeriod(NaftahPeriod period, NaftahDuration duration)
      Adjusts durations of 24 hours or more by converting full days into the period.
      Parameters:
      period - the original ArabicPeriod
      duration - the original ArabicDuration
      Returns:
      a new ArabicPeriodWithDuration with normalized duration and adjusted period

    • temporalAmount

      public TemporalAmount temporalAmount()
      Returns the combined temporal amount of the period and duration.

      The period and duration are added together as a single TemporalAmount.

      Specified by:
      temporalAmount in interface NaftahTemporalAmount
      Returns:
      the total temporal amount

    • getYears

      public int getYears()
      Returns the number of years in this period.
      Returns:
      the years component of the period

    • getMonths

      public int getMonths()
      Returns the number of months in this period.
      Returns:
      the months component of the period

    • getDays

      public int getDays()
      Returns the number of days in this period.
      Returns:
      the days component of the period

    • getHours

      public long getHours()
      Returns the total number of hours in this duration.
      Returns:
      the total hours

    • getMinutes

      public long getMinutes()
      Returns the minute-of-hour component of this duration.

      This is calculated as the total minutes modulo 60, representing the remaining minutes after full hours are accounted for.

      Returns:
      the minutes within the current hour (0-59)

    • getSeconds

      public long getSeconds()
      Returns the second-of-minute component of this duration.

      This is calculated as the total seconds modulo 60, representing the remaining seconds after full minutes are accounted for.

      Returns:
      the seconds within the current minute (0-59)

    • getMillis

      public long getMillis()
      Returns the millisecond-of-second component of this duration.

      This is calculated as the total milliseconds modulo 1000, representing the remaining milliseconds after full seconds are accounted for.

      Returns:
      the milliseconds within the current second (0-999)

    • getNano

      public int getNano()
      Returns the nanosecond-of-second component of this duration.
      Returns:
      the nanoseconds within the current second (0-999,999,999)

    • plus

      public NaftahPeriodWithDuration plus(NaftahTemporalAmount other)
      Adds the given Arabic temporal amount to this instance.

      Supported combinations:

      Specified by:
      plus in interface NaftahTemporalAmount
      Parameters:
      other - the temporal amount to add
      Returns:
      a new normalized ArabicPeriodWithDuration

    • plusYears

      public NaftahPeriodWithDuration plusYears(long yearsToAdd)
      Returns a copy of this period with the specified years added.

      This adds the amount to the years unit in a copy of this period. The months and days units are unaffected. For example, "1 year, 6 months and 3 days" plus 2 years returns "3 years, 6 months and 3 days".

      This instance is immutable and unaffected by this method call.

      Parameters:
      yearsToAdd - the years to add, positive or negative
      Returns:
      a ArabicPeriodWithDuration based on this period with the specified years added, not null
      Throws:
      ArithmeticException - if numeric overflow occurs

    • plusMonths

      public NaftahPeriodWithDuration plusMonths(long monthsToAdd)
      Returns a copy of this period with the specified months added.

      This adds the amount to the months unit in a copy of this period. The years and days units are unaffected. For example, "1 year, 6 months and 3 days" plus 2 months returns "1 year, 8 months and 3 days".

      This instance is immutable and unaffected by this method call.

      Parameters:
      monthsToAdd - the months to add, positive or negative
      Returns:
      a ArabicPeriodWithDuration based on this period with the specified months added, not null
      Throws:
      ArithmeticException - if numeric overflow occurs

    • plusDays

      public NaftahPeriodWithDuration plusDays(long daysToAdd)
      Returns a copy of this period with the specified days added.

      This adds the amount to the days unit in a copy of this period. The years and months units are unaffected. For example, "1 year, 6 months and 3 days" plus 2 days returns "1 year, 6 months and 5 days".

      This instance is immutable and unaffected by this method call.

      Parameters:
      daysToAdd - the days to add, positive or negative
      Returns:
      a ArabicPeriodWithDuration based on this period with the specified days added, not null
      Throws:
      ArithmeticException - if numeric overflow occurs

    • plusHours

      public NaftahPeriodWithDuration plusHours(long hoursToAdd)
      Returns a copy of this duration with the specified duration in hours added.

      This instance is immutable and unaffected by this method call.

      Parameters:
      hoursToAdd - the hours to add, positive or negative
      Returns:
      a ArabicPeriodWithDuration based on this duration with the specified hours added, not null
      Throws:
      ArithmeticException - if numeric overflow occurs

    • plusMinutes

      public NaftahPeriodWithDuration plusMinutes(long minutesToAdd)
      Returns a copy of this duration with the specified duration in minutes added.

      This instance is immutable and unaffected by this method call.

      Parameters:
      minutesToAdd - the minutes to add, positive or negative
      Returns:
      a ArabicPeriodWithDuration based on this duration with the specified minutes added, not null
      Throws:
      ArithmeticException - if numeric overflow occurs

    • plusSeconds

      public NaftahPeriodWithDuration plusSeconds(long secondsToAdd)
      Returns a copy of this duration with the specified duration in seconds added.

      This instance is immutable and unaffected by this method call.

      Parameters:
      secondsToAdd - the seconds to add, positive or negative
      Returns:
      a ArabicPeriodWithDuration based on this duration with the specified seconds added, not null
      Throws:
      ArithmeticException - if numeric overflow occurs

    • plusMillis

      public NaftahPeriodWithDuration plusMillis(long millisToAdd)
      Returns a copy of this duration with the specified duration in milliseconds added.

      This instance is immutable and unaffected by this method call.

      Parameters:
      millisToAdd - the milliseconds to add, positive or negative
      Returns:
      a ArabicPeriodWithDuration based on this duration with the specified milliseconds added, not * null
      Throws:
      ArithmeticException - if numeric overflow occurs

    • plusNanos

      public NaftahPeriodWithDuration plusNanos(long nanosToAdd)
      Returns a copy of this duration with the specified duration in nanoseconds added.

      This instance is immutable and unaffected by this method call.

      Parameters:
      nanosToAdd - the nanoseconds to add, positive or negative
      Returns:
      a ArabicPeriodWithDuration based on this duration with the specified nanoseconds added, not null
      Throws:
      ArithmeticException - if numeric overflow occurs

    • minus

      public NaftahPeriodWithDuration minus(NaftahTemporalAmount other)
      Subtracts the given Arabic temporal amount from this instance.

      Supported combinations mirror those of plus(NaftahTemporalAmount).

      Specified by:
      minus in interface NaftahTemporalAmount
      Parameters:
      other - the temporal amount to subtract
      Returns:
      a new normalized ArabicPeriodWithDuration

    • minusYears

      public NaftahPeriodWithDuration minusYears(long yearsToSubtract)
      Returns a copy of this period with the specified years subtracted.

      This subtracts the amount from the years unit in a copy of this period. The months and days units are unaffected. For example, "1 year, 6 months and 3 days" minus 2 years returns "-1 years, 6 months and 3 days".

      This instance is immutable and unaffected by this method call.

      Parameters:
      yearsToSubtract - the years to subtract, positive or negative
      Returns:
      a ArabicPeriodWithDuration based on this period with the specified years subtracted, not null
      Throws:
      ArithmeticException - if numeric overflow occurs

    • minusMonths

      public NaftahPeriodWithDuration minusMonths(long monthsToSubtract)
      Returns a copy of this period with the specified months subtracted.

      This subtracts the amount from the months unit in a copy of this period. The years and days units are unaffected. For example, "1 year, 6 months and 3 days" minus 2 months returns "1 year, 4 months and 3 days".

      This instance is immutable and unaffected by this method call.

      Parameters:
      monthsToSubtract - the years to subtract, positive or negative
      Returns:
      a ArabicPeriodWithDuration based on this period with the specified months subtracted, not null
      Throws:
      ArithmeticException - if numeric overflow occurs

    • minusDays

      public NaftahPeriodWithDuration minusDays(long daysToSubtract)
      Returns a copy of this period with the specified days subtracted.

      This subtracts the amount from the days unit in a copy of this period. The years and months units are unaffected. For example, "1 year, 6 months and 3 days" minus 2 days returns "1 year, 6 months and 1 day".

      This instance is immutable and unaffected by this method call.

      Parameters:
      daysToSubtract - the months to subtract, positive or negative
      Returns:
      a ArabicPeriodWithDuration based on this period with the specified days subtracted, not null
      Throws:
      ArithmeticException - if numeric overflow occurs

    • minusHours

      public NaftahPeriodWithDuration minusHours(long hoursToSubtract)
      Returns a copy of this duration with the specified duration in hours subtracted.

      The number of hours is multiplied by 3600 to obtain the number of seconds to subtract.

      This instance is immutable and unaffected by this method call.

      Parameters:
      hoursToSubtract - the hours to subtract, positive or negative
      Returns:
      a ArabicPeriodWithDuration based on this duration with the specified hours subtracted, not null
      Throws:
      ArithmeticException - if numeric overflow occurs

    • minusMinutes

      public NaftahPeriodWithDuration minusMinutes(long minutesToSubtract)
      Returns a copy of this duration with the specified duration in minutes subtracted.

      The number of hours is multiplied by 60 to obtain the number of seconds to subtract.

      This instance is immutable and unaffected by this method call.

      Parameters:
      minutesToSubtract - the minutes to subtract, positive or negative
      Returns:
      a ArabicPeriodWithDuration based on this duration with the specified minutes subtracted, not * null
      Throws:
      ArithmeticException - if numeric overflow occurs

    • minusSeconds

      public NaftahPeriodWithDuration minusSeconds(long secondsToSubtract)
      Returns a copy of this duration with the specified duration in seconds subtracted.

      This instance is immutable and unaffected by this method call.

      Parameters:
      secondsToSubtract - the seconds to subtract, positive or negative
      Returns:
      a ArabicPeriodWithDuration based on this duration with the specified seconds subtracted, not * null
      Throws:
      ArithmeticException - if numeric overflow occurs

    • minusMillis

      public NaftahPeriodWithDuration minusMillis(long millisToSubtract)
      Returns a copy of this duration with the specified duration in milliseconds subtracted.

      This instance is immutable and unaffected by this method call.

      Parameters:
      millisToSubtract - the milliseconds to subtract, positive or negative
      Returns:
      a ArabicPeriodWithDuration based on this duration with the specified milliseconds subtracted, * not null
      Throws:
      ArithmeticException - if numeric overflow occurs

    • minusNanos

      public NaftahPeriodWithDuration minusNanos(long nanosToSubtract)
      Returns a copy of this duration with the specified duration in nanoseconds subtracted.

      This instance is immutable and unaffected by this method call.

      Parameters:
      nanosToSubtract - the nanoseconds to subtract, positive or negative
      Returns:
      a ArabicPeriodWithDuration based on this duration with the specified nanoseconds subtracted, * not null
      Throws:
      ArithmeticException - if numeric overflow occurs

    • isEquals

      public boolean isEquals(NaftahTemporalAmount other)
      Determines whether this temporal amount is equal to the given one.

      Equality requires both the period and duration components to be equal.

      Specified by:
      isEquals in interface NaftahTemporalAmount
      Parameters:
      other - the temporal amount to compare with
      Returns:
      true if both components are equal

    • notEquals

      public boolean notEquals(NaftahTemporalAmount other)
      Determines whether this temporal amount is not equal to the given one.
      Specified by:
      notEquals in interface NaftahTemporalAmount
      Parameters:
      other - the temporal amount to compare with
      Returns:
      true if the amounts are not equal

    • greaterThan

      public boolean greaterThan(NaftahTemporalAmount other)
      Determines whether this temporal amount is greater than the given one.

      Comparison is performed component-wise: both the period and duration must be greater.

      Specified by:
      greaterThan in interface NaftahTemporalAmount
      Parameters:
      other - the temporal amount to compare with
      Returns:
      true if both components are greater

    • greaterThanEquals

      public boolean greaterThanEquals(NaftahTemporalAmount other)
      Determines whether this temporal amount is greater than or equal to the given one.
      Specified by:
      greaterThanEquals in interface NaftahTemporalAmount
      Parameters:
      other - the temporal amount to compare with
      Returns:
      true if both components are greater than or equal

    • lessThan

      public boolean lessThan(NaftahTemporalAmount other)
      Determines whether this temporal amount is less than the given one.
      Specified by:
      lessThan in interface NaftahTemporalAmount
      Parameters:
      other - the temporal amount to compare with
      Returns:
      true if both components are less

    • lessThanEquals

      public boolean lessThanEquals(NaftahTemporalAmount other)
      Determines whether this temporal amount is less than or equal to the given one.
      Specified by:
      lessThanEquals in interface NaftahTemporalAmount
      Parameters:
      other - the temporal amount to compare with
      Returns:
      true if both components are less than or equal

    • toString

      public String toString()
      Returns the Arabic textual representation of the combined period and duration.

      The string consists of the Arabic period followed by the Arabic duration, joined with the Arabic conjunction " و ".

      Specified by:
      toString in class Record
      Returns:
      a string describing the combined period and duration in Arabic

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. All components in this record class are compared with Objects::equals(Object,Object).
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • naftahPeriod

      public NaftahPeriod naftahPeriod()
      Returns the value of the naftahPeriod record component.
      Returns:
      the value of the naftahPeriod record component

    • naftahDuration

      public NaftahDuration naftahDuration()
      Returns the value of the naftahDuration record component.
      Returns:
      the value of the naftahDuration record component