Java Period class

by

In Java, the Period class is a part of the java.time package introduced in Java 8. It represents a period of time defined in terms of years, months, and days.

To create an instance of Period, you can use one of the factory methods provided by the class. For example:

Period threeDays = Period.ofDays(3); // represents a period of 3 days
Period twoMonths = Period.ofMonths(2); // represents a period of 2 months
Period oneYearTwoMonthsThreeDays = Period.of(1, 2, 3); // represents a period of 1 year, 2 months, and 3 days

You can also create a Period object by parsing a string using the Period.parse() method:

Period sixMonths = Period.parse("P6M"); // represents a period of 6 months

Once you have a Period object, you can perform arithmetic operations on it. For example, you can add or subtract a period from a date using the plus() and minus() methods:

LocalDate today = LocalDate.now();
LocalDate threeDaysFromNow = today.plus(Period.ofDays(3));
LocalDate twoMonthsAgo = today.minus(Period.ofMonths(2));

You can also compare two periods using the equals() method or the compareTo() method:

Period oneYear = Period.ofYears(1);
Period twoYears = Period.ofYears(2);
System.out.println(oneYear.equals(twoYears)); // prints "false"
System.out.println(oneYear.compareTo(twoYears)); // prints "-1"

The Period class also provides methods to get the number of years, months, and days in a period:

Period twoYearsThreeMonths = Period.of(2, 3, 0);
System.out.println(twoYearsThreeMonths.getYears()); // prints "2"
System.out.println(twoYearsThreeMonths.getMonths()); // prints "3"
System.out.println(twoYearsThreeMonths.getDays()); // prints "0"

Overall, the Period class is a useful tool for working with periods of time in Java.

Java Period class declaration:

The Period class in Java is declared as follows:

public final class Period
    implements ChronoPeriod, Serializable {
    
    // Constructors
    public static Period ofYears(int years);
    public static Period ofMonths(int months);
    public static Period ofWeeks(int weeks);
    public static Period ofDays(int days);
    public static Period of(int years, int months, int days);
    public static Period parse(CharSequence text);
    
    // Instance methods
    public int getYears();
    public int getMonths();
    public int getDays();
    public boolean isZero();
    public boolean isNegative();
    public Period plus(Period other);
    public Period plusYears(long yearsToAdd);
    public Period plusMonths(long monthsToAdd);
    public Period plusDays(long daysToAdd);
    public Period minus(Period other);
    public Period minusYears(long yearsToSubtract);
    public Period minusMonths(long monthsToSubtract);
    public Period minusDays(long daysToSubtract);
    public Period multipliedBy(int scalar);
    public Period negated();
    public Period normalized();
    public Period abs();
    public Chronology getChronology();
    public List<TemporalUnit> getUnits();
    public long get(TemporalUnit unit);
    public boolean isSupported(TemporalUnit unit);
    public Period withYears(int years);
    public Period withMonths(int months);
    public Period withDays(int days);
    public Temporal addTo(Temporal temporal);
    public Temporal subtractFrom(Temporal temporal);
    public String toString();
    public boolean equals(Object obj);
    public int hashCode();
}

The Period class is a final class, which means that it cannot be subclassed. It implements the ChronoPeriod interface and the Serializable interface.

The class provides several factory methods for creating instances of Period, including ofYears(), ofMonths(), ofWeeks(), ofDays(), and of(). These methods take different combinations of years, months, and days as input and return a Period object representing the corresponding period of time.

The class also provides many instance methods for performing arithmetic operations on Period objects. These methods include plus(), minus(), multipliedBy(), negated(), normalized(), abs(), withYears(), withMonths(), withDays(), and more.

In addition, the Period class provides methods for getting the years, months, and days in a Period object, as well as checking whether a Period object is zero or negative. It also provides methods for getting and setting the units of the period, and for adding or subtracting a Period object to or from a Temporal object. Finally, it provides methods for checking whether a TemporalUnit is supported by the Period class, and for converting a Period object to a string.

Methods of Java Period:

