> ## Documentation Index
> Fetch the complete documentation index at: https://docs.farmtrace.co.za/llms.txt
> Use this file to discover all available pages before exploring further.

# Date functions

> Create dates and calculate calendar parts, periods, weeks, quarters, years, and workdays.

A Date contains a calendar day without a time of day. Date literals use `#yyyy-MM-dd#`, for example `#2026-08-31#`.

## `AdjustMonth`

Moves a date by a whole number of calendar months.

* **Syntax:** `AdjustMonth(date, months)`
* **Requires:** a Date and a whole Numeric month count. Negative counts move backward.
* **Returns:** Date.
* **Best for:** monthly renewals, due dates, and reporting cycles.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
AdjustMonth([Start Date], 3)
```

When the target month is shorter, the day is clamped to that month's last valid day.

## `AdjustYear`

Moves a date by a whole number of calendar years.

* **Syntax:** `AdjustYear(date, years)`
* **Requires:** a Date and a whole Numeric year count. Negative counts move backward.
* **Returns:** Date.
* **Best for:** anniversaries, annual renewals, and age windows.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
AdjustYear([Certification Date], 1)
```

Moving February 29 into a non-leap year uses the last valid day of February.

## `Date`

Creates a calendar date from numeric components.

* **Syntax:** `Date(year, month, day)`
* **Requires:** three whole Numeric values that form a valid date.
* **Returns:** Date.
* **Best for:** fixed dates and dates assembled from separate imported fields.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Date(2026, 8, 31)
```

## `Day`

Returns the day of the month.

* **Syntax:** `Day(date)`
* **Requires:** a Date.
* **Returns:** Numeric from `1` through `31`.
* **Best for:** monthly grouping and calendar labels.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Day([Inspection Date])
```

## `DayOfWeek`

Returns the weekday number, starting with Sunday.

* **Syntax:** `DayOfWeek(date)`
* **Requires:** a Date.
* **Returns:** Numeric: Sunday is `0`, Monday `1`, through Saturday `6`.
* **Best for:** weekday rules and weekend checks.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
In(DayOfWeek([Inspection Date]), 0, 6)
```

## `DayOfYear`

Returns how many days a date follows January 1.

* **Syntax:** `DayOfYear(date)`
* **Requires:** a Date.
* **Returns:** zero-based Numeric: January 1 is `0`.
* **Best for:** seasonal grouping and day-of-year comparisons.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
DayOfYear([Harvest Date])
```

## `FirstDayOfMonth`

Returns the first date in the same month.

* **Syntax:** `FirstDayOfMonth(date)`
* **Requires:** a Date.
* **Returns:** Date.
* **Best for:** monthly report windows and grouping.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
FirstDayOfMonth([Invoice Date])
```

## `FirstDayOfPeriod`

Finds the first day of a repeating fixed-length period anchored to a reference date.

* **Syntax:** `FirstDayOfPeriod(date, duration, referenceDate)`
* **Requires:** two Dates and a positive Duration. Fractional days are discarded toward zero, so the Duration must contain at least one full day.
* **Returns:** Date.
* **Best for:** custom 7-day, 14-day, or other fixed reporting cycles.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
FirstDayOfPeriod([Inspection Date], Days(14), #2026-01-05#)
```

## `FirstDayOfQuarter`

Returns the first date in the same calendar quarter.

* **Syntax:** `FirstDayOfQuarter(date)`
* **Requires:** a Date.
* **Returns:** Date.
* **Best for:** quarterly reports and targets.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
FirstDayOfQuarter([Invoice Date])
```

## `FirstDayOfWeek`

Returns the Sunday at the start of the date's week.

* **Syntax:** `FirstDayOfWeek(date)`
* **Requires:** a Date.
* **Returns:** Date.
* **Best for:** Sunday-to-Saturday reporting windows.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
FirstDayOfWeek([Inspection Date])
```

## `FirstDayOfYear`

