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