The Period class in Java provides several methods for working with periods of time. Here is a brief overview of some of the important methods:

  1. ofYears(int years), ofMonths(int months), ofWeeks(int weeks), ofDays(int days), and of(int years, int months, int days): These are factory methods for creating Period objects representing the specified period of time.
  2. parse(CharSequence text): This method creates a Period object by parsing a string representation of the period.
  3. getYears(), getMonths(), and getDays(): These methods return the number of years, months, and days in the Period object, respectively.
  4. isZero(): This method returns true if the Period object represents a zero-length period.
  5. isNegative(): This method returns true if the Period object represents a negative period.
  6. plus(Period other) and minus(Period other): These methods return a new Period object that is the sum or difference of the current Period object and another Period object, respectively.
  7. plusYears(long yearsToAdd), plusMonths(long monthsToAdd), and plusDays(long daysToAdd): These methods return a new Period object that is the sum of the current Period object and the specified number of years, months, or days.
  8. minusYears(long yearsToSubtract), minusMonths(long monthsToSubtract), and minusDays(long daysToSubtract): These methods return a new Period object that is the difference of the current Period object and the specified number of years, months, or days.
  9. multipliedBy(int scalar): This method returns a new Period object that is the current Period object multiplied by the specified scalar value.
  10. negated(): This method returns a new Period object that is the negation of the current Period object.
  11. normalized(): This method returns a new Period object that is equivalent to the current Period object but with the years and months normalized to be between -11 and 11.
  12. abs(): This method returns a new Period object that is the absolute value of the current Period object.
  13. withYears(int years), withMonths(int months), and withDays(int days): These methods return a new Period object that is identical to the current Period object except for the specified field.
  14. addTo(Temporal temporal) and subtractFrom(Temporal temporal): These methods add or subtract the Period object to or from a Temporal object.
  15. toString(): This method returns a string representation of the Period object.
  16. equals(Object obj) and hashCode(): These methods override the equals() and hashCode() methods inherited from the Object class. They are used to compare Period objects for equality.

Overall, the Period class provides a rich set of methods for working with periods of time in Java.

Java Period Example: addTo()

Sure, here’s an example of using the addTo(Temporal temporal) method of the Period class in Java:

import java.time.LocalDate;
import java.time.Period;

public class PeriodExample {
    public static void main(String[] args) {
        LocalDate date = LocalDate.of(2023, 5, 6);
        Period period = Period.of(1, 2, 3); // 1 year, 2 months, 3 days
        LocalDate newDate = period.addTo(date); // add the period to the date
        
        System.out.println("Original date: " + date); // output: Original date: 2023-05-06
        System.out.println("Period: " + period); // output: Period: P1Y2M3D
        System.out.println("New date: " + newDate); // output: New date: 2024-07-09
    }
}

n this example, we first create a LocalDate object representing May 6, 2023. We then create a Period object representing 1 year, 2 months, and 3 days. We use the addTo(Temporal temporal) method of the Period object to add the period to the date, resulting in a new LocalDate object representing July 9, 2024. Finally, we output the original date, the period, and the new date to the console.

Java Period Example: of()

Sure, here’s an example of using the of(int years, int months, int days) method of the Period class in Java:

import java.time.Period;

public class PeriodExample {
    public static void main(String[] args) {
        Period period1 = Period.of(1, 2, 3); // 1 year, 2 months, 3 days
        Period period2 = Period.of(0, 0, 7); // 7 days
        
        Period period3 = period1.plus(period2); // add the two periods together
        
        System.out.println("Period 1: " + period1); // output: Period 1: P1Y2M3D
        System.out.println("Period 2: " + period2); // output: Period 2: P7D
        System.out.println("Period 3: " + period3); // output: Period 3: P1Y2M10D
    }
}

In this example, we first create two Period objects: one representing 1 year, 2 months, and 3 days, and another representing 7 days. We then use the plus(Period other) method of the first Period object to add the second Period object to it, resulting in a new Period object representing 1 year, 2 months, and 10 days. Finally, we output all three Period objects to the console.

Java Period Example: minus()

Sure, here’s an example of using the minus(Period other) method of the Period class in Java:

import java.time.Period;

public class PeriodExample {
    public static void main(String[] args) {
        Period period1 = Period.of(1, 2, 3); // 1 year, 2 months, 3 days
        Period period2 = Period.of(0, 0, 7); // 7 days
        
        Period period3 = period1.minus(period2); // subtract the second period from the first
        
        System.out.println("Period 1: " + period1); // output: Period 1: P1Y2M3D
        System.out.println("Period 2: " + period2); // output: Period 2: P7D
        System.out.println("Period 3: " + period3); // output: Period 3: P1Y1M24D
    }
}

In this example, we first create two Period objects: one representing 1 year, 2 months, and 3 days, and another representing 7 days. We then use the minus(Period other) method of the first Period object to subtract the second Period object from it, resulting in a new Period object representing 1 year, 1 month, and 24 days. Finally, we output all three Period objects to the console.

Java Period Example: plus()

Sure, here’s an example of using the plus(Period other) method of the Period class in Java:

import java.time.Period;

public class PeriodExample {
    public static void main(String[] args) {
        Period period1 = Period.of(1, 2, 3); // 1 year, 2 months, 3 days
        Period period2 = Period.of(0, 0, 7); // 7 days
        
        Period period3 = period1.plus(period2); // add the second period to the first
        
        System.out.println("Period 1: " + period1); // output: Period 1: P1Y2M3D
        System.out.println("Period 2: " + period2); // output: Period 2: P7D
        System.out.println("Period 3: " + period3); // output: Period 3: P1Y2M10D
    }
}

In this example, we first create two Period objects: one representing 1 year, 2 months, and 3 days, and another representing 7 days. We then use the plus(Period other) method of the first Period object to add the second Period object to it, resulting in a new Period object representing 1 year, 2 months, and 10 days. Finally, we output all three Period objects to the console.