---
title: "Date and time"
description: "TapHome script date and time: current time with NOW, build dates with DATETIME, add days or hours, durations with TIMESPAN, time zone offset and Unix time."
url: "https://taphome.com/en/docs/script/date-and-time/"
language: en
lastmod: 2026-11-06
generator: hugo
ai:
  topics: ["date-time","timespan","timezone","scripting-language"]
  questions: ["How to work with date and time in TapHome scripts?","How do I create a DateTime object in TapHome?","How to get the current date and time in TapHome script?","How do I represent a duration with TIMESPAN?","How to add or subtract time from a DateTime with DATETIMEADD?","How do I get the local timezone offset in TapHome?","What properties does a DateTime object have?","How do I check in a script whether today is a weekend?","How do I convert a Unix timestamp to a date in a TapHome script?","How do I calculate the number of minutes between two dates?"]
---

# Date and time

TapHome script date and time functions — NOW, DATETIME, DATETIMEADD, TIMESPAN and LOCALTIMEZONE — and the properties of datetime and timespan values.

Last updated: 2026-11-06

Date and time functions create `datetime` values (a point in time) and `timespan` values (a duration). They work in every script — smart rules, notifications, Modbus and Packet parser — and use the time zone of the control unit. All functions on this page need Core 2022.2 or newer.

## NOW

`NOW` returns the current date and time of the control unit as a `datetime` value — local time by default, UTC with `NOW(Utc)`.

```text
NOW()
NOW(kind)
```

| Name | Type | Description |
|---|---|---|
| `kind` | `DateTimeKind`, optional | `Local` (default) or `Utc`. `NOW(DateTimeKind.Utc)` is the same as `NOW(Utc)`. |

**Remarks** — A property cannot be read directly from a function call: `NOW().HOUR` is rejected when you save the script. Store the value in a variable first.

**Example**

```taphome
VAR now := NOW();
now.HOUR;
# Result: the current hour, 0 to 23
```

