# Date & Time Functions

Formula Pro custom functions for date arithmetic, formatting, and time calculations.

***

## ADD\_DAYS

Adds a specified number of days to a date. Returns a date string in `YYYY-MM-DD` format.

**Syntax:** `ADD_DAYS(date, days)`

| Parameter | Type                    | Description                                      |
| --------- | ----------------------- | ------------------------------------------------ |
| date      | Date, string, or number | The starting date                                |
| days      | number                  | Number of days to add (use negative to subtract) |

**Example:**

```
ADD_DAYS("2025-03-09", 14)
```

**Result:** `"2025-03-23"`

***

## SUBTRACT\_DAYS

Subtracts a specified number of days from a date. Returns `YYYY-MM-DD`.

**Syntax:** `SUBTRACT_DAYS(date, days)`

**Example:**

```
SUBTRACT_DAYS("2025-03-23", 14)
```

**Result:** `"2025-03-09"`

***

## DATE\_ARITHMETIC

Adds or subtracts days from a date. Same as ADD\_DAYS/SUBTRACT\_DAYS; use negative `days` to subtract.

**Syntax:** `DATE_ARITHMETIC(date, days)`

**Example:**

```
DATE_ARITHMETIC("2025-01-15", -7)
```

**Result:** `"2025-01-08"`

***

## ADD\_MINUTES

Adds minutes to a datetime string. Accepts `YYYY-MM-DD HH:mm:ss` or `YYYY-MM-DD`. Returns ISO 8601 UTC string.

**Syntax:** `ADD_MINUTES(date, minutes)`

**Example:**

```
ADD_MINUTES("2025-06-27 07:00:00", 90)
```

**Result:** `"2025-06-27T08:30:00.000Z"` (or equivalent ISO string)

***

## SUBTRACT\_MINUTES

Subtracts minutes from a datetime string.

**Syntax:** `SUBTRACT_MINUTES(date, minutes)`

***

## DATE\_MIN / MIN\_DATE

Returns the earliest date from multiple date arguments. Accepts date strings, numbers (timestamps), or timeline strings (`YYYY-MM-DD+YYYY-MM-DD`).

**Syntax:** `DATE_MIN(date1, date2, ...)` or `MIN_DATE(...)`

**Example:**

```
DATE_MIN("2025-03-01", "2025-03-15", "2025-02-20")
```

**Result:** `"2025-02-20"`

***

## DATE\_MAX / MAX\_DATE

Returns the latest date from multiple date arguments.

**Syntax:** `DATE_MAX(date1, date2, ...)` or `MAX_DATE(...)`

**Example:**

```
DATE_MAX("2025-03-01", "2025-03-15", "2025-02-20")
```

**Result:** `"2025-03-15"`

***

## WORKDAYS

Calculates the number of working days (Mon–Fri) between two dates.

**Syntax:** `WORKDAYS(toDate, fromDate, [allowNegative])`

| Parameter     | Description                                                                                  |
| ------------- | -------------------------------------------------------------------------------------------- |
| toDate        | End date (YYYY-MM-DD)                                                                        |
| fromDate      | Start date (YYYY-MM-DD)                                                                      |
| allowNegative | Optional. "TRUE" or true to allow negative results; default is false (returns 0 if negative) |

**Example:**

```
WORKDAYS("2025-03-14", "2025-03-09")
```

**Result:** `4` (Mon 9th to Fri 14th = 4 weekdays)

***

## FORMAT\_DATE

Formats a date using Moment.js format tokens. Default format is `"MMM DD, YYYY"`.

**Syntax:** `FORMAT_DATE(dateInput, [formatString])`

**Common format tokens:** `YYYY` (year), `MM` (month), `DD` (day), `HH` (hour), `mm` (minute), `ss` (second)

**Example:**

```
FORMAT_DATE("2025-03-09", "MMM DD, YYYY")
```

**Result:** `"Mar 09, 2025"`

**Example:**

```
FORMAT_DATE("2025-03-09", "YYYY-MM-DD")
```

**Result:** `"2025-03-09"`

***

## TIMEVALUE

Converts a time string to a decimal fraction of a day (Excel-compatible). Supports `HH:MM`, `HH:MM:SS`, and AM/PM formats.

**Syntax:** `TIMEVALUE(time_text)`

**Example:**

```
TIMEVALUE("09:00")
```

**Result:** `0.375` (9 AM = 9/24 of a day)

***

## HOURS\_DIFF

Calculates the difference between two time strings in `HH:MM` format. Supports hours beyond 24.

**Syntax:** `HOURS_DIFF(time1, time2)`

**Example:**

```
HOURS_DIFF("18:00", "09:00")
```

**Result:** `"09:00"` (9 hours difference)

**Example:**

```
HOURS_DIFF("09:00", "18:00")
```

**Result:** `"-09:00"`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://formulapro.shadebridge.com/formula-pro/formula-pro-custom-functions/date-time.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.