YearMonth (Java Platform SE 8 )

java.lang.Object
- java.time.YearMonth

All Implemented Interfaces:

Serializable, Comparable<YearMonth>, Temporal, TemporalAccessor, TemporalAdjuster
```
public final class YearMonth
extends Object
implements Temporal, TemporalAdjuster, Comparable<YearMonth>, Serializable
```
A year-month in the ISO-8601 calendar system, such as 2007-12.
YearMonth is an immutable date-time object that represents the combination of a year and month. Any field that can be derived from a year and month, such as quarter-of-year, can be obtained.
This class does not store or represent a day, time or time-zone. For example, the value "October 2007" can be stored in a YearMonth.
The ISO-8601 calendar system is the modern civil calendar system used today in most of the world. It is equivalent to the proleptic Gregorian calendar system, in which today's rules for leap years are applied for all time. For most applications written today, the ISO-8601 rules are entirely suitable. However, any application that makes use of historical dates, and requires them to be accurate will find the ISO-8601 approach unsuitable.
This is a value-based class; use of identity-sensitive operations (including reference equality (==), identity hash code, or synchronization) on instances of YearMonth may have unpredictable results and should be avoided. The equals method should be used for comparisons.

Implementation Requirements:

This class is immutable and thread-safe.

Since:

1.8

See Also:

Serialized Form

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`Temporal`	`adjustInto(Temporal temporal)`	Adjusts the specified temporal object to have this year-month.
`LocalDate`	`atDay(int dayOfMonth)`	Combines this year-month with a day-of-month to create a `LocalDate`.
`LocalDate`	`atEndOfMonth()`	Returns a `LocalDate` at the end of the month.
`int`	`compareTo(YearMonth other)`	Compares this year-month to another year-month.
`boolean`	`equals(Object obj)`	Checks if this year-month is equal to another year-month.
`String`	`format(DateTimeFormatter formatter)`	Formats this year-month using the specified formatter.
`static YearMonth`	`from(TemporalAccessor temporal)`	Obtains an instance of `YearMonth` from a temporal object.
`int`	`get(TemporalField field)`	Gets the value of the specified field from this year-month as an `int`.
`long`	`getLong(TemporalField field)`	Gets the value of the specified field from this year-month as a `long`.
`Month`	`getMonth()`	Gets the month-of-year field using the `Month` enum.
`int`	`getMonthValue()`	Gets the month-of-year field from 1 to 12.
`int`	`getYear()`	Gets the year field.
`int`	`hashCode()`	A hash code for this year-month.
`boolean`	`isAfter(YearMonth other)`	Checks if this year-month is after the specified year-month.
`boolean`	`isBefore(YearMonth other)`	Checks if this year-month is before the specified year-month.
`boolean`	`isLeapYear()`	Checks if the year is a leap year, according to the ISO proleptic calendar system rules.
`boolean`	`isSupported(TemporalField field)`	Checks if the specified field is supported.
`boolean`	`isSupported(TemporalUnit unit)`	Checks if the specified unit is supported.
`boolean`	`isValidDay(int dayOfMonth)`	Checks if the day-of-month is valid for this year-month.
`int`	`lengthOfMonth()`	Returns the length of the month, taking account of the year.
`int`	`lengthOfYear()`	Returns the length of the year.
`YearMonth`	`minus(long amountToSubtract, TemporalUnit unit)`	Returns a copy of this year-month with the specified amount subtracted.
`YearMonth`	`minus(TemporalAmount amountToSubtract)`	Returns a copy of this year-month with the specified amount subtracted.
`YearMonth`	`minusMonths(long monthsToSubtract)`	Returns a copy of this `YearMonth` with the specified number of months subtracted.
`YearMonth`	`minusYears(long yearsToSubtract)`	Returns a copy of this `YearMonth` with the specified number of years subtracted.
`static YearMonth`	`now()`	Obtains the current year-month from the system clock in the default time-zone.
`static YearMonth`	`now(Clock clock)`	Obtains the current year-month from the specified clock.
`static YearMonth`	`now(ZoneId zone)`	Obtains the current year-month from the system clock in the specified time-zone.
`static YearMonth`	`of(int year, int month)`	Obtains an instance of `YearMonth` from a year and month.
`static YearMonth`	`of(int year, Month month)`	Obtains an instance of `YearMonth` from a year and month.
`static YearMonth`	`parse(CharSequence text)`	Obtains an instance of `YearMonth` from a text string such as `2007-12`.
`static YearMonth`	`parse(CharSequence text, DateTimeFormatter formatter)`	Obtains an instance of `YearMonth` from a text string using a specific formatter.
`YearMonth`	`plus(long amountToAdd, TemporalUnit unit)`	Returns a copy of this year-month with the specified amount added.
`YearMonth`	`plus(TemporalAmount amountToAdd)`	Returns a copy of this year-month with the specified amount added.
`YearMonth`	`plusMonths(long monthsToAdd)`	Returns a copy of this `YearMonth` with the specified number of months added.
`YearMonth`	`plusYears(long yearsToAdd)`	Returns a copy of this `YearMonth` with the specified number of years added.
`<R> R`	`query(TemporalQuery<R> query)`	Queries this year-month using the specified query.
`ValueRange`	`range(TemporalField field)`	Gets the range of valid values for the specified field.
`String`	`toString()`	Outputs this year-month as a `String`, such as `2007-12`.
`long`	`until(Temporal endExclusive, TemporalUnit unit)`	Calculates the amount of time until another year-month in terms of the specified unit.
`YearMonth`	`with(TemporalAdjuster adjuster)`	Returns an adjusted copy of this year-month.
`YearMonth`	`with(TemporalField field, long newValue)`	Returns a copy of this year-month with the specified field set to a new value.
`YearMonth`	`withMonth(int month)`	Returns a copy of this `YearMonth` with the month-of-year altered.
`YearMonth`	`withYear(int year)`	Returns a copy of this `YearMonth` with the year altered.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Method Detail
  - now