**See also** — [DATETIME](https://taphome.com/en/docs/script/date-and-time/#datetime), [Properties of datetime values](https://taphome.com/en/docs/script/date-and-time/#datetime-properties).

## DATETIME

`DATETIME` creates a `datetime` value from its parts, from text or from a number of milliseconds; called without arguments it returns 1.1.0001 00:00, not the current time — use [NOW](https://taphome.com/en/docs/script/date-and-time/#now) for that.

```text
DATETIME(year, month, day [, hour [, minute [, second [, millisecond [, kind]]]]])
DATETIME(text [, format])
DATETIME(text, kind)
DATETIME(milliseconds [, kind])
DATETIME()
```

| Name | Type | Description |
|---|---|---|
| `year`, `month`, `day` | number | Required together. Omitted time parts are 0. |
| `hour` … `millisecond` | number, optional | Time of day. |
| `kind` | `DateTimeKind`, optional | `Local` (default) or `Utc`. |
| `text` | string | Date and time as text. |
| `format` | string, optional | .NET format of `text`, for example `"dd.MM.yyyy HH:mm"`. |
| `milliseconds` | number | Milliseconds since 1.1.0001 — the scale of the `TICKS` property, not Unix time. |

**Remarks**

- Text without a format is read according to the language settings of the control unit. Use ISO 8601 (`"2026-01-15T08:30:00"`) or pass a format so the result does not depend on them.
- Text with an offset or `Z` (`"2026-01-15T08:30:00Z"`) is kept as a UTC value. With `kind` set to `Utc`, text without zone information is read as UTC.
- For Unix time, set the [UNIXTIME property](https://taphome.com/en/docs/script/date-and-time/#datetime-properties).

**Example**

```taphome
# date from parts: year, month, day, time
VAR start := DATETIME(2026, 1, 15, 8, 30, 0);
# date from ISO 8601 text and from text with a format
VAR iso := DATETIME("2026-01-15T08:30:00");
VAR custom := DATETIME("15.01.2026 08:30", "dd.MM.yyyy HH:mm");
# date from parts, marked as UTC
VAR utc := DATETIME(2026, 1, 15, 8, 30, 0, 0, DateTimeKind.Utc);
# minute of the parsed date
custom.MINUTE;
# Result: 30
```

## DATETIMEADD

`DATETIMEADD` returns a new `datetime` moved by the given number of years, months, days, hours, minutes, seconds and milliseconds; negative numbers move it back.

```text
DATETIMEADD(datetime, years [, months [, days [, hours [, minutes [, seconds [, milliseconds]]]]]])
```

**Remarks** — The original value does not change. Adding a month to 31 January gives the last day of February. To add an interval, you can also use `+` with a [timespan](https://taphome.com/en/docs/script/date-and-time/#timespan) or with a number of milliseconds.

**Example**

```taphome
# current time of the control unit
VAR now := NOW();
# one day forward, two hours back
VAR tomorrow := DATETIMEADD(now, 0, 0, 1);
VAR twoHoursAgo := DATETIMEADD(now, 0, 0, 0, -2);
# one month after 31 January
VAR endOfFebruary := DATETIMEADD(DATETIME(2026, 1, 31), 0, 1);
# day of the result
endOfFebruary.DAY;
# Result: 28
```

## TIMESPAN

`TIMESPAN` creates a `timespan` value — a duration — either from milliseconds or from days, hours, minutes, seconds and milliseconds.

```text
TIMESPAN(milliseconds)
TIMESPAN(days, hours, minutes, seconds, milliseconds)
```

**Properties** (read-only)

| Property | Meaning |
|---|---|
| `DAYS`, `HOURS`, `MINUTES`, `SECONDS`, `MILLISECONDS` | One component of the duration (`HOURS` is 0 – 23). |
| `TOTALDAYS`, `TOTALHOURS`, `TOTALMINUTES`, `TOTALSECONDS`, `TOTALMILLISECONDS` | The whole duration in that unit, with a fraction. |

**Remarks**

- Only the 1- and 5-argument forms exist; 2 to 4 arguments stop the script.
- `timespan ± timespan` gives a `timespan`, `datetime ± timespan` a `datetime`.
- Subtracting two `datetime` values is not defined. For the time between two dates, subtract their `TICKS` (milliseconds).
- Declaring a variable with the `timespan` type keyword needs Core 2023.2 or newer.

**Example**

```taphome
VAR t := TIMESPAN(1, 2, 3, 4, 0);
t.TOTALSECONDS;
# Result: 93784
```

```taphome
VAR start := DATETIME(2026, 1, 15, 8, 0, 0);
VAR stop := DATETIME(2026, 1, 15, 9, 30, 0);
(stop.TICKS - start.TICKS) / 60000;
# Result: 90 (minutes)
```

**Errors** — *TIMESPAN Unsupported number of parameters*; *Operator '-' not defined for 'DateTime' and 'DateTime'*.

## LOCALTIMEZONE

`LOCALTIMEZONE` returns the current offset of the control unit's time zone from UTC in milliseconds, daylight saving time included.

```text
LOCALTIMEZONE()
```

**Example**

```taphome
LOCALTIMEZONE() / 3600000;
# Result: 1 in Central European winter time, 2 in summer time
```

## Properties of datetime values

A `datetime` value has these properties. Read them from a variable, not from a function call.

| Property | Read | Write | Note |
|---|---|---|---|
| `TICKS` | ✓ | ✓ | Milliseconds since 1.1.0001. |
| `YEAR`, `MONTH`, `DAY` | ✓ | ✓ | Writing checks the range (`MONTH` 1 – 12, `DAY` 1 – last day of the month). |
| `HOUR`, `MINUTE`, `SECOND`, `MILLISECOND` | ✓ | ✓ | Ranges 0 – 23, 0 – 59, 0 – 59, 0 – 999. |
| `DAYOFWEEK` | ✓ | | `DayOfWeek` value (`Monday` … `Sunday`). |
| `DAYOFYEAR` | ✓ | | 1 – 366. |
| `KIND` | ✓ | ✓ | `DateTimeKind`: `Local`, `Utc` or `Unspecified`. |
| `UTCDATETIME`, `LOCALDATETIME` | ✓ | | The same moment converted with the time zone of the control unit. |
| `UNIXTIME` | ✓ | ✓ | Seconds since 1.1.1970 UTC. Writing it stores a UTC value. |

**Remarks**

- Outside a function argument an enum value is written with its type: `DayOfWeek.Saturday`. A bare `Saturday` is an unknown variable.
- `<`, `>` and `=` compare two `datetime` values as moments in time, so values of different `KIND` compare correctly.
- Writing a value outside the range stops the script, for example *Value must between 0-23*.
- Without a format, [TOSTRING](https://taphome.com/en/docs/script/data-type-conversions/#tostring) prints a `datetime` as `yyyy/MM/dd hh:mm:ss.fff` — a 12-hour clock without AM or PM. Pass a format such as `"yyyy-MM-dd HH:mm"`.

**Example — no action at the weekend**

```taphome
# current time of the control unit
VAR now := NOW();
# on Saturday and Sunday return 0
IF now.DAYOFWEEK = DayOfWeek.Saturday OR now.DAYOFWEEK = DayOfWeek.Sunday
    RETURN(0);
END
# on other days return 1
1;
```

**Example — date from a Unix timestamp**

```taphome
datetime d;
d.UNIXTIME := 1767225600;
d.YEAR;
# Result: 2026 (1 January 2026, 00:00 UTC)
```

**See also** — [Format strings](https://taphome.com/en/docs/script/data-type-conversions/#format-strings), [Data types](https://taphome.com/en/docs/script/data-types/).