# DateTime module

The DateTime module contains functions for working with datetime values. Most of the functions are declared as self functions: by opening the DateTime module in a script step, you can use dot notation to call the functions on datetime values.

```typescript
// Example 1: access the datetime module without opening it
return DateTime.addYears(now(), 1);
```

```typescript
// Example 2: open the DateTime module and use it.
open DateTime;
return now().addYears(1);
```

<details>

<summary>Advanced: Time zones</summary>

All datetime values contain a *Time Zone Offset*. This ensures that values created on different devices "mean" the same absolute time.

</details>

## Creating and Parsing datetime values

### createDate

**Signature:** createDate(year: number, month: number, day: number) -> datetime

Returns a datetime value with the given year, month and day. The time portion of the datetime will be set to 00:00:00. The offset will be set to the local time zone.

### createDateAndTime

**Signature:** createDateAndTime(year: number, month: number, day: number, hour: number, minute: number, second: number) -> datetime

Returns a datetime value with the given year, month, day, hour (in 24-hour time), minute and second.

the offset will be set to the local time zone.&#x20;

### isValidDate

**Signature:** isValidDate(input: any) -> boolean

Returns true if the input value can be converted to a valid date. Arguments that returns true can be used with the `Date` function to create a datetime value.

```typescript
return isValidDate("2012-04-05") // returns true
```

## Modifying datetime values

### addSeconds

**Signature:** addSeconds(**self** input: datetime, seconds: number) -> datetime

Returns a new date obtained by adding the specified number of seconds to the input date. You can pass a negative number to subtract seconds.

### addMinutes

**Signature:** addMinutes(**self** input: datetime, minutes: number) -> datetime

Returns a new date obtained by adding the specified number of minutes to the input date. You can pass a negative number to subtract minutes.

### addHours

**Signature:** addHours(**self** input: datetime, hours: number) -> datetime

Returns a new date obtained by adding the specified number of hours to the input date. You can pass a negative number to subtract hours.

### addDays

**Signature:** addDays(**self** input: datetime, days: number) -> datetime

Returns a new date obtained by adding the specified number of days to the input date. You can pass a negative number to subtract days.

### addMonths

**Signature:** addMonths(**self** input: datetime, months: number) -> datetime

Returns a new date obtained by adding the specified number of months to the input date. You can pass a negative number to subtract months.

### addYears

**Signature:** addYears(self input: datetime, months: number) -> datetime

Returns a new date obtained by adding the specified number of years to the input date. You can pass a negative number to subtract years.

### setTime

**Signature:**  setTime(date: datetime, hour: number, minute: number, second: number) -> datetime

Returns a new date obtained from the given date with the hours, minutes and second set by the provided arguments.

```typescript
open DateTime;
let d = Date("2021-03-11 00:00:00");

return format(setTime(d,12,10,55), "G") // returns "03/11/2021 12:10:55"
```

### toUtc

**Signature:** toUtc(**self** date: datetime) -> datetime

\`Returns the given date converted to UTC.

```typescript
open DateTime;
let easternTime = Date("2021-03-11 05:00:00 -05:00");

return format(easternTime.toUTC(), "g") // returns "03/11/2021 10:00"
```

### toLocal

**Signature:**  toLocal(**self** date: datetime) -> datetime

Returns the given date converted to local time.

```typescript
open DateTime;
let easternTime = Date("2021-03-11 05:00:00 -05:00");

return format(easternTime.toLocal(), "g") // returns "03/11/2021 11:00" in GMT+1
```

## Retrieving data from datetime values

### getSecond

**Signature:** getSecond(**self** input: datetime) -> number

Returns the second component of the datetime value.

### getMinute

**Signature:** getMinute(**self** input: datetime) -> number

Returns the minute component of the datetime value.

### getHour

**Signature:** getHour(**self** input: datetime) -> number

Returns the hour component of the datetime value, in 24-hour time.

### getDayOfMonth

**Signature:** getDayOfMonth(**self** input: datetime) -> number

Returns the day component of the datetime value.

### getDayOfWeek

**Signature:** getDayOfWeek(**self** input: datetime) -> text

Returns the day of week for the given datetime value. Return values are English-laguage text values "monday", "tuesday" etc.&#x20;

### getMonth

**Signature:** getMonth(**self** input: datetime) -> number

Returns the month component of the datetime value.

### getYear

**Signature:** getYear(**self** input: datetime) -> number

Returns the year component of the datetime value.

### getTimeOffset

**Signature:** getTimeZoneOffset(**self** input: datetime) -> number

Returns the offset from UTC of the datetime value.

## Comparing dates

### differenceInDays

**Signature:** differenceInDays(fromDate: datetime, toDate: datetime) -> number

Returns the difference in days between two dates.&#x20;

```typescript
let yesterDay = Now().AddDays(-1);
let today = Now();

return Datime.differenceInDays(today, yesterDay) // will return 1
```

```typescript
let easternTime = Date("2021-03-11 00:00:00 -05:00");
let pacificTime = Date("2021-03-10 21:00:00 -08:00");

return DateTime.differenceInDays(easternTime, pacificTime)
// will return 0 due to being the same time but in different timezones
```

### differenceInSeconds

**Signature:** differenceInSeconds(fromDate: datetime, toDate: datetime) -> number

Returns the difference in seconds between two dates.&#x20;

```typescript
open DateTime;

let aMinuteAgo = Now().addMinutes(-1);
let currentTime = Now();

return differenceInSeconds(currentTime, aMinuteAgo) // will return -60
```

```typescript
let easternTime = Date("2021-03-11 00:00:00 -05:00");
let pacificTime = Date("2021-03-10 21:00:30 -08:00");

return DateTime.differenceInSeconds(easternTime, pacificTime) 
// will return 30 due to being in different time zones.
```

## HHMM text

### createHHMMText

**Signature:** createHHMMText(input: datetime) -> text

Returns a text representation of datetime value hours and minutes

```typescript
let d = DateTime.CreateDateAndTime(2023, 03, 09, 22, 34, 22)

return DateTime.CreateHHMMText(d) // returns "22:34"
```

### getMinuteFromHHMMText

**Signature:** getMinuteFromHHMMText(input: text) -> number

Returns the number of minutes from a HHMM formatted text.

```typescript
return DateTime.getMinuteFromHHMMText("22:34") // returns 34
```

### getHourFromHHMMText

**Signature:** getHourFromHHMMText(input: text) -> number

Returns the number of hours from a HHMM formatted text.

```typescript
return DateTime.getHourFromHHMMText("22:34") // returns 22
```


---

# 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://docs.novacura.com/flow-connect/reference/reference/flowscript/walkthrough/datetime-module.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.