A multiplatform Kotlin library for working with date and time.
See Using in your projects for the instructions how to setup a dependency in your project.
There are a few guiding principles in the design of kotlinx-datetime
. First of all, it is pragmatic, focused
on the most common problems developers face every day (pun intended) when working with dates and times. It is not
all-encompassing and lacks some domain-specific utilities that special-purpose applications might need.
We chose convenience over generality, so the API surface this library provides is as minimal as possible
to meet the use-cases.
The library puts a clear boundary between physical time of an instant and a local, time-zone dependent civil time, consisting of components such as year, month, etc that people use when talking about time. We intentionally avoid entities in the library that mix both together and could be misused. However, there are convenience operations that take, for example, a physical instant and perform a calendar-based adjustment (such as adding a month); all such operation explicitly take a time-zone information as parameter to clearly state that their result depends on the civil time-zone rules which are subject to change at any time.
The library is based on the ISO 8601 international standard, other ways to represent dates and times are out of its scope. Internationalization (such as locale-specific month and day names) is out the scope, too.
The library provides the basic set of types for working with date and time:
Instant
to represent a moment on the UTC-SLS time scale;Clock
to obtain the current instant;LocalDateTime
to represent date and time components without a reference to the particular time zone;LocalDate
to represent the components of date only;TimeZone
andZoneOffset
provide time zone information to convert betweenInstant
andLocalDateTime
;Month
andDayOfWeek
enums;DateTimePeriod
to represent a difference between two instants decomposed into date and time units;DatePeriod
is a subclass ofDateTimePeriod
with zero time components, it represents a difference between two LocalDate values decomposed into date units.DateTimeUnit
provides a set of predefined date and time units to use in arithmetic operations onInstant
andLocalDate
.
Here is some basic advice on how to choose which of the date-carrying types to use in what cases:
-
Use
Instant
to represent a timestamp of the event that had already happened in the past (like a timestamp of a log entry) or will definitely happen in a well-defined instant of time in the future not far away from now (like an order confirmation deadline in 1 hour from now). -
Use
LocalDateTime
to represent a time of the event that is scheduled to happen in the far future at a certain local time (like a scheduled meeting in a few months from now). You'll have to keep track of theTimeZone
of the scheduled event separately. Try to avoid converting future events toInstant
in advance, because time-zone rules might change unexpectedly in the future. In this blog post, you can read more about why it's not always a good idea to useInstant
everywhere.Also, use
LocalDateTime
to decode anInstant
to its local date-time components for display and UIs. -
Use
LocalDate
to represent a date of the event that does not have a specific time associated with it (like a birth date).
With the above types you can get the following operations done.
The current moment of time can be captured with the Instant
type.
To obtain an Instant
corresponding to the current moment of time,
use now()
function of the Clock
interface:
val clock: Clock = ...
val currentMoment = clock.now()
An instance of Clock
can be injected through the function/class parameters,
or you can use its default implementation Clock.System
that represents the system clock:
val currentMoment = Clock.System.now()
Instant
is just a counter of high resolution time intervals since the beginning of time scale.
To get human readable components from an Instant
value you need to convert it to LocalDateTime
type
that represents date and time components without a reference to the particular time zone.
The TimeZone
type provides the rules to convert instants from and to date/time components.
val currentMoment: Instant = Clock.System.now()
val datetimeInUtc: LocalDateTime = currentMoment.toLocalDateTime(TimeZone.UTC)
val datetimeInSystemZone: LocalDateTime = currentMoment.toLocalDateTime(TimeZone.currentSystemDefault())
LocalDateTime
instance exposes familiar components of the Gregorian calendar:
year
, month
, dayOfMonth
, hour
, and so on up to nanosecond
.
The property dayOfWeek
shows what weekday that date is,
and dayOfYear
shows the day number since the beginning of a year.
Additional time zones can be acquired by their string identifier with the TimeZone.of(id: String)
function.
val tzBerlin = TimeZone.of("Europe/Berlin")
val datetimeInBerlin = currentMoment.toLocalDateTime(tzBerlin)
LocalDateTime
instance can be constructed from individual components:
val kotlinReleaseDateTime = LocalDateTime(2016, 2, 15, 16, 57, 0, 0)
An instant can be obtained from LocalDateTime
by interpreting it as a time moment
in a particular TimeZone
:
val kotlinReleaseInstant = kotlinReleaseDateTime.toInstant(TimeZone.of("UTC 3"))
LocalDate
type represents local date without time. You can obtain it from Instant
by converting it to LocalDateTime
and taking its date
property.
val now: Instant = Clock.System.now()
val today: LocalDate = now.toLocalDateTime(TimeZone.currentSystemDefault()).date
// or more short
val today: LocalDate = Clock.System.todayAt(TimeZone.currentSystemDefault())
Note, that today's date really depends on the time zone in which you're observing the current moment.
LocalDate
can be constructed from three components, year, month, and day:
val knownDate = LocalDate(2020, 2, 21)
An Instant
can be converted to a number of milliseconds since the Unix/POSIX epoch with the toEpochMilliseconds()
function.
To convert back, use Instant.fromEpochMilliseconds(Long)
companion object function.
Currently, Instant
, LocalDateTime
, and LocalDate
only support ISO-8601 format.
The toString()
function is used to convert the value to a string in that format, and
the parse
function in companion object is used to parse a string representation back.
val instantNow = Clock.System.now()
instantNow.toString() // returns something like 2015-12-31T12:30:00Z
val instantBefore = Instant.parse("2010-06-01T22:19:44.475Z")
Alternatively, String.to...()
extension functions can be used instead of parse
,
where it feels more convenient:
LocalDateTime
uses the similar format, but without Z
UTC time zone designator in the end.
LocalDate
uses format with just year, month, and date components, e.g. 2010-06-01
.
"2010-06-01T22:19:44.475Z".toInstant()
"2010-06-01T22:19:44".toLocalDateTime()
"2010-06-01".toLocalDate()
val now = Clock.System.now()
val instantInThePast: Instant = Instant.parse("2020-01-01T00:00:00Z")
val durationSinceThen: Duration = now - instantInThePast
val equidistantInstantInTheFuture: Instant = now durationSinceThen
Duration
is a type from the experimental kotlin.time
package in the Kotlin standard library.
This type holds the amount of time that can be represented in different time units: from nanoseconds to 24H days.
To get the calendar difference between two instants you can use Instant.periodUntil(Instant, TimeZone)
function.
val period: DateTimePeriod = instantInThePast.periodUntil(Clock.System.now(), TimeZone.UTC)
DateTimePeriod
represents a difference between two particular moments as a sum of calendar components,
like "2 years, 3 months, 10 days, and 22 hours".
The difference can be calculated as an integer amount of specified date or time units:
val diffInMonths = instantInThePast.until(Clock.System.now(), DateTimeUnit.MONTH, TimeZone.UTC)
There are also shortcuts yearsUntil(...)
, monthsUntil(...)
, and daysUntil(...)
.
A particular amount of date/time units or a date/time period can be added to an Instant
with the plus
function:
val now = Clock.System.now()
val systemTZ = TimeZone.currentSystemDefault()
val tomorrow = now.plus(2, DateTimeUnit.DAY, systemTZ)
val threeYearsAndAMonthLater = now.plus(DateTimePeriod(years = 3, months = 1), systemTZ)
Note that plus
and ...until
operations require TimeZone
as a parameter because the calendar interval between
two particular instants can be different, when calculated in different time zones.
The similar operations with date units are provided for LocalDate
type:
LocalDate.plus(number, DateTimeUnit.DateBased)
LocalDate.plus(DatePeriod)
LocalDate.until(LocalDate, DateTimeUnit.DateBased)
and the shortcutsyearsUntil
,monthUntil
,daysUntil
LocalDate.periodUntil(LocalDate): DatePeriod
andLocalDate.minus(LocalDate): DatePeriod
Notice that instead of general DateTimeUnit
and DateTimePeriod
we're using their subtypes
DateTimeUnit.DateBased
and DatePeriod
respectively. This allows preventing the situations when
time components are being added to a date at compile time.
The implementation of date/time types, such as Instant
, LocalDateTime
, TimeZone
and so on, relies on:
- in JVM:
java.time
API; - in JS:
js-joda
library; - in Native: based on ThreeTen backport project
- time zone support is provided by date C library;
- Some kind of
Clock
interface is needed as a pluggable replacement forInstant.now()
. - Flexible locale-neutral parsing and formatting facilities are needed to support various date/time interchange formats that are used in practice (in particular, various RFCs).
Note that the library is experimental, and the API is subject to change.
The library is published to Maven Central.
The library depends on the Kotlin Standard Library not lower than 1.4.0
.
If you target Android devices running below API 26, you need to use Android Gradle plugin 4.0 or newer and enable core library desugaring.
- Add the Maven Central repository if it is not already there:
repositories {
mavenCentral()
}
- In multiplatform projects, add a dependency to the commonMain source set dependencies
kotlin {
sourceSets {
commonMain {
dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.1.1")
}
}
}
}
- To use the library in a single-platform project, add a dependency to the dependencies block.
dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.1.1")
}
By default, there's only one time zone available in Kotlin/JS: the SYSTEM
time zone with a fixed offset.
If you want to use all time zones in Kotlin/JS platform, you need to add the following npm dependency:
kotlin {
sourceSets {
val jsMain by getting {
dependencies {
implementation(npm("@js-joda/timezone", "2.3.0"))
}
}
}
}
and after that add the following initialization code in your project:
@JsModule("@js-joda/timezone")
@JsNonModule
external object JsJodaTimeZoneModule
private val jsJodaTz = JsJodaTimeZoneModule
Add a dependency to the <dependencies>
element. Note that you need to use the platform-specific -jvm
artifact in Maven.
<dependency>
<groupId>org.jetbrains.kotlinx</groupId>
<artifactId>kotlinx-datetime-jvm</artifactId>
<version>0.1.1</version>
</dependency>
Before building, ensure that you have thirdparty/date submodule initialized and updated. IDEA does that automatically when cloning the repository, and if you cloned it in the command line, you may need to run additionally:
git submodule init
git submodule update
The path to JDK 8 must be specified either with the environment variable JDK_8
or
with the gradle property JDK_8
. For local builds, you can use a later version of JDK if you don't have that
version installed.
After that, the project can be opened in IDEA and built with Gradle.