Package: datetime

Date and time handling APIs.

Unless otherwise specified, in this article, when referring to a "date" we are referring to a date with the time at the start of day.

Format

The underlying implementation of date-time formatting is based on JodaTime version 2.3.

All ASCII letters are reserved as pattern letters, which are defined as follows:

The count of pattern letters determine the format.

1. Text: If the number of pattern letters is 4 or more, the full form is used; otherwise a short or abbreviated form is used if available.
2. Number: The minimum number of digits. Shorter numbers are zero-padded to this amount. When parsing, any number of digits are accepted.
3. Year: Numeric presentation for year and weekyear fields are handled specially. For example, if the count of 'y' is 2, the year will be displayed as the zero-based year of the century, which is two digits.
4. Month: 3 or over, use text, otherwise use number.
5. Millis: The exact number of fractional digits. If more millisecond digits are available then specified the number will be truncated, if there are fewer than specified then the number will be zero-padded to the right. When parsing, only the exact number of digits are accepted.
6. Zone: 'Z' outputs offset without a colon, 'ZZ' outputs the offset with a colon, 'ZZZ' or more outputs the zone id.
7. Zone names: Time zone names ('z') cannot be parsed.

Any characters in the pattern that are not in the ranges of ['a'..'z'] and ['A'..'Z'] will be treated as quoted text. For instance, characters like ':', '.', ' ', '#' and '?' will appear in the resulting time text even they are not embraced within single quotes.

Methods

abuts

function abuts(firstInterval as datetimeinterval, secondInterval as datetimeinterval) as bool

Checks if two intervals abut (touch without intersecting).

Since: 1.5.0

atEndOfDay

function atEndOfDay(input as datetime) as datetime

Returns the date with the time at the end of day, that is: 23 hour 59 minute 59 second 999 milisecond.

atStartOfDay

function atStartOfDay(input as datetime) as datetime

Returns the date with the time at the start of day, that is: 0 hour 0 minute 0 second 0 milisecond.

atTime

function atTime(input as datetime, hour as int, minute as int, second as int) as datetime

Returns the date with the time at the specified hour, minute and second.

atTimeMilliseconds

function atTimeMilliseconds(input as datetime, hour as int, minute as int, second as int, millisecond as int) as datetime

Returns the date with the time at the specified hour, minute, second and millisecond.

Since 1.6.0

coalesce

function coalesce(value1 as datetime, value2 as datetime) as datetime

Returns the first non-null value. value2 cannot be null.

Since 1.5.1

contains

function contains(firstInterval as datetimeinterval, secondInterval as datetimeinterval) as bool

Checks if first interval contains the second interval.

Since: 1.5.0

create

function create(year as int, month as int, day as int) as datetime

Creates a new date at start of day.

Since: 1.5.0

createWithTime

function createWithTime(year as int, month as int, day as int, hour as int, minute as int, second as int) as datetime

Creates a new date at the specified time.

Since: 1.5.0

createWithTimeAndZone

function createWithTimeAndZone(year as int, month as int, day as int, hour as int, minute as int, second as int, zone as string) as datetime

Creates a new date at the specified time at a specific timezone. Timezone strings can be found here.

Since: 1.5.0

createWithTimeMilliseconds

function createWithTimeMilliseconds(year as int, month as int, day as int, hour as int, minute as int, second as int, millisecond as int) as datetime

Creates a new date at the specified time with milliseconds.

Since: 1.6.0

createWithTimeMillisecondsAndZone

function createWithTimeMillisecondsAndZone(year as int, month as int, day as int, hour as int, minute as int, second as int, millisecond as int, zone as string) as datetime

Creates a new date at the specified time at a specific timezone. Timezone strings can be found here.

Since: 1.6.0

day

function day(input as datetime) as int

Extracts the day (of month). Range 1-[28,29,30,31] depending on month.

dayAsInterval

function dayAsInterval(input as datetime) as datetimeinterval

Returns the input date as a time interval.

Example for input 02.04.2018 the result will be (02.04.2018 00:00:00.000, 02.04.2018 23:59:59.999).

Since: 1.5.0

dayOfMonth

function dayOfMonth(input as datetime) as datetime

Extracts the day of month. Range 1-[28,29,30,31] depending on month.

dayOfYear

function dayOfYear(input as datetime) as datetime

Extracts the day of year. Range 1-[365, 366] depending on year.

daysBetween

function daysBetween(start as datetime, stop as datetime) as int

Returns the number of days between start and stop. The stop date is not included in the result.

Example interval: [2018-01-01, 2018-01-31) = 30 days.

