Documentation/Calc Functions/YEARS
TDF LibreOffice Document Liberation Project Community Blogs Weblate Nextcloud Redmine Ask LibreOffice Donate
Function name:
YEARS
Category:
Date and Time
Summary:
Calculates the number of years between two dates.
Syntax:
YEARS(StartDate; EndDate; Type)
Returns:
Returns an integer value which is the difference between the two given dates in years, depending on the calculation mode selected through the Type argument.
Arguments:
StartDate is the date (in quotation marks) or a date-time serial number, or a reference to the cell containing one of those types, which is either the start date or the end date of the period for which the calculation is to be carried out.
EndDate is the date (in quotation marks) or a date-time serial number, or a reference to the cell containing one of those types, which is either the end date or the start date of the period for which the calculation is to be carried out.
Type is an integer value, either 0 or 1. If Type is 0, then YEARS returns the number of whole years between StartDate and EndDate (day/month to day/month). If Type is 1, YEARS identifies the year that each of StartDate and EndDate lie in, and then returns the difference between those years.
- If either StartDate or EndDate is not a valid date expression, then YEARS returns a #VALUE! error.
- If StartDate is earlier than EndDate, the result is a positive number; if StartDate is later than EndDate, the result is a negative number.
- YEARS ignores any time components of StartDate and EndDate.
- If Type is non-numeric, then YEARS reports a #VALUE! error.
- If Type is a non-integer value, then YEARS truncates it to an integer.
- If (after truncation) Type is not equal to either 0 or 1, then YEARS reports an invalid argument error (Err:502).
Additional details:
Details specific to YEARS function
YEARS is not part of the ODF 1.2 international standard and should not be regarded as portable.
General information about Calc's Date and Time functions
 |
Note:
|
- Internal to Calc, a date/time value is handled as a real number and this is sometimes referred to by the term date-time serial number. For example, 2021-02-08 12:00:00 corresponds to the date-time serial number 44235.5. The integer part of a date-time serial number (before the decimal separator) is the number of days since a defined start date. The fractional part of a date-time serial number (after the decimal separator) is the time of day expressed as a fraction of a day. For example, 0.25 is equivalent to 06:00:00 and 0.75 is equivalent to 18:00:00.
- Calc uses 1899-12-30 as the default start date (day 0) but you can go to ▸ ▸ ▸ to select alternative start dates; however, unless you have specific requirements for compatibility with legacy spreadsheet applications, we recommend that you do not change this setting. If you copy and paste cells containing date values between different spreadsheets, check that both documents are set to use the same start date to avoid unexpected changes to the dates displayed.
- Negative date-time serial numbers correspond to dates earlier than Calc's start date. Calc calculates all dates back to 15th October 1582 using the Gregorian calendar. The day before this is 4th October 1582, and Calc uses the Julian calendar for earlier dates.
- A date-time serial number is the same as any other number, except that we usually choose to display it formatted as a date/time. You can enter a number in a cell and then change the cell's formatting to display the value as a date/time. You can also enter a date/time in a cell and then change the cell's formatting to display the date-time serial number.
- For clarity, the descriptions of the Calc functions within these wiki pages use the standard ISO 8601 format for date and time because this should be independent of your selected locale settings. The default date format on your computer may be different. When entering dates as part of formulas, slashes or dashes used as date separators may be interpreted as arithmetic operators. Therefore, dates entered in this format are not recognized as dates and result in erroneous calculations. To keep dates from being interpreted as parts of formulas either use the DATE function or place the date in quotation marks and use the ISO 8601 notation. Avoid using locale dependent date formats which may produce errors if the document is loaded under different locale settings.
- Time zone information is not used by Calc's Date & Time functions.
- If you only wish to enter two digits of the year (for example 21 instead of 2021), Calc needs to know whether you mean 2021 or 1921. Go to ▸ ▸ ▸ to view or adjust the range of years which Calc will use to interpret two-digit year values.
- Calc contains logic to decide how to treat text when encountered as an operand in an arithmetic operation or as an argument to a function that expects a number instead. In this context, unambiguous conversion is possible for ISO 8601 dates and times in their extended formats with separators. For example, the simple formula
=1 + "2021-02-08"will usually give the result2021-02-09(when formatted as a date). However, this logic may be affected by the settings on the Detailed Calculation Settings dialog, accessed by selecting ▸ ▸ ▸ and pressing the button in the Detailed Calculation Settings area. If a #VALUE! error occurs, it may be because the Generate #VALUE! error option is selected, in which case you should experiment with one of the other self-explanatory options in the Conversion from text to number drop-down.
Examples:
| Formula | Description | Returns |
|---|---|---|
| =YEARS("2015-07-01"; "2021-01-01"; 0) | Here the function returns 5. With Type set to 0, there is approximately 5.5 years between the two dates but this is truncated to an integer value by YEARS. | 5 |
| =YEARS("2015-07-01"; "2021-01-01"; 1) | Here the function returns 6. With Type set to 1, YEARS subtracts 2015 from 2021. | 6 |
| =YEARS("2021-01-01"; "2015-07-01"; 1) | Here the function returns -6. Similar to the previous example, except for reordering the two date arguments. Since StartDate is now later than EndDate, YEARS returns a negative value. | −6 |
=YEARS(F1; F2; F3) where cell F1 contains the date 2018-06-30, cell F2 contains the date 2021-09-01, and cell F3 contains the value 1. |
Here the function returns 3. | 3 |
| =YEARS(43889; 44255; 0) | Here the function returns 1. Values 43889 and 44255 are the date-time serial numbers for 2020-02-28 and 2021-02-28 respectively. 2020 is a leap year, but February 28 to February 28 is counted as a whole year. | 1 |
| =YEARS(43890; 44255; 0) | Here the function returns 0. Values 43890 and 44255 are the date-time serial numbers for 2020-02-29 and 2021-02-28 respectively. Contrast this with the previous example. 2020 is a leap year, but February 29 to February 28 is not classed as a whole year, even though both dates are the last day of February. | 0 |
Related LibreOffice functions:
ODF standard:
None.
Related (or similar) Excel functions:
None.