Returns January 1 in the same year.

* **Syntax:** `FirstDayOfYear(date)`
* **Requires:** a Date.
* **Returns:** Date.
* **Best for:** year-to-date reporting.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
FirstDayOfYear([Invoice Date])
```

## `ISOWeek`

Returns the ISO 8601 week number.

* **Syntax:** `ISOWeek(date)`
* **Requires:** a Date.
* **Returns:** Numeric week number using Monday as the first weekday and the ISO first-week rule.
* **Best for:** internationally consistent weekly reporting.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
ISOWeek([Inspection Date])
```

## `IsLeapDay`

Checks whether a date is February 29.

* **Syntax:** `IsLeapDay(date)`
* **Requires:** a Date.
* **Returns:** Boolean.
* **Best for:** anniversary and renewal edge cases.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
IsLeapDay([Start Date])
```

## `IsLeapYear`

Checks whether a date's year, or a supplied year number, is a leap year.

* **Syntax:** `IsLeapYear(dateOrYear)`
* **Requires:** a Date or whole Numeric year.
* **Returns:** Boolean.
* **Best for:** February and annual-calendar rules.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
IsLeapYear([Inspection Date])
IsLeapYear(2028)
```

## `LastDayOfMonth`

Returns the last date in the same month.

* **Syntax:** `LastDayOfMonth(date)`
* **Requires:** a Date.
* **Returns:** Date.
* **Best for:** monthly deadlines and report ranges.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
LastDayOfMonth([Invoice Date])
```

## `LastDayOfPeriod`

Finds the last day of a repeating fixed-length period anchored to a reference date.

* **Syntax:** `LastDayOfPeriod(date, duration, referenceDate)`
* **Requires:** two Dates and a positive Duration. Fractional days are discarded toward zero, so the Duration must contain at least one full day.
* **Returns:** Date.
* **Best for:** the closing date of custom reporting cycles.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
LastDayOfPeriod([Inspection Date], Days(14), #2026-01-05#)
```

## `LastDayOfQuarter`

Returns the last date in the same calendar quarter.

* **Syntax:** `LastDayOfQuarter(date)`
* **Requires:** a Date.
* **Returns:** Date.
* **Best for:** quarterly deadlines and report ranges.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
LastDayOfQuarter([Invoice Date])
```

## `LastDayOfWeek`

Returns the Saturday at the end of the date's week.

* **Syntax:** `LastDayOfWeek(date)`
* **Requires:** a Date.
* **Returns:** Date.
* **Best for:** Sunday-to-Saturday reporting windows.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
LastDayOfWeek([Inspection Date])
```

## `LastDayOfYear`

Returns December 31 in the same year.

* **Syntax:** `LastDayOfYear(date)`
* **Requires:** a Date.
* **Returns:** Date.
* **Best for:** annual report and validity windows.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
LastDayOfYear([Invoice Date])
```

## `Month`

Returns the calendar month number.

* **Syntax:** `Month(date)`
* **Requires:** a Date.
* **Returns:** Numeric from `1` for January through `12` for December.
* **Best for:** monthly grouping and conditional rules.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Month([Harvest Date])
```

## `MonthsBetween`

Counts month boundaries crossed from one date to another.

* **Syntax:** `MonthsBetween(startDate, endDate)`
* **Requires:** two Dates.
* **Returns:** signed Numeric boundary count.
* **Best for:** calendar-month reporting buckets rather than exact elapsed time.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
MonthsBetween([Start Date], [End Date])
```

Day numbers do not affect the result; January 31 to February 1 crosses one month boundary.

## `NextDayOfWeek`

Returns the next requested weekday strictly after a date.

* **Syntax:** `NextDayOfWeek(date, weekday)`
* **Requires:** a Date and a whole Numeric weekday from `0` (Sunday) through `6` (Saturday).
* **Returns:** Date.
* **Best for:** next collection, meeting, or processing day rules.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
NextDayOfWeek([Order Date], 1)
```