daysIn

function daysIn(interval as datetimeinterval) as int

Returns the number of whole days in interval. The last day of the interval is not included in the result.

Since: 1.5.0

firstDateOfMonth

function firstDateOfMonth(input as datetime) as datetime

Returns the first date of the month where the input date is in.

Since: 1.5.0

firstDateOfWeek

function firstDateOfWeek(input as datetime) as datetime

Returns the first date (monday) of the week where the input date is in.

Since: 1.5.0

format

function format(in as datetime, pattern as string) as string

Formats the input datetime according to the pattern. The pattern is in the format specified in the previous chapter.

Since 1.5.1

formatDateTime

function formatDateTime(in as datetime) as string

Formats the input datetime extracting the date and the time.

Since 1.5.1

formatDate

function formatDate(in as datetime) as string

Formats the input datetime extracting only the date.

Since 1.5.1

formatDayOfWeekNameDate

function formatDayOfWeekNameDate(in as datetime, lang as string) as string

Formats the input datetime extracting day of week name followed by the date using the specified language (ex: "ro", "en", "de", "fr").

Since 1.5.1

formatTime

function formatTime(in as datetime) as string

Formats the input datetime extracting only the time.

Since 1.5.1

formatWithLang

function formatWithLang(in as datetime, lang as string, pattern as string) as string

Formats the input

datetime according to the pattern using the specified language (ex: "ro", "en", "de", "fr"). The pattern is in the format specified in the previous chapter.

Since 1.5.1

fromString

function fromString(input as string) as datetime

Converts from ISO8061 string to datetime.

gap

function gap(firstInterval as datetimeinterval, secondInterval as datetimeinterval) as datetimeinterval

Returns the gap interval.

Since: 1.5.0

hour

function hour(input as datetime) as int

Extracts the hour (of day). Range 0-23.

hourAsInterval

function hourAsInterval(input as datetime) as datetimeinterval

Returns the hour the input date is in.

Example for input 02.04.2018 12:30 the result will be (02.04.2018 12:00:00.000, 02.04.2018 12:59:59.999).

Since: 1.5.1

hoursBetween

function hoursBetween(start as datetime, stop as datetime) as int

Returns the number of whole hours between start and stop. The stop date is not included in the result.

Since: 1.5.0

hoursIn

function hoursIn(interval as datetimeinterval) as int

Returns the number of whole hours in interval. The last hour of the interval is not included in the result.

Since: 1.5.0

interval

function interval(start as datetime, end as datetime) as datetimeinterval

Creates a new date interval.

Since: 1.5.0

isAfter

function isAfter(firstInterval as datetimeinterval, secondInterval as datetimeinterval) as bool

Checks if first interval is after the second interval.

Since: 1.5.0

isBefore

function isBefore(firstInterval as datetimeinterval, secondInterval as datetimeinterval) as bool

Checks if first interval is before the second interval.

Since: 1.5.0

isLeapYear

function isLeapYear(in as datetime) as bool

isWeekend

function isWeekend(in as datetime) as bool

lastDateOfMonth

function lastDateOfMonth(input as datetime) as datetime

Returns the last date of the month where the input date is in.

Since: 1.5.0

lastDateOfWeek

function lastDateOfWeek(input as datetime) as datetime

Returns the last date (sunday) of the week where the input date is in.

Since: 1.5.0

lastDayOfMonth

function lastDayOfMonth(input as datetime) as datetime

Returns the last day of the month where the input date is in. Range 28-31.

Since: 1.5.0

lastWorkingDateOfWeek

function lastWorkingDateOfWeek(input as datetime) as datetime

Returns the last date (friday) of the week where the input date is in.

Since: 1.5.0

max

function max(firstDate, secondDate) as datetime

Returns the maximum datetime (newest).

Since: 1.5.0

millisecond

function millisecond(input as datetime) as int

Extracts the millisecond (of second). Range 0-999.

Since: 1.6.0

millisecondsIn

function millisecondsIn(interval as datetimeinterval) as int

Returns the number of whole milliseconds in interval. The last millisecond of the interval is not included in the result.

Since: 1.5.2

min

function min(fistDate as datetime, secondDate as datetime) as datetime

Returns the minimum datetime (oldest).

Since: 1.5.0

minute

function minute(input as datetime) as int

Extracts the minute (of hour). Range 0-59.

minuteAsInterval

function minuteAsInterval(input as datetime) as datetimeinterval

Returns the hour the input date is in.

Example for input 02.04.2018 12:30:15 the result will be (02.04.2018 12:30:00.000, 02.04.2018 12:30:59.999).

