# DateTime module

### The DateTime module

The DateTime module contains additional functions for creating and consuming date and time values. 

Please note that the DateTime module is currently only available in Script Steps.

Note, also, that all the functions in the DateTime module work on textual values as well as date values explicitly created using the Date function; for instance, calling `DateTime.GetYear("2018-01-01")` returns the same result as calling `DateTime.GetYear(Date("2018-01-01"))`.

#### IsValidDate(candidate)

Returns a Boolean value indicating whether the candidate value is a valid date (or date and time)

```fsharp
return DateTime.IsValidDate("hello"); 
// Return false; "hello" is not a valid date.
```

#### CreateDate(year, month, dayOfMonth)

Creates a date value with the given year, month and day of the month. The timestamp of the created value will be 00:00:00. Please note that the month and day of the month are 1-based.

```fsharp
return DateTime.CreateDate(2018, 03, 23);
// Returns a date value representing the 23rd of March 2018
```

#### CreateDateAndTime(year, month, dayOfMonth, hour, minute, second)

Creates a date value with the given year, month, day of the month, hour, minute and second. Please note that the month and day of the month are 1-based and that the `hour` argument is in 24h time.

```fsharp
return DateTime.CreateDateAndTime(2018, 03, 23, 11, 03, 01);
// Returns a date value representing the 23rd of Match, three minutes
// and one second past eleven.
```

#### GetYear(dateValue)

Gets the year of a date.

```fsharp
let d = DateTime.CreateDateAndTime(2018, 03, 23, 11, 03, 01);

return DateTime.GetYear(d);
// Returns 2018.
```

#### GetMonth(dateValue)

Gets the month of a date.

```fsharp
let d = DateTime.CreateDateAndTime(2018, 03, 23, 11, 03, 01);

return DateTime.GetMonth(d);
// Returns 3 (the month of March).
```

#### GetDayOfMonth(dateValue)

Gets the day of the month of a date.

```fsharp
let d = DateTime.CreateDateAndTime(2018, 03, 23, 11, 03, 01);

return DateTime.GetDayOfMonth(d);
// Returns 23.
```

#### GetHour(dateValue)

Gets the hour component of a date.

```fsharp
let d = DateTime.CreateDateAndTime(2018, 03, 23, 11, 03, 01);

return DateTime.GetHour(d);
// Returns 11.
```

#### GetMinute(dateValue)

Gets the minute of a valid date.

```fsharp
let d = DateTime.CreateDateAndTime(2018, 03, 23, 11, 03, 01);

return DateTime.GetMinute(d);
// Returns 3.
```

#### GetSecond(dateValue)

Gets the second of a date.

```fsharp
let d = DateTime.CreateDateAndTime(2018, 03, 23, 11, 03, 01);

return DateTime.GetYear(d);
// Returns 1.
```

#### DifferenceInDays(fromDate, toDate)

Returns a numeric value representing the (possibly fractional) number of days between the `fromDate` and `toDate` arguments. If toDate is earlier than fromDate, the resulting value will be negative. 

```fsharp
let fromDate = DateTime.CreateDateAndTime(2018, 03, 23, 11, 03, 01);

let toDate = DateTime.CreateDateAndTime(2018, 03, 24, 12, 15, 00);


return DateTime.DifferenceInDays(fromDate, toDate);
// Returns 1.049988
```

#### DifferenceInSeconds(fromDate, toDate)

Returns a numeric value representing the number of seconds between the `fromDate` and `toDate` arguments. If toDate is earlier than fromDate, the resulting value will be negative.

```fsharp
let fromDate = DateTime.CreateDateAndTime(2018, 03, 23, 11, 03, 01);

let toDate = DateTime.CreateDateAndTime(2018, 03, 24, 12, 15, 00);


return DateTime.DifferenceInSeconds(fromDate, toDate);
// Returns 90719
```

#### SetTime(dateValue, hours, minutes, seconds)

Returns a new date value with the same year, month and day as `dateValue`, but with a new time as specified in the `hours,` `minutes` and `seconds` arguments.

```fsharp
let original = DateTime.CreateDate(2018, 12, 24);
return DateTime.SetTime(original, 14, 25, 00);

// Returns a date representing the 24th of December 2018, 14:25:00
```

#### AddYears(dateValue, years)

Returns a new date value with the 'year' component offset by the number of years specified in the `years` argument. (To subtract, specify a negative number.)

```fsharp
let original = DateTime.CreateDate(2018, 12, 24);
return DateTime.AddYears(original, 1);

// Returns a date representing the 24th of December 2019.
```

#### AddMonths(dateValue, months)

Returns a new date value with the 'month' component offset by the number of months specified in the `months` argument. (To subtract, specify a negative number.)

```fsharp
let original = DateTime.CreateDate(2018, 12, 24);

return DateTime.AddMonths(original, 1);

// Returns a date representing the 24th of January 2019
```

#### AddDays(dateValue, days)

Returns a new date value with the 'day' component offset by the number of days specified in the `days` argument. (To subtract, specify a negative number.)

```fsharp
let original = DateTime.CreateDate(2018, 12, 24);
return DateTime.AddDays(original, 1);

// Returns a date representing the 25th of December 2018
```

*Note: for values which are known to be dates (i.e. created using the `Date` or `Now` functions), it is possible to use the addition (+) and subtraction (-) operators as shorthand for the AddDays function.*

```fsharp
let original = DateTime.CreateDate(2018, 12, 24);
return original + 1;

// Returns a date representing the 25th of December 2019.
```

#### AddHours(dateValue, hours)

Returns a new date value with the 'hour' component offset by the number of hours specified in the `hours` argument. (To subtract, specify a negative number.)

```fsharp
let original = DateTime.CreateDate(2018, 12, 24);
return DateTime.AddHours(original, -1);

// Returns a date representing the 23rd of December 2018, 11 PM.
```

#### AddMinutes(dateValue, minutes)

Returns a new date value with the 'minute' component offset by the number of minutes specified in the `minutes` argument. (To subtract, specify a negative number.)

```fsharp
let original = DateTime.CreateDate(2018, 12, 24);
return DateTime.AddMinutes(original, -1);

// Returns a date representing the 23rd of December 2018, 11:59:00 PM.
```

#### AddSeconds(dateValue, seconds)

Returns a new date value with the 'second' component offset by the number of seconds specified in the `seconds` argument. (To subtract, specify a negative number.)

```fsharp
let original = DateTime.CreateDate(2018, 12, 24);
return DateTime.AddSeconds(original, -1);

// Returns a date representing the 23rd of December 2018, 11:59:59 PM.
```

#### CreateHHMMText(dateValue)

Converts a valid date value into a textual value containing the hour and minute of the day in the HH:MM format. This is the format supported by the [Time input](https://help.novacuraflow.com/development/flow-studio/applications/workflow/user-step/time-input) element.

```fsharp
let d = DateTime.CreateDateAndTime(2018, 03, 23, 11, 03, 01);

return DateTime.CreateHHMMText(d);
// Returns 11:03 as a text value.
```

#### GetHourFromHHMMText(text)

Gets the hour component from a text in the HH:MM format (as created by the [Time input](https://help.novacuraflow.com/development/flow-studio/applications/workflow/user-step/time-input) element).

```fsharp
return DateTime.GetHourFromHHMMText("13:45");
// Returns 13
```

#### GetMinuteFromHHMMText(text)

Gets the minute component from a text in the HH:MM format (as created by the [Time input](https://help.novacuraflow.com/development/flow-studio/applications/workflow/user-step/time-input) element).

```fsharp
return DateTime.GetMinuteFromHHMMText("13:45");
// Returns 45
```