If the supplied date is already that weekday, the result is seven days later.

## `PrevDayOfWeek`

Returns the requested weekday strictly before a date.

* **Syntax:** `PrevDayOfWeek(date, weekday)`
* **Requires:** a Date and a whole Numeric weekday from `0` (Sunday) through `6` (Saturday).
* **Returns:** Date.
* **Best for:** previous cut-off or reporting-day rules.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
PrevDayOfWeek([Order Date], 5)
```

If the supplied date is already that weekday, the result is seven days earlier.

## `Quarter`

Returns the calendar quarter number.

* **Syntax:** `Quarter(date)`
* **Requires:** a Date.
* **Returns:** Numeric from `1` through `4`.
* **Best for:** quarterly grouping and targets.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Quarter([Invoice Date])
```

## `QuartersBetween`

Counts quarter boundaries crossed from one date to another.

* **Syntax:** `QuartersBetween(startDate, endDate)`
* **Requires:** two Dates.
* **Returns:** signed Numeric boundary count.
* **Best for:** calendar-quarter reporting buckets.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
QuartersBetween([Start Date], [End Date])
```

## `Today`

Returns the current date in the active formula timezone.

* **Syntax:** `Today()`
* **Requires:** the evaluation clock and timezone supplied by Dsync.
* **Returns:** Date.
* **Best for:** due, overdue, age, and validity checks.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
[Due Date] < Today()
```

Every `Today()` call in one evaluation observes the same date.

## `Week`

Returns the week number using a locale-based or explicitly selected first weekday.

* **Syntax:** `Week(date[, firstWeekday])`
* **Requires:** a Date and optional whole Numeric weekday from `0` (Sunday) through `6` (Saturday). Without it, the active locale chooses the first weekday.
* **Returns:** Numeric week number.
* **Best for:** locally configured weekly reports.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Week([Inspection Date])
Week([Inspection Date], 1)
```

Use `ISOWeek` when reports must follow ISO 8601 everywhere.

## `Workday`

Moves a date by a number of working days.

* **Syntax:** `Workday(date, amount[, weekend])`
* **Requires:** a Date; a whole Numeric amount or a Duration; and optional weekend Text. Fractional days in a Duration are discarded toward zero. Negative amounts move backward.
* **Returns:** Date.
* **Best for:** business deadlines and service schedules.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Workday([Submitted Date], 5)
Workday([Submitted Date], 5, "67")
```

The default weekend is Saturday and Sunday. Custom weekend text can contain one or two weekday digits (`1` Monday through `7` Sunday), or a seven-character Monday-to-Sunday mask where `1` marks a weekend day.

## `Workdays`

Counts working days between two dates, including both endpoints.

* **Syntax:** `Workdays(startDate, endDate[, weekend])`
* **Requires:** two Dates and optional weekend Text in the same format as `Workday`.
* **Returns:** Duration containing the signed number of working days.
* **Best for:** turnaround time and service-level reporting.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
ToDays(Workdays([Opened Date], [Closed Date]))
```

The result is negative when the end date is before the start date.

## `Year`

Returns the calendar year.

* **Syntax:** `Year(date)`
* **Requires:** a Date.
* **Returns:** Numeric year.
* **Best for:** annual grouping and labels.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Year([Harvest Date])
```

## `YearsBetween`

Counts year boundaries crossed from one date to another.

* **Syntax:** `YearsBetween(startDate, endDate)`
* **Requires:** two Dates.
* **Returns:** signed Numeric boundary count.
* **Best for:** calendar-year buckets rather than exact anniversaries.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
YearsBetween([Start Date], [End Date])
```

Month and day do not affect this boundary count.

<Tip>
  Use `AdjustMonth` and `AdjustYear` for calendar movement. Use `Days` and Duration arithmetic when you mean a fixed elapsed amount.
</Tip>