From 564d4bac7a9a5a551a842d41712f68cffd67e5b8 Mon Sep 17 00:00:00 2001 From: Steve Fanning Date: Tue, 31 Dec 2024 19:58:12 +0000 Subject: [PATCH] Add DAY function description --- docs/src/.vitepress/config.mts | 4 +++ docs/src/features/serial-numbers.md | 33 ++++++++++++++++++++++ docs/src/functions/date-and-time.md | 2 +- docs/src/functions/date_and_time/day.md | 36 ++++++++++++++++++++---- xlsx/tests/docs/DAY.xlsx | Bin 10801 -> 10704 bytes 5 files changed, 69 insertions(+), 6 deletions(-) create mode 100644 docs/src/features/serial-numbers.md diff --git a/docs/src/.vitepress/config.mts b/docs/src/.vitepress/config.mts index 4f42410..6e999a2 100644 --- a/docs/src/.vitepress/config.mts +++ b/docs/src/.vitepress/config.mts @@ -70,6 +70,10 @@ export default defineConfig({ text: "Units", link: "/features/units", }, + { + text: "Serial Numbers", + link: "/features/serial-numbers", + }, { text: "Unsupported Features", link: "/features/unsupported-features", diff --git a/docs/src/features/serial-numbers.md b/docs/src/features/serial-numbers.md new file mode 100644 index 0000000..ffd08cf --- /dev/null +++ b/docs/src/features/serial-numbers.md @@ -0,0 +1,33 @@ +--- +layout: doc +outline: deep +lang: en-US +--- + +# Serial Numbers +::: warning +**Note:** This draft page is under construction 🚧 +::: +**Note**: For convenience, dates presented on this page are formatted in accordance with the ISO 8601 international standard. IronCalc can recognize and display dates in other formats. + +IronCalc stores dates and times as positive numbers, referred to as *serial numbers*. Serial numbers can be formatted to display the date and time. + +The integer part of a serial number represents the date, as a count of the days since the fixed starting date of 1899-12-30. Hence dates are represented by a unique, sequential integer value, for example: +* 1 corresponds to 1899-12-31. +* 2 corresponds to 1900-01-01. +* 36,526 corresponds to 2000-01-01. +* 45,658 corresponds to 2025-01-01. +* 2,958,465 corresponds to 9999-12-31. + +To illustrate the concept, type the value 2 into an empty cell that is initially formatted as a number. When you subsequently change the cell to a date format, it will update to show the date 1900-01-01. + +The fractional part of a serial number represents time, as a fraction of the day. For example: +* 0.0 corresponds to 00:00:00 (midnight) +* 0.041666667 corresponds to 01:00:00. +* 0.5 corresponds to 12:00:00 (noon) +* 0.75 corresponds to 18:00:00. +* 0.99 corresponds to 23:45:36. + +Since date-times are stored as numbers, they can be used for arithmetic operations in formulas. For example, it is possible to determine the difference between two dates by subtracting one serial number from the other. + +**Note**: A #VALUE! error is reported if a date-formatted cell contains a number less than 1 or greater than 2,958,465. diff --git a/docs/src/functions/date-and-time.md b/docs/src/functions/date-and-time.md index e48450e..c675130 100644 --- a/docs/src/functions/date-and-time.md +++ b/docs/src/functions/date-and-time.md @@ -14,7 +14,7 @@ You can track the progress in this [GitHub issue](https://github.com/ironcalc/Ir | DATE | | – | | DATEDIF | | – | | DATEVALUE | | – | -| DAY | | – | +| DAY | | [DAY](date_and_time/day) | | DAYS | | – | | DAYS360 | | – | | EDATE | | – | diff --git a/docs/src/functions/date_and_time/day.md b/docs/src/functions/date_and_time/day.md index 7cd8f5a..c8a993b 100644 --- a/docs/src/functions/date_and_time/day.md +++ b/docs/src/functions/date_and_time/day.md @@ -3,9 +3,35 @@ layout: doc outline: deep lang: en-US --- - -# DAY - +# DAY 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 +DAY is a function of the Date and Time category that extracts the day of the month from a valid date [serial number](/features/serial-numbers.md), returning a number in the range [1, 31]. +## Usage +### Syntax +**DAY(date) => day** +### Argument descriptions +* *date* ([number](/features/value-types#numbers), required). The date for which the day of the month is to be calculated, expressed as a [serial number](/features/serial-numbers.md) in the range [0, 2958465]. The value 0 corresponds to the date 1899-12-30, while 2958465 corresponds to 9999-12-31. +### Additional guidance +If the supplied _date_ argument has a fractional part, DAY uses its [floor value](https://en.wikipedia.org/wiki/Floor_and_ceiling_functions). +### Returned value +DAY returns an integer [number](/features/value-types#numbers) in the range [1, 31], that is the day of the month according to the [Gregorian calendar](https://en.wikipedia.org/wiki/Gregorian_calendar). +### Error conditions +* In common with many other IronCalc functions, DAY propagates errors that are found in its argument. +* If no argument, or more than one argument, is supplied, then DAY 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 DAY returns the [`#VALUE!`](/features/error-types.md#value) error. +* For some argument values, DAY may return the [`#DIV/0!`](/features/error-types.md#div-0) error. +* If date is less than 0, or greater than 2,958,465, then DAY returns the [`#NUM!`](/features/error-types.md#num) error. +* At present, DAY does not accept a string representation of a date literal as an argument. For example, the formula `=DAY("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 DAY function. +## Examples +[See some examples in IronCalc](https://app.ironcalc.com/?example=day). + +## Links +* See also IronCalc's [MONTH](/functions/date_and_time/month.md) and [YEAR](/functions/date_and_time/year.md) functions. +* Visit Microsoft Excel's [DAY function](https://support.microsoft.com/en-gb/office/day-function-8a7d1cbb-6c7d-4ba1-8aea-25c134d03101) page. +* Both [Google Sheets](https://support.google.com/docs/answer/3093040) and [LibreOffice Calc](https://wiki.documentfoundation.org/Documentation/Calc_Functions/DAY) provide versions of the DAY function. \ No newline at end of file diff --git a/xlsx/tests/docs/DAY.xlsx b/xlsx/tests/docs/DAY.xlsx index f131f04f004e61b576639d30357baa07634b3963..55bce6512dc94ca15396848bb9159e44d668bc89 100644 GIT binary patch delta 4719 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 delta 4863 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