4.9.1. Temporal instant types

An introduction to temporal instant types, including descriptions of creation functions, clocks, and truncation.

4.9.1.1. An overview of temporal instant type creation

Each function bears the same name as the type, and construct the type they correspond to in one of four ways:

  • Capturing the current time
  • Composing the components of the type
  • Parsing a string representation of the temporal value
  • Selecting and composing components from another temporal value by

    • either combining temporal values (such as combining a Date with a Time to create a DateTime), or
    • selecting parts from a temporal value (such as selecting the Date from a DateTime); the extractors — groups of components which can be selected — are:

      • date — contains all components for a Date (conceptually year, month and day).
      • time — contains all components for a Time (hour, minute, second, and sub-seconds; namely millisecond, microsecond and nanosecond). If the type being created and the type from which the time component is being selected both contain timezone (and a timezone is not explicitly specified) the timezone is also selected.
      • datetime — selects all components, and is useful for overriding specific components. Analogously to time, if the type being created and the type from which the time component is being selected both contain timezone (and a timezone is not explicitly specified) the timezone is also selected.
    • In effect, this allows for the conversion between different temporal types, and allowing for 'missing' components to be specified.
Table 4.90. Temporal instant type creation functions
Function Date Time LocalTime DateTime LocalDateTime

Getting the current value

X

X

X

X

X

Creating a calendar-based (Year-Month-Day) value

X

   

X

X

Creating a week-based (Year-Week-Day) value

X

   

X

X

Creating a quarter-based (Year-Quarter-Day) value

X

   

X

X

Creating an ordinal (Year-Day) value

X

   

X

X

Creating a value from time components

 

X

X

   

Creating a value from other temporal values using extractors (i.e. converting between different types)

X

X

X

X

X

Creating a value from a string

X

X

X

X

X

Creating a value from a timestamp

     

X

 

All the temporal instant types — including those that do not contain time zone information support such as Date, LocalTime and DateTime — allow for a time zone to specified for the functions that retrieve the current instant. This allows for the retrieval of the current instant in the specified time zone.

4.9.1.2. Controlling which clock to use

The functions which create temporal instant values based on the current instant use the statement clock as default. However, there are three different clocks available for more fine-grained control:

  • transaction: The same instant is produced for each invocation within the same transaction. A different time may be produced for different transactions.
  • statement: The same instant is produced for each invocation within the same statement. A different time may be produced for different statements within the same transaction.
  • realtime: The instant produced will be the live clock of the system.

The following table lists the different sub-functions for specifying the clock to be used when creating the current temporal instant value:

4.9.1.3. Truncating temporal values

A temporal instant value can be created by truncating another temporal instant value at the nearest preceding point in time at a specified component boundary (namely, a truncation unit). A temporal instant value created in this way will have all components which are less significant than the specified truncation unit set to their default values.

It is possible to supplement the truncated value by providing a map containing components which are less significant than the truncation unit. This will have the effect of overriding the default values which would otherwise have been set for these less significant components.

The following truncation units are supported:

  • millennium: Select the temporal instant corresponding to the millenium of the given instant.
  • century: Select the temporal instant corresponding to the century of the given instant.
  • decade: Select the temporal instant corresponding to the decade of the given instant.
  • year: Select the temporal instant corresponding to the year of the given instant.
  • weekYear: Select the temporal instant corresponding to the first day of the first week of the week-year of the given instant.
  • quarter: Select the temporal instant corresponding to the quarter of the year of the given instant.
  • month: Select the temporal instant corresponding to the month of the given instant.
  • week: Select the temporal instant corresponding to the week of the given instant.
  • day: Select the temporal instant corresponding to the month of the given instant.
  • hour: Select the temporal instant corresponding to the hour of the given instant.
  • minute: Select the temporal instant corresponding to the minute of the given instant.
  • second: Select the temporal instant corresponding to the second of the given instant.
  • millisecond: Select the temporal instant corresponding to the millisecond of the given instant.
  • microsecond: Select the temporal instant corresponding to the microsecond of the given instant.

The following table lists the supported truncation units and the corresponding sub-functions:

Truncation unit Date Time LocalTime DateTime LocalDateTime

millennium

date.truncate('millennium', input)

   

datetime.truncate('millennium', input)

localdatetime.truncate('millennium', input)

century

date.truncate('century', input)

   

datetime.truncate('century', input)

localdatetime.truncate('century', input)

decade

date.truncate('decade', input)

   

datetime.truncate('decade', input)

localdatetime.truncate('decade', input)

year

date.truncate('year', input)

   

datetime.truncate('year', input)

localdatetime.truncate('year', input)

weekYear

date.truncate('weekYear', input)

   

datetime.truncate('weekYear', input)

localdatetime.truncate('weekYear', input)

quarter

date.truncate('quarter', input)

   

datetime.truncate('quarter', input)

localdatetime.truncate('quarter', input)

month

date.truncate('month', input)

   

datetime.truncate('month', input)

localdatetime.truncate('month', input)

week

date.truncate('week', input)

   

datetime.truncate('week', input)

localdatetime.truncate('week', input)

day

date.truncate('day', input)

time.truncate('day', input)

localtime.truncate('day', input)

datetime.truncate('day', input)

localdatetime.truncate('day', input)

hour

 

time.truncate('hour', input)

localtime.truncate('hour', input)

datetime.truncate('hour', input)

localdatetime.truncate('hour',input)

minute

 

time.truncate('minute', input)

localtime.truncate('minute', input)

datetime.truncate('minute', input)

localdatetime.truncate('minute', input)

second

 

time.truncate('second', input)

localtime.truncate('second', input)

datetime.truncate('second', input)

localdatetime.truncate('second', input)

millisecond

 

time.truncate('millisecond', input)

localtime.truncate('millisecond', input)

datetime.truncate('millisecond', input)

localdatetime.truncate('millisecond', input)

microsecond

 

time.truncate('microsecond', input)

localtime.truncate('microsecond', input)

datetime.truncate('microsecond', input)

localdatetime.truncate('microsecond', input)