sirtimbly/IronCalc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
* 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
This commit is contained in:
Elsa Minsut
2025-11-07 04:56:14 +07:00
committed by GitHub
parent f30f6864e2
commit 480a2d1769
4 changed files with 101 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
base/src/test/test_fn_datevalue_timevalue.rs Normal file
View File

@@ -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!");
}

4
docs/src/functions/date-and-time.md
View File

@@ -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" /> | – |

41
docs/src/functions/date_and_time/datevalue.md
View File

@@ -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).
:::
## 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(<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.

43
docs/src/functions/date_and_time/timevalue.md
View File

@@ -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.
:::
## 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(<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.