Since: 1.5.1

minutesBetween

function minutesBetween(start as datetime, stop as datetime) as int

Returns the number of whole minutes between start and stop. The stop date is not included in the result.

Since: 1.5.0

minutesIn

function minutesIn(interval as datetimeinterval) as int

Returns the number of whole minutes in interval. The last minute of the interval is not included in the result.

Since: 1.5.0

month

function month(input as datetime) as int

Extracts the month (of year). Range 1-12.

monthAsInterval

function monthAsInterval(input as datetime) as datetimeinterval

Returns the month where the input date is in.

Example for input 02.04.2018 the result will be (01.04.2018 00:00:00.000, 30.04.2018 23:59:59.999).

Since: 1.5.0

monthsBetween

function monthsBetween(start as datetime, stop as datetime) as int

Returns the number of full months between start and stop. The stop date is not included in the result.

Since: 1.5.0

monthsIn

function monthsIn(interval as datetimeinterval) as int

Returns the number of whole months in interval. The last month of the interval is not included in the result.

Since: 1.5.0

next

function next(in as datetime, dayOfWeek as int) as datetime

Returns the next occurrence of the specified day of the week after the input datetime.

Example: next(DateTime.now, DateTime.MONDAY)

Since 1.5.1

now

function now() as datetime

Returns the current date and time.

parse

function parse(input as string, pattern as string) as datetime

Parses the input string according to the specified pattern into a datetime.

Since 1.5.1

previous

function previous(in as datetime, dayOfWeek as int) as datetime

Returns the previous occurrence of the specified day of the week before the input datetime.

Example: previous(DateTime.now, DateTime.MONDAY)

Since 1.5.1

second

function second(input as datetime) as int

Extracts the second (of minute). Range 0-59.

secondAsInterval

function secondAsInterval(input as datetime) as datetimeinterval

Returns the second the input date is in.

Example for input 02.04.2018 12:30:15.500 the result will be (02.04.2018 12:30:15.000, 02.04.2018 12:30:15.999).

Since: 1.5.1

secondsBetween

function secondsBetween(start as datetime, stop as datetime) as int

Returns the number of whole seconds between start and stop. The stop date is not included in the result.

Since: 1.5.0

secondsIn

function secondsIn(interval as datetimeinterval) as int

Returns the number of whole seconds in interval. The last second of the interval is not included in the result.

Since: 1.5.0

startOfDay

function startOfDay(input as datetime) as datetime

Returns the date with the time at the start of day, that is: 0 hour 0 minute 0 second 0 millisecond.

startOfMonth

function startOfMonth(input as datetime) as datetime

Returns the first date of the month where the input date is in.

Since: 1.5.0

startOfWeek

function startOfWeek(input as datetime) as datetime

Returns the first date (monday) of the week where the input date is in.

Since: 1.5.0

time

function time(input as datetime) as datetime

Returns the time part of the input date.

Since: 1.5.0

toDateTime

function toDateTime(year as int, month as int, day as int, hour as int, minute as int, second as int, millisecond as int) as datetime

Creates a new datetime.

Since: 1.6.0

toString

function toString(input as datetime, pattern as string) as string

Converts a datetime to a string using the specified pattern.

Since 1.5.1

truncateToDay

function truncateToDay(input as datetime) as datetime

Truncates the input datetime to the start of day.

Since: 1.5.0

truncateToHour

function truncateToHour(input as datetime) as datetime

Truncates the input datetime to the start of hour.

Since: 1.5.0

truncateToMinute

function truncateToMinute(input as datetime) as datetime

Truncates the input datetime to the start of minute.

Since: 1.5.0

truncateToMonth

function truncateToMonth(input as datetime) as datetime

Truncates the input datetime to the start of month.

Since: 1.5.0

truncateToSecond

function truncateToSecond(input as datetime) as datetime

Truncates the input datetime to the start of second.

Since: 1.5.0

truncateToWeek

function truncateToWeek(input as datetime) as datetime

Truncates the input datetime to the start of week.

Since: 1.5.0

truncateToYear

function truncateToYear(input as datetime) as datetime

Truncates the input datetime to the start of year.

Since: 1.5.0

year

function year(input as datetime) as int

Extracts the year.

yearsBetween

function yearsBetween(start as datetime, stop as datetime) as int

Returns the number of full years between start and stop. The stop date is not included in the result.

Since: 1.5.0

yearsIn

function yearsIn(interval as datetimeinterval) as int

Returns the number of whole years in interval. The last year of the interval is not included in the result.

Since: 1.5.0