Package: datetime

Owned by Former user (Deleted)
Last updated: Mar 19, 2022 by Vlad Untu

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

Creates a new date at the specified time.

Since: 1.5.0

createWithTimeAndZone

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

Since: 1.5.0

createWithTimeMilliseconds

Creates a new date at the specified time with milliseconds.

Since: 1.6.0

createWithTimeMillisecondsAndZone

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

Since: 1.6.0

fromString

Converts from ISO8061 string to datetime.

interval

Creates a new date interval.

Since: 1.5.0

daysBetween

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

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

Since: 1.5.0

weeksBetween

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

Since: 1.5.0

monthsBetween

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

Since: 1.5.0

yearsBetween

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

Since: 1.5.0

millisecond

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

Since: 1.6.0

second

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

minute

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

hour

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

day

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

month

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

year

Extracts the year.

plusMilliseconds

Adds a number of milliseconds.

Since 1.6.0

plusSeconds

Adds a number of seconds.

plusMinutes

Adds a number of minutes.

plusHours

Adds a number of hours.

plusDays

Adds a number of days.

plusWeeks

Adds a number of weeks.

plusMonths

Adds a number of months.

plusYears

Adds a number of years.

atEndOfDay

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

atStartOfDay

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

atTime

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

atTimeMilliseconds

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

Since 1.6.0

dayOfWeek

Extracts the day of week. Range 1-7.

dayOfMonth

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

dayOfYear

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

firstDateOfWeek

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

Since: 1.5.0

lastDateOfWeek

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

Since: 1.5.0

lastWorkingDateOfWeek

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

Since: 1.5.0

lastDayOfMonth

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

Since: 1.5.0

firstDateOfMonth

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

Since: 1.5.0

lastDateOfMonth

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

Since: 1.5.0

minuteAsInterval

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

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

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

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

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

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

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

Returns the minimum datetime (oldest).

Since: 1.5.0

max

Returns the maximum datetime (newest).

Since: 1.5.0

overlap

Returns the overlapping interval.

Since: 1.5.0

gap

Returns the gap interval.

Since: 1.5.0

overlaps

Checks if two intervals overlap.

Since: 1.5.0

abuts

Checks if two intervals abut (touch without intersecting).

Since: 1.5.0

isBefore

Checks if first interval is before the second interval.

Since: 1.5.0

isAfter

Checks if first interval is after the second interval.

Since: 1.5.0

contains

Checks if first interval contains the second interval.

Since: 1.5.0

millisecondsIn

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

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

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

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

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

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

weeksIn

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

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

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

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

Since: 1.5.0

sequenceWorkingDays

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

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

Since: 1.5.0

sequenceMonths

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

Since: 1.5.0

sequenceYears

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

Since: 1.5.0

coalesce

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

Since 1.5.1

format

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

Since 1.5.1

formatWithLang

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

Formats the input datetime extracting only the time.

Since 1.5.1

formatDate

Formats the input datetime extracting only the date.

Since 1.5.1

formatDateTime

Formats the input datetime extracting the date and the time.

Since 1.5.1

formatDayOfWeekNameDate

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

isLeapYear