From 02e726b4458c9f1de87a3405130d42625314c128 Mon Sep 17 00:00:00 2001 From: Steve Fanning Date: Thu, 2 Jan 2025 16:29:53 +0000 Subject: [PATCH] Add YEAR function description --- docs/src/functions/date-and-time.md | 2 +- docs/src/functions/date_and_time/year.md | 36 +++++++++++++++++++---- xlsx/tests/docs/YEAR.xlsx | Bin 9594 -> 10715 bytes 3 files changed, 32 insertions(+), 6 deletions(-) diff --git a/docs/src/functions/date-and-time.md b/docs/src/functions/date-and-time.md index bdeccab..2a47942 100644 --- a/docs/src/functions/date-and-time.md +++ b/docs/src/functions/date-and-time.md @@ -34,5 +34,5 @@ You can track the progress in this [GitHub issue](https://github.com/ironcalc/Ir | WEEKNUM | | – | | WORKDAY | | – | | WORKDAY.INTL | | – | -| YEAR | | – | +| YEAR | | [YEAR](date_and_time/year) | | YEARFRAC | | – | diff --git a/docs/src/functions/date_and_time/year.md b/docs/src/functions/date_and_time/year.md index b38831b..5c8038f 100644 --- a/docs/src/functions/date_and_time/year.md +++ b/docs/src/functions/date_and_time/year.md @@ -3,9 +3,35 @@ layout: doc outline: deep lang: en-US --- - -# YEAR - +# YEAR function ::: warning -🚧 This function is implemented but currently lacks detailed documentation. For guidance, you may refer to the equivalent functionality in [Microsoft Excel documentation](https://support.microsoft.com/en-us/office/excel-functions-by-category-5f91f4e9-7b42-46d2-9bd1-63f26a86c0eb). -::: \ No newline at end of file +**Note:** This draft page is under construction 🚧 +::: +## Overview +YEAR is a function of the Date and Time category that extracts the year from a valid date [serial number](/features/serial-numbers.md), returning a number in the range [1899, 9999]. +## Usage +### Syntax +**YEAR(date) => year** +### Argument descriptions +* *date* ([number](/features/value-types#numbers), required). The date for which the year is to be calculated, expressed as a [serial number](/features/serial-numbers.md) in the range [1, 2958466). The value 1 corresponds to the date 1899-12-31, while 2958465 corresponds to 9999-12-31. +### Additional guidance +If the supplied _date_ argument has a fractional part, YEAR uses its [floor value](https://en.wikipedia.org/wiki/Floor_and_ceiling_functions). +### Returned value +YEAR returns an integer [number](/features/value-types#numbers) in the range [1899, 9999], that is the year according to the [Gregorian calendar](https://en.wikipedia.org/wiki/Gregorian_calendar). +### Error conditions +* In common with many other IronCalc functions, YEAR propagates errors that are found in its argument. +* If no argument, or more than one argument, is supplied, then YEAR returns the [`#ERROR!`](/features/error-types.md#error) error. +* If the value of the *date* argument is not (or cannot be converted to) a [number](/features/value-types#numbers), then YEAR returns the [`#VALUE!`](/features/error-types.md#value) error. +* For some argument values, YEAR may return the [`#DIV/0!`](/features/error-types.md#div-0) error. +* If date is less than 0, or greater than or equal to 2,958,466, then YEAR returns the [`#NUM!`](/features/error-types.md#num) error. +* At present, YEAR does not accept a string representation of a date literal as an argument. For example, the formula `=YEAR("2024-12-31")` returns the [`#VALUE!`](/features/error-types.md#value) error. + +## Details +IronCalc utilizes Rust's [chrono](https://docs.rs/chrono/latest/chrono/) crate to implement the YEAR function. +## Examples +[See some examples in IronCalc](https://app.ironcalc.com/?example=year). + +## Links +* See also IronCalc's [DAY](/functions/date_and_time/day.md) and [MONTH](/functions/date_and_time/month.md) functions. +* Visit Microsoft Excel's [YEAR function](https://support.microsoft.com/en-gb/office/year-function-c64f017a-1354-490d-981f-578e8ec8d3b9) page. +* Both [Google Sheets](https://support.google.com/docs/answer/3093061) and [LibreOffice Calc](https://wiki.documentfoundation.org/Documentation/Calc_Functions/YEAR) provide versions of the YEAR function. \ No newline at end of file diff --git a/xlsx/tests/docs/YEAR.xlsx b/xlsx/tests/docs/YEAR.xlsx index c283e0334ca0106b566e66bce821a955b496abfc..52a4b257794177ef565d1624052b0e4be967fb0b 100644 GIT binary patch delta 4642 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