```
public static YearMonth now()
```
    Obtains the current year-month from the system clock in the default time-zone.
    This will query the system clock in the default time-zone to obtain the current year-month.
    Using this method will prevent the ability to use an alternate clock for testing because the clock is hard-coded.
    
    Returns:
    
    the current year-month using the system clock and default time-zone, not null
  - now
```
public static YearMonth now(ZoneId zone)
```
    Obtains the current year-month from the system clock in the specified time-zone.
    This will query the system clock to obtain the current year-month. Specifying the time-zone avoids dependence on the default time-zone.
    Using this method will prevent the ability to use an alternate clock for testing because the clock is hard-coded.
    
    Parameters:
    
    zone - the zone ID to use, not null
    
    Returns:
    
    the current year-month using the system clock, not null
  - now
```
public static YearMonth now(Clock clock)
```
    Obtains the current year-month from the specified clock.
    This will query the specified clock to obtain the current year-month. Using this method allows the use of an alternate clock for testing. The alternate clock may be introduced using dependency injection.
    
    Parameters:
    
    clock - the clock to use, not null
    
    Returns:
    
    the current year-month, not null
  - of
```
public static YearMonth of(int year,
                           Month month)
```
    Obtains an instance of YearMonth from a year and month.
    
    Parameters:
    
    year - the year to represent, from MIN_YEAR to MAX_YEAR
    
    month - the month-of-year to represent, not null
    
    Returns:
    
    the year-month, not null
    
    Throws:
    
    DateTimeException - if the year value is invalid
  - of
```
public static YearMonth of(int year,
                           int month)
```
    Obtains an instance of YearMonth from a year and month.
    
    Parameters:
    
    year - the year to represent, from MIN_YEAR to MAX_YEAR
    
    month - the month-of-year to represent, from 1 (January) to 12 (December)
    
    Returns:
    
    the year-month, not null
    
    Throws:
    
    DateTimeException - if either field value is invalid
  - from
```
public static YearMonth from(TemporalAccessor temporal)
```
    Obtains an instance of YearMonth from a temporal object.
    This obtains a year-month based on the specified temporal. A TemporalAccessor represents an arbitrary set of date and time information, which this factory converts to an instance of YearMonth.
    The conversion extracts the YEAR and MONTH_OF_YEAR fields. The extraction is only permitted if the temporal object has an ISO chronology, or can be converted to a LocalDate.
    This method matches the signature of the functional interface TemporalQuery allowing it to be used as a query via method reference, YearMonth::from.
    
    Parameters:
    
    temporal - the temporal object to convert, not null
    
    Returns:
    
    the year-month, not null
    
    Throws:
    
    DateTimeException - if unable to convert to a YearMonth
  - parse
```
public static YearMonth parse(CharSequence text)
```
    Obtains an instance of YearMonth from a text string such as 2007-12.
    The string must represent a valid year-month. The format must be uuuu-MM. Years outside the range 0000 to 9999 must be prefixed by the plus or minus symbol.
    
    Parameters:
    
    text - the text to parse such as "2007-12", not null
    
    Returns:
    
    the parsed year-month, not null
    
    Throws:
    
    DateTimeParseException - if the text cannot be parsed
  - parse
```
public static YearMonth parse(CharSequence text,
                              DateTimeFormatter formatter)
```
    Obtains an instance of YearMonth from a text string using a specific formatter.
    The text is parsed using the formatter, returning a year-month.
    
    Parameters:
    
    text - the text to parse, not null
    
    formatter - the formatter to use, not null
    
    Returns:
    
    the parsed year-month, not null
    
    Throws:
    
    DateTimeParseException - if the text cannot be parsed
  - isSupported
