Source Code

Date and Time library for Ceylon language SDK.

This library is loosely modeled/inspired by the JodaTime/JSR-310 date/time library.

By: Diego Coronel, Roland Tepp

“Main package for the Ceylon's Date and Time library.


Base classes and interfaces of the Date/Time library.


Package containing supported chronologies in ceylon.time library.


“Main package for the Ceylon's Date and Time library.

Like in JodaTime and JSR-310, there is a machine timeline and a human timeline.

Machine timeline

Machine timeline is represented by an Instant that is basically just an object wrapper around an Integer representing Unix time value. A value of an Instant uniquely identifies a particular instant of time without needing to take into account timezone information and contain no ambiguities associated with DST changeover times.

Human timeline

Human timeline is based mostly on Gregorian and ISO 8601 calendar systems and consists of the following principal data types:

  • Date – A date value without time component
  • Time – A time of day vallue without date component.
  • DateTime – A particular time of a particular date.
  • ZoneDateTime – A particular moment of time identified by date, time of day and a time zone.

Note: At the moment, timezone support and awareness is missing from the library, so all of the time and date types and conversions behave as though staying in UTC-0.

By: Diego Coronel, Roland Tepp
systemTimeSource Code
shared systemTime systemTime

Gets a clock that obtains the current instant using the best available system clock.

zeroSource Code
shared Period zero

A period of zero length

dateSource Code
shared Date date(Integer year, Integer|Month month, Integer day)

Returns a date based on the specified year, month and day-ofMonth values

dateTimeSource Code
shared DateTime dateTime(Integer year, Integer|Month month, Integer date, Integer hour, Integer minutes, Integer seconds, Integer millis)

Returns a date based on the specified year, month and day-of-month values

fixedTimeSource Code
shared Clock fixedTime(Instant|Integer instant)

Gets a clock that always returns the same instant in the UTC time-zone.

nowSource Code
shared Instant now(Clock? clock)

Obtains the current instant from the system clock.

timeSource Code
shared Time time(Integer hours, Integer minutes, Integer seconds, Integer millis)

Creates new instance of Time.

todaySource Code
shared Date today(Clock clock, TimeZone? zone)

Returns current date according to the provided system clock and time zone.

ClockSource Code
shared Clock

A clock providing access to the current instant, date and time using a time-zone.

Instances of this class are used to find the current instant, which can be interpreted using the stored time-zone to find the current date and time. As such, a clock can be used instead of {@link System#currentTimeMillis()} and {@link TimeZone#getDefault()}.

The primary purpose of this abstraction is to allow alternate clocks to be plugged in as and when required. Applications use an object to obtain the current time rather than a static method. This can simplify testing.

Applications should avoid using the static methods on this class. Instead, they should pass a {@code Clock} into any method that requires it. A dependency injection framework is one way to achieve this:

public class MyBean {
  private Clock clock;  // dependency inject
  public void process(LocalDate eventDate) {
    if (eventDate.isBefore( {

This approach allows an alternate clock, such as {@link #fixed} to be used during testing.

The {@code system} factory method provides clocks based on the best available system clock, such as {@code System.currentTimeMillis}.

DateSource Code
shared Date

An interface for date objects in the ISO-8601 calendar system.

A date is often viewed as triple of year-month-day values. This interface also defines access to other date fields such as day-of-year, day-of-week and week-of-year.

DateTimeSource Code
shared DateTime

An abstract moment in time (like 4pm, October 21. 2012).

DateTime does not contain a time zone information, so You can not use it to record or schedule events.

TimeSource Code
shared Time

Time of day like 6pm or 8.30am.

This type contains only information about an abstract time of day without referencing any date or timezone.

You use Time to specify something that has to occur on a specific time of day like “lunch hour starts at 1pm” or “shop opens at 10am”.

DurationSource Code
shared Duration

Duration specifies a discreet amount of milliseconds between two instances of time.

InstantSource Code
shared Instant

A specific instant of time on a continuous time-scale.

An instant represents a single point in time irrespective of any time-zone offsets or geographical locations

PeriodSource Code
shared Period

An immutable period consisting of the ISO-8601 years, months, days, hours, minutes, seconds and milliseconds, such as '3 Months, 4 Days and 7 Hours'.

A period is a human-scale description of an amount of time.

systemTimeSource Code
shared systemTime

Gets a clock that obtains the current instant using the best available system clock.