date time functions (#425)

* merge networkdays, networkdays.intl #33 * merge time, timevalue, hour, minute, second #35 * merge datedif, datevalue #36 * merge days, days360, weekday, weeknum, workday, workday.intl, yearfrac, isoweeknum #41 * from excel helper * fix build * date time macros * de-dupe weekend * serial helper * de-dupe now today * weekend pattern enum * remove unused clippy wrong self * fix docs * add test coverage * fix build * fix cursor comment * PR coments + xlsx date time
2025-10-19 01:19:19 -07:00
parent 29989b9fd7
commit dd4467f95d
33 changed files with 3354 additions and 182 deletions
--- a/docs/src/functions/date-and-time.md
+++ b/docs/src/functions/date-and-time.md
@@ -12,27 +12,27 @@ You can track the progress in this [GitHub issue](https://github.com/ironcalc/Ir
 | Function         | Status                                         | Documentation |
 | ---------------- | ---------------------------------------------- | ------------- |
 | DATE             | <Badge type="tip" text="Available" />          | –             |
-| DATEDIF          | <Badge type="info" text="Not implemented yet" /> | –             |
-| DATEVALUE        | <Badge type="info" text="Not implemented yet" /> | –             |
+| DATEDIF          | <Badge type="tip" text="Available" />          | [DATEDIF](date_and_time/datedif) |
+| DATEVALUE        | <Badge type="tip" text="Available" />          | [DATEVALUE](date_and_time/datevalue) |
 | DAY              | <Badge type="tip" text="Available" />          | [DAY](date_and_time/day) |
-| DAYS             | <Badge type="info" text="Not implemented yet" /> | –             |
-| DAYS360          | <Badge type="info" text="Not implemented yet" /> | –             |
+| DAYS             | <Badge type="tip" text="Available" />          | –             |
+| DAYS360          | <Badge type="tip" text="Available" />          | –             |
 | EDATE            | <Badge type="tip" text="Available" />          | –             |
 | EOMONTH          | <Badge type="tip" text="Available" />          | –             |
-| HOUR             | <Badge type="info" text="Not implemented yet" /> | –             |
-| ISOWEEKNUM       | <Badge type="info" text="Not implemented yet" /> | –             |
-| MINUTE           | <Badge type="info" text="Not implemented yet" /> | –             |
+| HOUR             | <Badge type="tip" text="Available" />          | [HOUR](date_and_time/hour) |
+| ISOWEEKNUM       | <Badge type="tip" text="Available" />          | –             |
+| MINUTE           | <Badge type="tip" text="Available" />          | [MINUTE](date_and_time/minute) |
 | MONTH            | <Badge type="tip" text="Available" />          | [MONTH](date_and_time/month) |
-| NETWORKDAYS      | <Badge type="info" text="Not implemented yet" /> | –             |
-| NETWORKDAYS.INTL | <Badge type="info" text="Not implemented yet" /> | –             |
+| NETWORKDAYS      | <Badge type="tip" text="Available" />          | [NETWORKDAYS](date_and_time/networkdays) |
+| NETWORKDAYS.INTL | <Badge type="tip" text="Available" />          | [NETWORKDAYS.INTL](date_and_time/networkdays.intl) |
 | NOW              | <Badge type="tip" text="Available" />          | –             |
-| SECOND           | <Badge type="info" text="Not implemented yet" /> | –             |
-| TIME             | <Badge type="info" text="Not implemented yet" /> | –             |
-| TIMEVALUE        | <Badge type="info" text="Not implemented yet" /> | –             |
+| SECOND           | <Badge type="tip" text="Available" />          | [SECOND](date_and_time/second) |
+| TIME             | <Badge type="tip" text="Available" />          | [TIME](date_and_time/time) |
+| TIMEVALUE        | <Badge type="tip" text="Available" />          | [TIMEVALUE](date_and_time/timevalue) |
 | TODAY            | <Badge type="tip" text="Available" />          | –             |
-| WEEKDAY          | <Badge type="info" text="Not implemented yet" /> | –             |
-| WEEKNUM          | <Badge type="info" text="Not implemented yet" /> | –             |
-| WORKDAY          | <Badge type="info" text="Not implemented yet" /> | –             |
-| WORKDAY.INTL     | <Badge type="info" text="Not implemented yet" /> | –             |
+| WEEKDAY          | <Badge type="tip" text="Available" />          | –             |
+| WEEKNUM          | <Badge type="tip" text="Available" />          | –             |
+| WORKDAY          | <Badge type="tip" text="Available" />          | –             |
+| WORKDAY.INTL     | <Badge type="tip" text="Available" />          | –             |
 | YEAR             | <Badge type="tip" text="Available" />          | [YEAR](date_and_time/year) |
-| YEARFRAC         | <Badge type="info" text="Not implemented yet" /> | –             |
+| YEARFRAC         | <Badge type="tip" text="Available" />          | –             |
--- a/docs/src/functions/date_and_time/datedif.md
+++ b/docs/src/functions/date_and_time/datedif.md
@@ -7,6 +7,5 @@ lang: en-US
 # DATEDIF

 ::: warning
-🚧 This function is not yet available in IronCalc.
-[Follow development here](https://github.com/ironcalc/IronCalc/labels/Functions)
+🚧 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).
 :::
--- a/docs/src/functions/date_and_time/datevalue.md
+++ b/docs/src/functions/date_and_time/datevalue.md
@@ -7,6 +7,5 @@ lang: en-US
 # DATEVALUE

 ::: warning
-🚧 This function is not yet available in IronCalc.
-[Follow development here](https://github.com/ironcalc/IronCalc/labels/Functions)
+🚧 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).
 :::
--- a/docs/src/functions/date_and_time/days.md
+++ b/docs/src/functions/date_and_time/days.md
@@ -7,6 +7,5 @@ lang: en-US
 # DAYS

 ::: warning
-🚧 This function is not yet available in IronCalc.
-[Follow development here](https://github.com/ironcalc/IronCalc/labels/Functions)
+🚧 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).
 :::
--- a/docs/src/functions/date_and_time/days360.md
+++ b/docs/src/functions/date_and_time/days360.md
@@ -7,6 +7,5 @@ lang: en-US
 # DAYS360

 ::: warning
-🚧 This function is not yet available in IronCalc.
-[Follow development here](https://github.com/ironcalc/IronCalc/labels/Functions)
+🚧 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).
 :::
--- a/docs/src/functions/date_and_time/hour.md
+++ b/docs/src/functions/date_and_time/hour.md
@@ -7,6 +7,6 @@ lang: en-US
 # HOUR

 ::: warning
-🚧 This function is not yet available in IronCalc.
-[Follow development here](https://github.com/ironcalc/IronCalc/labels/Functions)
+**Note:** This draft page is under construction 🚧
+The HOUR function is implemented and available in IronCalc.
 :::
--- a/docs/src/functions/date_and_time/isoweeknum.md
+++ b/docs/src/functions/date_and_time/isoweeknum.md
@@ -7,6 +7,5 @@ lang: en-US
 # ISOWEEKNUM

 ::: warning
-🚧 This function is not yet available in IronCalc.
-[Follow development here](https://github.com/ironcalc/IronCalc/labels/Functions)
+🚧 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).
 :::
--- a/docs/src/functions/date_and_time/minute.md
+++ b/docs/src/functions/date_and_time/minute.md
@@ -7,6 +7,6 @@ lang: en-US
 # MINUTE

 ::: warning
-🚧 This function is not yet available in IronCalc.
-[Follow development here](https://github.com/ironcalc/IronCalc/labels/Functions)
+**Note:** This draft page is under construction 🚧
+The MINUTE function is implemented and available in IronCalc.
 :::
--- a/docs/src/functions/date_and_time/networkdays.intl.md
+++ b/docs/src/functions/date_and_time/networkdays.intl.md
@@ -4,9 +4,73 @@ outline: deep
 lang: en-US
 ---

-# NETWORKDAYS.INTL
+# NETWORKDAYS.INTL function

 ::: warning
-🚧 This function is not yet available in IronCalc.
-[Follow development here](https://github.com/ironcalc/IronCalc/labels/Functions)
-:::
+**Note:** This draft page is under construction 🚧
+:::
+
+## Overview
+NETWORKDAYS.INTL is a function of the Date and Time category that calculates the number of working days between two dates, with customizable weekend definitions and optionally specified holidays.
+
+## Usage
+
+### Syntax
+**NETWORKDAYS.INTL(<span title="Number" style="color:#1E88E5">start_date</span>, <span title="Number" style="color:#1E88E5">end_date</span>, [<span title="Number or String" style="color:#4CAF50">weekend</span>], [<span title="Array" style="color:#E91E63">holidays</span>]) => <span title="Number" style="color:#1E88E5">workdays</span>**
+
+### Argument descriptions
+* *start_date* ([number](/features/value-types#numbers), required). The start date expressed as a [serial number](/features/serial-numbers.md).
+* *end_date* ([number](/features/value-types#numbers), required). The end date expressed as a [serial number](/features/serial-numbers.md).
+* *weekend* ([number](/features/value-types#numbers) or [string](/features/value-types#strings), optional). Defines which days are considered weekends. Default is 1 (Saturday-Sunday).
+* *holidays* ([array](/features/value-types#arrays) or [range](/features/ranges), optional). A list of dates to exclude from the calculation, expressed as serial numbers.
+
+### Weekend parameter options
+The _weekend_ parameter can be specified in two ways:
+
+**Numeric codes:**
+- 1 (default): Saturday and Sunday
+- 2: Sunday and Monday
+- 3: Monday and Tuesday
+- 4: Tuesday and Wednesday
+- 5: Wednesday and Thursday
+- 6: Thursday and Friday
+- 7: Friday and Saturday
+- 11: Sunday only
+- 12: Monday only
+- 13: Tuesday only
+- 14: Wednesday only
+- 15: Thursday only
+- 16: Friday only
+- 17: Saturday only
+
+**String pattern:** A 7-character string of "0" and "1" where "1" indicates a weekend day. The string represents Monday through Sunday. For example, "0000011" means Saturday and Sunday are weekends.
+
+### Additional guidance
+- If the supplied _start_date_ and _end_date_ arguments have fractional parts, NETWORKDAYS.INTL uses their [floor values](https://en.wikipedia.org/wiki/Floor_and_ceiling_functions).
+- If _start_date_ is later than _end_date_, the function returns a negative number.
+- Empty cells in the _holidays_ array are ignored.
+- The calculation includes both the start and end dates if they are workdays.
+
+### Returned value
+NETWORKDAYS.INTL returns a [number](/features/value-types#numbers) representing the count of working days between the two dates.
+
+### Error conditions
+* In common with many other IronCalc functions, NETWORKDAYS.INTL propagates errors that are found in its arguments.
+* If fewer than 2 or more than 4 arguments are supplied, then NETWORKDAYS.INTL returns the [`#ERROR!`](/features/error-types.md#error) error.
+* If the *start_date* or *end_date* arguments are not (or cannot be converted to) [numbers](/features/value-types#numbers), then NETWORKDAYS.INTL returns the [`#VALUE!`](/features/error-types.md#value) error.
+* If the *start_date* or *end_date* values are outside the valid date range, then NETWORKDAYS.INTL returns the [`#NUM!`](/features/error-types.md#num) error.
+* If the *weekend* parameter is an invalid numeric code or an improperly formatted string, then NETWORKDAYS.INTL returns the [`#NUM!`](/features/error-types.md#num) or [`#VALUE!`](/features/error-types.md#value) error.
+* If the *holidays* array contains non-numeric values, then NETWORKDAYS.INTL returns the [`#VALUE!`](/features/error-types.md#value) error.
+
+<!--@include: ../markdown-snippets/error-type-details.txt-->
+
+## Details
+IronCalc utilizes Rust's [chrono](https://docs.rs/chrono/latest/chrono/) crate to implement the NETWORKDAYS.INTL function. This function provides more flexibility than NETWORKDAYS by allowing custom weekend definitions.
+
+## Examples
+[See some examples in IronCalc](https://app.ironcalc.com/?example=networkdays-intl).
+
+## Links
+* See also IronCalc's [NETWORKDAYS](/functions/date_and_time/networkdays.md) function for the basic version with fixed weekends.
+* Visit Microsoft Excel's [NETWORKDAYS.INTL function](https://support.microsoft.com/en-us/office/networkdays-intl-function-a9b26239-4f20-46a1-9ab8-4e925bfd5e28) page.
+* Both [Google Sheets](https://support.google.com/docs/answer/3093019) and [LibreOffice Calc](https://wiki.documentfoundation.org/Documentation/Calc_Functions/NETWORKDAYS.INTL) provide versions of the NETWORKDAYS.INTL function.
--- a/docs/src/functions/date_and_time/networkdays.md
+++ b/docs/src/functions/date_and_time/networkdays.md
@@ -4,9 +4,51 @@ outline: deep
 lang: en-US
 ---

-# NETWORKDAYS
+# NETWORKDAYS function

 ::: warning
-🚧 This function is not yet available in IronCalc.
-[Follow development here](https://github.com/ironcalc/IronCalc/labels/Functions)
-:::
+**Note:** This draft page is under construction 🚧
+:::
+
+## Overview
+NETWORKDAYS is a function of the Date and Time category that calculates the number of working days between two dates, excluding weekends (Saturday and Sunday by default) and optionally specified holidays.
+
+## Usage
+
+### Syntax
+**NETWORKDAYS(<span title="Number" style="color:#1E88E5">start_date</span>, <span title="Number" style="color:#1E88E5">end_date</span>, [<span title="Array" style="color:#E91E63">holidays</span>]) => <span title="Number" style="color:#1E88E5">workdays</span>**
+
+### Argument descriptions
+* *start_date* ([number](/features/value-types#numbers), required). The start date expressed as a [serial number](/features/serial-numbers.md).
+* *end_date* ([number](/features/value-types#numbers), required). The end date expressed as a [serial number](/features/serial-numbers.md).
+* *holidays* ([array](/features/value-types#arrays) or [range](/features/ranges), optional). A list of dates to exclude from the calculation, expressed as serial numbers.
+
+### Additional guidance
+- If the supplied _start_date_ and _end_date_ arguments have fractional parts, NETWORKDAYS uses their [floor values](https://en.wikipedia.org/wiki/Floor_and_ceiling_functions).
+- If _start_date_ is later than _end_date_, the function returns a negative number.
+- Weekend days are Saturday and Sunday by default. Use [NETWORKDAYS.INTL](networkdays.intl) for custom weekend definitions.
+- Empty cells in the _holidays_ array are ignored.
+- The calculation includes both the start and end dates if they are workdays.
+
+### Returned value
+NETWORKDAYS returns a [number](/features/value-types#numbers) representing the count of working days between the two dates.
+
+### Error conditions
+* In common with many other IronCalc functions, NETWORKDAYS propagates errors that are found in its arguments.
+* If fewer than 2 or more than 3 arguments are supplied, then NETWORKDAYS returns the [`#ERROR!`](/features/error-types.md#error) error.
+* If the *start_date* or *end_date* arguments are not (or cannot be converted to) [numbers](/features/value-types#numbers), then NETWORKDAYS returns the [`#VALUE!`](/features/error-types.md#value) error.
+* If the *start_date* or *end_date* values are outside the valid date range, then NETWORKDAYS returns the [`#NUM!`](/features/error-types.md#num) error.
+* If the *holidays* array contains non-numeric values, then NETWORKDAYS returns the [`#VALUE!`](/features/error-types.md#value) error.
+
+<!--@include: ../markdown-snippets/error-type-details.txt-->
+
+## Details
+IronCalc utilizes Rust's [chrono](https://docs.rs/chrono/latest/chrono/) crate to implement the NETWORKDAYS function. The function treats Saturday and Sunday as weekend days.
+
+## Examples
+[See some examples in IronCalc](https://app.ironcalc.com/?example=networkdays).
+
+## Links
+* See also IronCalc's [NETWORKDAYS.INTL](/functions/date_and_time/networkdays.intl.md) function for custom weekend definitions.
+* Visit Microsoft Excel's [NETWORKDAYS function](https://support.microsoft.com/en-us/office/networkdays-function-48e717bf-a7a3-495f-969e-5005e3eb18e7) page.
+* Both [Google Sheets](https://support.google.com/docs/answer/3093018) and [LibreOffice Calc](https://wiki.documentfoundation.org/Documentation/Calc_Functions/NETWORKDAYS) provide versions of the NETWORKDAYS function.
--- a/docs/src/functions/date_and_time/second.md
+++ b/docs/src/functions/date_and_time/second.md
@@ -7,6 +7,6 @@ lang: en-US
 # SECOND

 ::: warning
-🚧 This function is not yet available in IronCalc.
-[Follow development here](https://github.com/ironcalc/IronCalc/labels/Functions)
+**Note:** This draft page is under construction 🚧
+The SECOND function is implemented and available in IronCalc.
 :::
--- a/docs/src/functions/date_and_time/time.md
+++ b/docs/src/functions/date_and_time/time.md
@@ -7,6 +7,6 @@ lang: en-US
 # TIME

 ::: warning
-🚧 This function is not yet available in IronCalc.
-[Follow development here](https://github.com/ironcalc/IronCalc/labels/Functions)
+**Note:** This draft page is under construction 🚧
+The TIME function is implemented and available in IronCalc.
 :::
--- a/docs/src/functions/date_and_time/timevalue.md
+++ b/docs/src/functions/date_and_time/timevalue.md
@@ -7,6 +7,6 @@ lang: en-US
 # TIMEVALUE

 ::: warning
-🚧 This function is not yet available in IronCalc.
-[Follow development here](https://github.com/ironcalc/IronCalc/labels/Functions)
+**Note:** This draft page is under construction 🚧
+The TIMEVALUE function is implemented and available in IronCalc.
 :::
--- a/docs/src/functions/date_and_time/weekday.md
+++ b/docs/src/functions/date_and_time/weekday.md
@@ -7,6 +7,5 @@ lang: en-US
 # WEEKDAY

 ::: warning
-🚧 This function is not yet available in IronCalc.
-[Follow development here](https://github.com/ironcalc/IronCalc/labels/Functions)
+🚧 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).
 :::
--- a/docs/src/functions/date_and_time/weeknum.md
+++ b/docs/src/functions/date_and_time/weeknum.md
@@ -7,6 +7,5 @@ lang: en-US
 # WEEKNUM

 ::: warning
-🚧 This function is not yet available in IronCalc.
-[Follow development here](https://github.com/ironcalc/IronCalc/labels/Functions)
+🚧 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).
 :::
--- a/docs/src/functions/date_and_time/workday.intl.md
+++ b/docs/src/functions/date_and_time/workday.intl.md
@@ -7,6 +7,5 @@ lang: en-US
 # WORKDAY.INTL

 ::: warning
-🚧 This function is not yet available in IronCalc.
-[Follow development here](https://github.com/ironcalc/IronCalc/labels/Functions)
+🚧 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).
 :::
--- a/docs/src/functions/date_and_time/workday.md
+++ b/docs/src/functions/date_and_time/workday.md
@@ -7,6 +7,5 @@ lang: en-US
 # WORKDAY

 ::: warning
-🚧 This function is not yet available in IronCalc.
-[Follow development here](https://github.com/ironcalc/IronCalc/labels/Functions)
+🚧 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).
 :::
--- a/docs/src/functions/date_and_time/yearfrac.md
+++ b/docs/src/functions/date_and_time/yearfrac.md
@@ -7,6 +7,5 @@ lang: en-US
 # YEARFRAC

 ::: warning
-🚧 This function is not yet available in IronCalc.
-[Follow development here](https://github.com/ironcalc/IronCalc/labels/Functions)
+🚧 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).
 :::