java.time.Period Class in Java

The Period Class in Java class obtains a quantity or amount of time in terms of years, months and days. The time obtained is a date-based amount of time in the ISO-8601 calendar system, such as ‘4 years, 5 months, and 6 days. The units which are supported for a period are YEARS, MONTHS, and days. All these three fields are always present but may be set to zero.

Syntax: Class declaration

public final class Period 
extends Object 
implements ChronoPeriod, Serializable

Below all the methods with the action performed by them are as follows in the tabular format are as follows:

Method	Description
addTo(Temporal temporal)	This method adds this period to the specified temporal object.
between(LocalDate startDateInclusive, LocalDate endDateExclusive)	This method obtains a Period consisting of the number of years, months, and days between two dates.
equals(Object obj)	This method checks if this period is equal to another period.
from(TemporalAmount amount)	This method obtains an instance of Period from a temporal amount.
get(TemporalUnit unit)	This method gets the value of the requested unit.
getChronology()	This method gets the chronology of this period, which is the ISO calendar system.
getDays()	This method gets the number of days of this period.
getMonths()	This method gets the number of months of this period.
getUnits()	This method gets the set of units supported by this period.
getYears()	This method gets the number of years of this period.
hashCode()	This method returns a hash code for this period.
isNegative()	This method checks if any of the three units of this period are negative.
isZero()	This method checks if all three units of this period are zero.
minus(TemporalAmount amountToSubtract)	This method returns a copy of this period with the specified period subtracted.
minusDays(long daysToSubtract)	This method returns a copy of this period with the specified days subtracted.
minusMonths(long monthsToSubtract)	This method returns a copy of this period with the specified months subtracted.
minusYears(long yearsToSubtract)	This method returns a copy of this period with the specified years subtracted.
multipliedBy(int scalar)	This method returns a new instance with each element in this period multiplied by the specified scalar.
negated()	This method returns a new instance with each amount in this period negated.
normalized()	This method returns a copy of this period with the years and months normalized.
of(int years, int months, int days)	This method obtains a Period representing a number of years, months, and days.
ofDays(int days)	This method obtains a Period representing a number of days.
ofMonths(int months)	This method obtains a Period representing a number of months.
ofWeeks(int weeks)	This method obtains a Period representing a number of weeks.
ofYears(int years)	This method obtains a Period representing a number of years.
parse(CharSequence text)	This method obtains a Period from a text string such as PnYnMnD.
plus(TemporalAmount amountToAdd)	This method returns a copy of this period with the specified period added.
plusDays(long daysToAdd)	This method returns a copy of this period with the specified days added.
plusMonths(long monthsToAdd)	This method returns a copy of this period with the specified months added.
plusYears(long yearsToAdd)	This method returns a copy of this period with the specified years added.
subtractFrom(Temporal temporal)	This method subtracts this period from the specified temporal object.
toString()	This method outputs this period as a String, such as P6Y3M1D.
toTotalMonths()	This method gets the total number of months in this period.
withDays(int days)	This method returns a copy of this period with the specified amount of days.
withMonths(int months)	This method returns a copy of this period with the specified amount of months.
withYears(int years)	This method returns a copy of this period with the specified amount of years.

Let us implement a few of the methods of this class.

Implementation:

Example 1

Java

// Java program to illustrate Period class
// demonstrate the methods of this class
// Methods - minus() and ofMonths()

// Importing Period class from
// java.time package
import java.time.Period;

// Main class
public class GFG {
    // Main driver method
    public static void main(String[] args)
    {
        // Obtaining period representing number of months
        // using of months() method by
        // creating object of period class
        Period p1 = Period.ofMonths(6);

        // minus() will return a copy of this period
        // with the specified period subtracted.
        Period p2 = p1.minus(Period.ofMonths(2));

        // Print and display on the console
        System.out.println(p2);
    }
}

Output

P4M

Let us take another example in order to discuss more methods namely as follows:

Method 1: ofDays() method of this class is used to obtain a period from the given number of Days as a parameter. 

Syntax:

public static Period ofDays(int numberOfDays)

Parameters: This method accepts a single parameter number of days which is the number of Days to be parsed into a Period object.

Returns: This function returns the period which is the Period object parsed with the given number of Days.

Method 2: addTo() method of this class adds this Period to the specific temporal object.

Syntax:

public Temporal addTo(Temporal temporal)

Parameters: The temporal object to adjust should not be null.

Return Type: An object of the same type with the adjustment made.

Exceptions: DateTime and Arithmetic exceptions are thrown by this method.

Example 2

Java

// Java program to illustrate Period class
// demonstrate the methods of this class
// Methods like ofDays() and addTo()

// Importing all classes from java.time package
import java.time.*;
import java.time.temporal.Temporal;

// Main class
public class GFG {

    // Main driver method
    public static void main(String[] args)
    {
        // Getting a period representing number of days
        // using ofDays() method
        Period p = Period.ofDays(24);

        // Adding this period to the
        // temporal object i.e. temp
        Temporal temp = p.addTo(LocalDate.now());

        // Print and display on the console
        System.out.println(temp);
    }
}

Output

2021-03-29