```
public boolean isSupported(TemporalField field)
```
    Checks if the specified field is supported.
    This checks if this year-month can be queried for the specified field. If false, then calling the range, get and with(TemporalField, long) methods will throw an exception.
    If the field is a ChronoField then the query is implemented here. The supported fields are:
    - MONTH_OF_YEAR
    - PROLEPTIC_MONTH
    - YEAR_OF_ERA
    - YEAR
    - ERA
    All other ChronoField instances will return false.
    If the field is not a ChronoField, then the result of this method is obtained by invoking TemporalField.isSupportedBy(TemporalAccessor) passing this as the argument. Whether the field is supported is determined by the field.
    Specified by:
    
    isSupported in interface TemporalAccessor
    
    Parameters:
    
    field - the field to check, null returns false
    
    Returns:
    
    true if the field is supported on this year-month, false if not
  - isSupported
```
public boolean isSupported(TemporalUnit unit)
```
    Checks if the specified unit is supported.
    This checks if the specified unit can be added to, or subtracted from, this year-month. If false, then calling the plus(long, TemporalUnit) and minus methods will throw an exception.
    If the unit is a ChronoUnit then the query is implemented here. The supported units are:
    - MONTHS
    - YEARS
    - DECADES
    - CENTURIES
    - MILLENNIA
    - ERAS
    All other ChronoUnit instances will return false.
    If the unit is not a ChronoUnit, then the result of this method is obtained by invoking TemporalUnit.isSupportedBy(Temporal) passing this as the argument. Whether the unit is supported is determined by the unit.
    Specified by:
    
    isSupported in interface Temporal
    
    Parameters:
    
    unit - the unit to check, null returns false
    
    Returns:
    
    true if the unit can be added/subtracted, false if not
  - range
```
public ValueRange range(TemporalField field)
```
    Gets the range of valid values for the specified field.
    The range object expresses the minimum and maximum valid values for a field. This year-month is used to enhance the accuracy of the returned range. If it is not possible to return the range, because the field is not supported or for some other reason, an exception is thrown.
    If the field is a ChronoField then the query is implemented here. The supported fields will return appropriate range instances. All other ChronoField instances will throw an UnsupportedTemporalTypeException.
    If the field is not a ChronoField, then the result of this method is obtained by invoking TemporalField.rangeRefinedBy(TemporalAccessor) passing this as the argument. Whether the range can be obtained is determined by the field.
    
    Specified by:
    
    range in interface TemporalAccessor
    
    Parameters:
    
    field - the field to query the range for, not null
    
    Returns:
    
    the range of valid values for the field, not null
    
    Throws:
    
    DateTimeException - if the range for the field cannot be obtained
    
    UnsupportedTemporalTypeException - if the field is not supported
  - get
```
public int get(TemporalField field)
```
    Gets the value of the specified field from this year-month as an int.
    This queries this year-month for the value of the specified field. The returned value will always be within the valid range of values for the field. If it is not possible to return the value, because the field is not supported or for some other reason, an exception is thrown.
    If the field is a ChronoField then the query is implemented here. The supported fields will return valid values based on this year-month, except PROLEPTIC_MONTH which is too large to fit in an int and throw a DateTimeException. All other ChronoField instances will throw an UnsupportedTemporalTypeException.
    If the field is not a ChronoField, then the result of this method is obtained by invoking TemporalField.getFrom(TemporalAccessor) passing this as the argument. Whether the value can be obtained, and what the value represents, is determined by the field.
    
    Specified by:
    
    get in interface TemporalAccessor
    
    Parameters:
    
    field - the field to get, not null
    
    Returns:
    
    the value for the field
    
    Throws:
    
    DateTimeException - if a value for the field cannot be obtained or the value is outside the range of valid values for the field
    
    UnsupportedTemporalTypeException - if the field is not supported or the range of values exceeds an int
    
    ArithmeticException - if numeric overflow occurs
  - getLong
```
public long getLong(TemporalField field)
```
    Gets the value of the specified field from this year-month as a long.
    This queries this year-month for the value of the specified field. If it is not possible to return the value, because the field is not supported or for some other reason, an exception is thrown.
    If the field is a ChronoField then the query is implemented here. The supported fields will return valid values based on this year-month. All other ChronoField instances will throw an UnsupportedTemporalTypeException.
    If the field is not a ChronoField, then the result of this method is obtained by invoking TemporalField.getFrom(TemporalAccessor) passing this as the argument. Whether the value can be obtained, and what the value represents, is determined by the field.
    
    Specified by:
    
    getLong in interface TemporalAccessor
    
    Parameters:
    
    field - the field to get, not null
    
    Returns:
    
    the value for the field
    
    Throws:
    
    DateTimeException - if a value for the field cannot be obtained

Class YearMonth

Method Summary

Methods inherited from class java.lang.Object

Method Detail

now

now

now

of

of

from

parse

parse

isSupported

isSupported

range

get

getLong