/
Package: datetime

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:

Symbol

Meaning

Presentation

Examples

Symbol

Meaning

Presentation

Examples

G

era

text

AD

C

century of era (>=0)

number       

20

Y

year of era (>=0)

year         

1996

x

weekyear

year         

1996

w

week of weekyear

number       

27

e

day of week

number       

2

E

day of week

text         

Tuesday; Tue

y

year

year         

1996

D

day of year

number       

189

M

month of year

month         

July; Jul; 07

d                      

day of month 

number       

10

a

halfday of day

text         

PM

K

hour of halfday (0~11)

number       

0

h

clockhour of halfday (1~12)

number       

12

H

hour of day (0~23) 

number       

0

k

clockhour of day (1~24)

number       

24

m

minute of hour

number       

30

s

second of minute

number       

55

S

fraction of second

millis       

978

z

time zone

text         

Pacific Standard Time; PST

Z

time zone offset/id

zone         

-0800; -08:00; America/Los_Angeles

'

escape for text

delimiter



''

single quote

literal       

'

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.

API

Methods

now

function now() as datetime

Current date and time.

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

createWithZone

function createWithZone(year as int, month as int, day as int, zone as string) as datetime

Creates a new date at start of day at a specific timezone. Timezone strings can be found here.

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

fromString

function fromString(input as string) as datetime

Converts from ISO8061 string to datetime.

interval

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

Creates a new date interval.

Since: 1.5.0

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.

workingDaysBetween

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

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

Since: 1.5.0

weeksBetween

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

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

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

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

millisecond

function millisecond(input as datetime) as int

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

Since: 1.6.0

second

function second(input as datetime) as int

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

minute

function minute(input as datetime) as int

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

hour

function hour(input as datetime) as int

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

day

function day(input as datetime) as int

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

month

function month(input as datetime) as int

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

year

function year(input as datetime) as int

Extracts the year.

plusMilliseconds

function plusMilliseconds(input as datetime, increment as int) as datetime

Adds a number of milliseconds.

Since 1.6.0

plusSeconds

function plusSeconds(input as datetime, increment as int) as datetime

Adds a number of seconds.

plusMinutes

function plusMinutes(input as datetime, increment as int) as datetime

Adds a number of minutes.

plusHours

function plusHours(input as datetime, increment as int) as datetime

Adds a number of hours.

plusDays

function plusDays(input as datetime, increment as int) as datetime

Adds a number of days.

plusWeeks

function plusWeeks(input as datetime, increment as int) as datetime

Adds a number of weeks.

plusMonths

function plusMonths(input as datetime, increment as int) as datetime

Adds a number of months.

plusYears

function plusYears(input as datetime, increment as int) as datetime

Adds a number of years.

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

dayOfWeek

function dayOfWeek(input as datetime) as datetime

Extracts the day of week. Range 1-7.

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.

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

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

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

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

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

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

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

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

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

weekAsInterval

function dayAsInterval(input as datetime) as datetimeinterval

Returns the week where the input date is in.

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

Since: 1.5.0

workingWeekAsInterval

function dayAsInterval(input as datetime) as datetimeinterval

Returns the working week (monday to friday) where the input date is in.

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

Since: 1.5.0

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

yearAsInterval

function yearAsInterval(input as datetime) as datetimeinterval

Returns the year where the input date is in.

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

Since: 1.5.0

min

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

Returns the minimum datetime (oldest).

Since: 1.5.0

max

function max(firstDate, secondDate) as datetime

Returns the maximum datetime (newest).

Since: 1.5.0

overlap

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

Returns the overlapping interval.

Since: 1.5.0

gap

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

Returns the gap interval.

Since: 1.5.0

overlaps

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

Checks if two intervals overlap.

Since: 1.5.0

abuts

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

Checks if two intervals abut (touch without intersecting).

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

isAfter

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

Checks if first interval is after the second interval.

Since: 1.5.0

contains

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

Checks if first interval contains the second interval.

Since: 1.5.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

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

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

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

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

workingDaysIn

function workingDaysIn(interval as datetimeinterval) as int

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

weeksIn

function weeksIn(interval as datetimeinterval) as int

Returns the number of whole weeks in interval. The last week of the interval 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

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

sequenceDays

function sequenceDays(start as datetime, count as int) as collection of datetime

Returns a collection of datetime filled with the number of requested days starting with the start date.

Since: 1.5.0

sequenceWorkingDays

function sequenceWorkingDays(start as datetime, count as int) as collection of datetime

Returns a collection of datetime filled with the number of requested working days starting with the start date.

When creating a sequence of working days the actual count of the result may be less than count. Count is considered to be the number of days.

Since: 1.5.0

sequenceWeeks

function sequenceWeeks(start as datetime, count as int) as collection of datetime

Returns a collection of datetime filled with the number of requested weeks starting with the start date.

Since: 1.5.0

sequenceMonths

function sequenceMonths(start as datetime, count as int) as collection of datetime

Returns a collection of datetime filled with the number of requested months starting with the start date.

Since: 1.5.0

sequenceYears

function sequenceYears(start as datetime, count as int) as collection of datetime

Returns a collection of datetime filled with the number of requested years starting with the start date.

Since: 1.5.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

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

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

formatTime

function formatTime(in as datetime) as string

Formats the input datetime extracting only 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

formatDateTime

function formatDateTime(in as datetime) as string

Formats the input datetime extracting the date and the time.

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

isWeekend

function isWeekend(in as datetime) as bool

isLeapYear

function isLeapYear(in as datetime) as bool