Terminology

Clock

A Clock is the root object to access time. Like a real clock, each time you demand the time it will provide a new value. This is part of the world that can change.

Unlike real clocks, in a program we often have the use case to convert a string back to a time representation (1). Clocks provide a method for this. You can think of it as a factory. Even though this is done by a clock this method is determinist, meaning that you'll always have the same result for the same inputs.

1. Such as reading a value from a database.

Point in time

As its name suggest it represents a fixed point in time on Earth. It represents time down to the microsecond. It also stores the time offset from UTC.

These objects are generated by clocks.

Once an object is created it can no longer change. But you can still create objects relative to it by specifying a period and the direction.

Timezone

A timezone represents a time offset from UTC for a set of cities on Earth (1).

1. For example Europe/Paris.

Due to politics a city may change its offset at any time (1). And for economic reasons some countries change their offset each year, a process called "daylight saving time" (2).

1. This means some points in time don't exist in certain countries or exist twice.
2. Usually they increase/decrease their offset by 1 or 2 hours.

Because asking the offset for a timezone will yield different results depending on when you ask for it, it's part of the world that changes. This means that timezones are handled at the clock level.

Period

It represents the time between 2 points in time. It can be defined by a number of:

• years
• months
• days
• hours
• minutes
• seconds
• milliseconds
• microseconds

Each of this component has to be a positive integer. It's when you apply it to a point in time that you decide if you want to go forward or back in time.

Since these objects are not tied to a particular point in time they're immutable.

Elapsed period

It represents the number of microseconds between two points in time.

Once an object is created it cannot change.

This is useful to compute the time your program took to accomplish a task. Operation often used when dealing with network I/O to handle timeouts.

Format

A format defines a way to represent a point in time as a string (1).

1. Usually to store the value to a database or print it in a user interface.

It's declared as an object to give meaning to the string format it encapsulate. The intent is to declare the string format once in an object in your program and reuse this object everywhere. This allows to attach a name to the format.

This is an attempt to solve the problem (1) where the same format is duplicated everywhere in a program.

1. We can see this practive in a lot of programs.