> For the complete documentation index, see [llms.txt](https://formulapro.shadebridge.com/formula-pro/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://formulapro.shadebridge.com/formula-pro/formula-pro-custom-functions/date-time.md).

# 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"`