update: adds docs, unit tests and xlsx tests for DATEVALUE and TIMEVALUE functions (#506)

* update: adds documentation for DATEVALUE and TIMEVALUE functions

* update: adds DATEVALUE and TIMEVALUE unit tests

* update: adds DATEVALUE and TIMEVALUE xlsx tests

* update: Date and Time main page links

* update: adds testing for multiple arguments

* update: removes links to example files

* update: removes DATEVALUE and TIMEVALUE xlsx tests

base/src/test/test_fn_datevalue_timevalue.rs

@@ -0,0 +1,24 @@
+#![allow(clippy::unwrap_used)]
+
+use crate::test::util::new_empty_model;
+
+#[test]
+fn datevalue_timevalue_arguments() {
+    let mut model = new_empty_model();
+    model._set("A1", "=DATEVALUE()");
+    model._set("A2", "=TIMEVALUE()");
+    model._set("A3", "=DATEVALUE("2000-01-01")")
+    model._set("A4", "=TIMEVALUE("12:00:00")")
+    model._set("A5", "=DATEVALUE(1,2)");
+    model._set("A6", "=TIMEVALUE(1,2)");
+    model.evaluate();
+
+    assert_eq!(model._get_text("A1"), *"#ERROR!");
+    assert_eq!(model._get_text("A2"), *"#ERROR!");
+    assert_eq!(model._get_text("A3"), *"36526");
+    assert_eq!(model._get_text("A4"), *"0.5");
+    assert_eq!(model._get_text("A5"), *"#ERROR!");
+    assert_eq!(model._get_text("A6"), *"#ERROR!");
+}
+
+

docs/src/functions/date-and-time.md

@@ -12,7 +12,7 @@ All Date and Time functions are already supported in IronCalc.
 | ---------------- | ---------------------------------------------- | ------------- |
 | DATE             | <Badge type="tip" text="Available" />          | –             |
 | DATEDIF          | <Badge type="tip" text="Available" />          | –             |
-| DATEVALUE        | <Badge type="tip" text="Available" />          | –             |
+| 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="tip" text="Available" />          | –             |
 | DAYS360          | <Badge type="tip" text="Available" />          | –             |
@@ -27,7 +27,7 @@ All Date and Time functions are already supported in IronCalc.
 | NOW              | <Badge type="tip" text="Available" />          | –             |
 | SECOND           | <Badge type="tip" text="Available" />          | –             |
 | TIME             | <Badge type="tip" text="Available" />          | –             |
-| TIMEVALUE        | <Badge type="tip" text="Available" />          | –             |
+| TIMEVALUE        | <Badge type="tip" text="Available" />          | [TIMEVALUE](date_and_time/timevalue) |
 | TODAY            | <Badge type="tip" text="Available" />          | –             |
 | WEEKDAY          | <Badge type="tip" text="Available" />          | –             |
 | WEEKNUM          | <Badge type="tip" text="Available" />          | –             |

docs/src/functions/date_and_time/datevalue.md

@@ -4,8 +4,41 @@ outline: deep
 lang: en-US
 ---
 
-# DATEVALUE
+# DATEVALUE function
 
-::: warning
+## Overview
-🚧 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).
+DATEVALUE is a function of the Date and Time category that converts a date stored as text to a [serial number](/features/serial-numbers.md) corresponding to a date value.
-:::
+
+## Usage
+### Syntax
+**DATEVALUE(<span title="Text" style="color:#1E88E5">date_text</span>) => <span title="Number" style="color:#1E88E5">datevalue</span>**
+
+### Argument descriptions
+* *date_text* ([text](/features/value-types#strings), required). A text string that represents a date in a known format. The text must represent a date between December 31, 1899 and December 31, 9999.
+
+### Additional guidance
+* If the year portion of the *date_text* argument is omitted, DATEVALUE uses the current year from the system clock.
+* Time information in the *date_text* argument is ignored. DATEVALUE processes only the date portion.
+
+### Returned value
+DATEVALUE returns a [number](/features/value-types#numbers) that represents the date as a [serial number](/features/serial-numbers.md). The serial number corresponds to the number of days since December 31, 1899.
+
+### Error conditions
+* In common with many other IronCalc functions, DATEVALUE propagates errors that are found in its argument.
+* If no argument, or more than one argument, is supplied, then DATEVALUE returns the [`#ERROR!`](/features/error-types.md#error) error.
+* If the value of the *date_text* argument is not (or cannot be converted to) a [text](/features/value-types#strings) value, then DATEVALUE returns the [`#VALUE!`](/features/error-types.md#value) error.
+* If the *date_text* argument represents a date outside the valid range (before December 31, 1899 or after December 31, 9999), then DATEVALUE returns the [`#VALUE!`](/features/error-types.md#value) error.
+* If the *date_text* argument cannot be recognized as a valid date format, then DATEVALUE returns the [`#VALUE!`](/features/error-types.md#value) error.
+<!--@include: ../markdown-snippets/error-type-details.txt-->
+
+<!-- ## Details
+For more information on how IronCalc processes Date and Time functions and values, visit [Date and Time](/features/serial-numbers.md) 
+
+## Examples
+[See some examples in IronCalc](https://app.ironcalc.com/?example=datevalue).
+-->
+
+## Links
+* See also IronCalc's [TIMEVALUE](/functions/date_and_time/timevalue.md) function for converting time text to serial numbers.
+* Visit Microsoft Excel's [DATEVALUE function](https://support.microsoft.com/en-us/office/datevalue-function-df8b07d4-7761-4a93-bc33-b7471bbff252) page.
+* Both [Google Sheets](https://support.google.com/docs/answer/3093039) and [LibreOffice Calc](https://wiki.documentfoundation.org/Documentation/Calc_Functions/DATEVALUE) provide versions of the DATEVALUE function.

docs/src/functions/date_and_time/timevalue.md

@@ -4,9 +4,42 @@ outline: deep
 lang: en-US
 ---
 
-# TIMEVALUE
+# TIMEVALUE function
 
-::: warning
+## Overview
-**Note:** This draft page is under construction 🚧
+TIMEVALUE is a function of the Date and Time category that converts a time stored as text to a [serial number](/features/serial-numbers.md) corresponding to a time value. The serial number represents time as a decimal fraction of a 24-hour day (e.g., 0.5 represents 12:00:00 noon).
-The TIMEVALUE function is implemented and available in IronCalc.
+
-:::
+## Usage
+### Syntax
+**TIMEVALUE(<span title="Text" style="color:#1E88E5">time_text</span>) => <span title="Number" style="color:#1E88E5">timevalue</span>**
+
+### Argument descriptions
+* *time_text* ([text](/features/value-types#strings), required). A text string that represents a time in a known format. The text must represent a time between 00:00:00 and 23:59:59.
+
+### Additional guidance
+* Date information in the *time_text* argument is ignored. TIMEVALUE processes only the time portion.
+* The function can handle various time formats, including both 12-hour and 24-hour formats, as well as text that includes both date and time information.
+
+### Returned value
+TIMEVALUE returns a [number](/features/value-types#numbers) that represents the time as a [serial number](/features/serial-numbers.md). The serial number is a decimal fraction of a 24-hour day, where:
+* 0.0 represents 00:00:00 (midnight)
+* 0.5 represents 12:00:00 (midday)
+* 0.99999... represents 23:59:59 (just before midnight)
+
+### Error conditions
+* In common with many other IronCalc functions, TIMEVALUE propagates errors that are found in its argument.
+* If no argument, or more than one argument, is supplied, then TIMEVALUE returns the [`#ERROR!`](/features/error-types.md#error) error.
+* If the value of the *time_text* argument is not (or cannot be converted to) a [text](/features/value-types#strings) value, then TIMEVALUE returns the [`#VALUE!`](/features/error-types.md#value) error.
+* If the *time_text* argument represents a time outside the valid range, then TIMEVALUE returns the [`#VALUE!`](/features/error-types.md#value) error.
+* If the *time_text* argument cannot be recognized as a valid time format, then TIMEVALUE returns the [`#VALUE!`](/features/error-types.md#value) error.
+<!--@include: ../markdown-snippets/error-type-details.txt-->
+
+<!--
+## Examples
+[See some examples in IronCalc](https://app.ironcalc.com/?example=timevalue).
+-->
+
+## Links
+* See also IronCalc's [DATEVALUE](/functions/date_and_time/datevalue.md) function for converting date text to serial numbers.
+* Visit Microsoft Excel's [TIMEVALUE function](https://support.microsoft.com/en-us/office/timevalue-function-0b615c12-33d8-4431-bf3d-f3eb6d186645) page.
+* Both [Google Sheets](https://support.google.com/docs/answer/3267350) and [LibreOffice Calc](https://wiki.documentfoundation.org/Documentation/Calc_Functions/TIMEVALUE) provide versions of the TIMEVALUE function.