diff --git a/base/src/test/test_fn_datevalue_timevalue.rs b/base/src/test/test_fn_datevalue_timevalue.rs new file mode 100644 index 0000000..039fc8e --- /dev/null +++ b/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!"); +} + + diff --git a/docs/src/functions/date-and-time.md b/docs/src/functions/date-and-time.md index f3dde9d..f8a1b99 100644 --- a/docs/src/functions/date-and-time.md +++ b/docs/src/functions/date-and-time.md @@ -12,7 +12,7 @@ All Date and Time functions are already supported in IronCalc. | ---------------- | ---------------------------------------------- | ------------- | | DATE | | – | | DATEDIF | | – | -| DATEVALUE | | – | +| DATEVALUE | | [DATEVALUE](date_and_time/datevalue) | | DAY | | [DAY](date_and_time/day) | | DAYS | | – | | DAYS360 | | – | @@ -27,7 +27,7 @@ All Date and Time functions are already supported in IronCalc. | NOW | | – | | SECOND | | – | | TIME | | – | -| TIMEVALUE | | – | +| TIMEVALUE | | [TIMEVALUE](date_and_time/timevalue) | | TODAY | | – | | WEEKDAY | | – | | WEEKNUM | | – | diff --git a/docs/src/functions/date_and_time/datevalue.md b/docs/src/functions/date_and_time/datevalue.md index da62d37..9c78168 100644 --- a/docs/src/functions/date_and_time/datevalue.md +++ b/docs/src/functions/date_and_time/datevalue.md @@ -4,8 +4,41 @@ outline: deep lang: en-US --- -# DATEVALUE +# DATEVALUE 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 +## Overview +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(date_text) => datevalue** + +### 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. + + + + +## 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. \ No newline at end of file diff --git a/docs/src/functions/date_and_time/timevalue.md b/docs/src/functions/date_and_time/timevalue.md index d408a2b..49b99c4 100644 --- a/docs/src/functions/date_and_time/timevalue.md +++ b/docs/src/functions/date_and_time/timevalue.md @@ -4,9 +4,42 @@ outline: deep lang: en-US --- -# TIMEVALUE +# TIMEVALUE function -::: warning -**Note:** This draft page is under construction 🚧 -The TIMEVALUE function is implemented and available in IronCalc. -::: \ No newline at end of file +## Overview +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). + +## Usage +### Syntax +**TIMEVALUE(time_text) => timevalue** + +### 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. + + + + +## 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. \ No newline at end of file