tokiope

README

tokiope: An alternative Go library for basic time operations

• Overview
• Getting Started
  • Installation
  • Time Zone Offset Transitions
• Usage
  • Types Overview
  • API References
  • Example Code
• Design Policy
  • Focusing on Basic Time Operations
  • Addressing Common Pitfalls

Overview

tokiope is a Go library to provide basic time operations, consisting of types designed to empower developers to implement application-specific time manipulations with correctness and clarity. The basic time operations in tokiope include:

• Representation of temporal values.
• Conversion of temporal values.
• Handling of time zones.
• Instant-based operations.
• Calendar-based operations.

The types in tokiope are designed with the following policies:

• Be well-defined.
• Be explicit.
• Be unambiguous.
• Follow standard.

Getting Started

Installation

go get "github.com/Jumpaku/tokiope"

Time Zone Offset Transitions

tokiope requires data for time zone offset transitions based on the IANA timezone database to handle time zones. This data is managed in the separate repository https://github.com/Jumpaku/tz-offset-transitions because it will be updated independently of tokiope. Therefore, tokiope provides a CLI tool to download this data as follows:

go run "github.com/Jumpaku/tokiope/cmd/tokiope-tzot" download -out-path=tzot.json
# The above command downloads the data and saves it as a file 'tzot.json'.

Usage

Types Overview

The tokiope package provides basic types to handle temporal values:

• Instant: Represents an instantaneous point on the time-line, which is compatible with the UNIX time seconds.
• Duration: Represents an amount of a difference between two instants.

The tokiope/calendar package provides types to represent values on the calendar:

• Date: Represents a day on the calendar in the format of yyyy-mm-dd, yyyy-Www-dd, or yyyy-ddd.
• YearMonth: Represents a month on the calendar in the format of yyyy-mm.
• YearWeek: Represents a week on the calendar in the format of yyyy-Www.
• Year: Represents a year on the calendar in the format of yyyy.

The tokiope/calendar/iter package provides iterators on the calendar:

• DateIterator: Iterates days on the calendar.
• YearMonthIterator: Iterates months on the calendar.
• YearWeekIterator: Iterates weeks on the calendar.
• YearIterator: Iterates years on the calendar.

The tokiope/datetime package provides types to handle date-times:

• OffsetDateTime: Represents an instant as a combination of a date and a time with an offset.
• OffsetMinutes: Represents an offset from UTC in minutes.

The tokiope/datetime/zone package provides types to handle zoned date-times:

• ZonedDateTime: Represents a combination of a date and a time with a time zone.
• Zone: Represents a time zone that has a time zone ID and provides a mapping from instants to offsets for a specific time zone.
• Provider: Provides time zones according to the data for time zone offset transitions based on the IANA timezone database.

API References

Detailed API references are available at https://pkg.go.dev/github.com/Jumpaku/tokiope .

Example Code

Example code snippets demonstrating practical usage of tokiope's functionalities are available at https://github.com/Jumpaku/tokiope/blob/main/docs/example-code.md .

Design Policy

tokiope, which focuses on basic time operations, challenges to address pitfalls by providing a well-designed type framework with the following policies:

• Be well-defined: Valid calls of functions for time operations do not lead to invalid states or errors.
• Be explicit: Function behaviors depend only on object states and arguments, but not on external environments implicitly.
• Be unambiguous: Only functions that can be named so that their behavior is clear and predictable are provided.
• Follow standard: Date and time representations follow the standard ISO 8601-1:2019 https://en.wikipedia.org/wiki/ISO_8601.

Focusing on Basic Time Operations

Since application-specific functionalities depend on individual product requirements, tokiope focuses on providing a solid foundation for basic time operations, which include:

• Representation of temporal values, including Instant, Date, OffsetDateTime, and ZonedDateTime.
• Conversion of temporal values, such as conversion between Instant and OffsetDateTime.
• Handling time zones by the tokiope/datetime/zone package.
• Instant-based temporal operations using Instant and Duration.
• Calendar-based temporal operations using iterators in the tokiope/date/iter package.

Addressing Common Pitfalls

The types in tokiope are designed according to the above policies, enabling developers to address the following common pitfalls in time operations:

• Implicit use of local time zones depending on environments.
• Ambiguities in calendar-based operations.
• Oversight of leap years.
• Storing date-times of past events without offsets.
• Storing timestamps of events scheduled in the future.
• Incorrect handling of daylight saving time (DST).

Implicit Use of Local Time Zones Depending on Environments

Implicit reliance on local time zones can lead to inconsistencies and bugs when dealing with time operations across different environments. This often occurs when applications use the system's default time zone without explicitly specifying it. Therefore, the time zone should always be explicitly specified to ensure consistent behavior across environments.

tokiope explicitly obtains Zone via the zone.Provider.Get method or zone.Create function. Notably, tokiope does not provide an API to obtain Zone from the local time zone implicitly.

Ambiguities in Calendar-Based Operations

Ambiguities often arise in calendar-based operations, presenting challenges such as:

• Determining the date one month after 2024-01-31, even though 2024-02-31 does not exist.
• Determining the date one year after 2024-02-29, even though 2025-02-29 does not exist.
• Counting the number of months between 2024-03-30 and 2024-04-30 or 2024-03-31 and 2024-04-30.
• Counting the number of years between 2024-02-28 and 2025-02-28 or 2024-02-29 and 2025-02-28.

To avoid these confusions, APIs for calendar-based operations should be designed clearly.

tokiope's iterators provided by the tokiope/date/iter package are specifically designed to execute calendar-based operations unambiguously.

Oversight of Leap Years

Leap years are frequently overlooked when calculating dates, and developers may not always understand the rules governing leap years correctly. It is essential to use libraries implementing calendar-based operations with leap years appropriately and to test the implementation.

tokiope fully supports leap years and undergoes unit tests to ensure reliability.

Storing Date-Times of Past Events without Offsets

Date-times stored without offsets may cause difficulties when attempting to restore the corresponding timestamp because the offsets from UTC are not clear and may vary due to time zones or DST. It is advisable to store the timestamps of past or physical events using a representation convertible to the original timestamps, such as date-times with offsets or UNIX seconds.

To represent timestamps consistently, tokiope offers Instant for UNIX seconds and OffsetDateTime for date-times with offsets, both of which are always convertible to timestamps.

Storing Timestamps of Events Scheduled in the Future

Storing a timestamp for the event scheduled on the calendar in the future as UNIX seconds or date-time with offset can lead to issues because the timestamp is not deterministic. For instance, the timestamp corresponding to the original date-time may change from the stored timestamp due to time zone offset transitions resulting from DST or changes in political rules. To address these concerns, it's recommended to store the date-time with a time zone to accommodate the offset transitions.

tokiope offers ZonedDateTime to represent date-times with time zones.

Incorrect Handling of Daylight Saving Time (DST)

Daylight Saving Time (DST) may not be handled properly, especially by inexperienced developers or those working in time zones without DST.

tokiope is designed to appropriately handle offset transitions, including DST. For example:

• func (Zone) FindOffset(at Instant) OffsetMinutes returns the corresponding offset at a particular instant in a specific time zone.
• func (ZonedDateTime) InstantCandidates() []Instant returns all possible timestamps that a specific date-time may represent, where the returned timestamps may be empty due to gaps or include multiple timestamps due to overlaps.

Documentation

Index

• Constants
• Variables
• type Clock
  • func FixedClock(fixAt Instant) Clock
  • func NewClock(now NowFunc) Clock
  • func OffsetClock(original Clock, offset Duration) Clock
  • func WallClock() Clock
• type Duration
  • func Days(days int64) (d Duration)
  • func Hours(hours int64) (d Duration)
  • func Minutes(minutes int64) (d Duration)
  • func Nanoseconds(nanoseconds int64) (d Duration)
  • func Seconds(seconds int64, nano int64) (d Duration)
  • func (d Duration) Abs() Duration
  • func (d Duration) Add(o Duration) (out Duration)
  • func (d Duration) AddNano(nanoseconds int64) (out Duration)
  • func (d Duration) Cmp(o Duration) int
  • func (d Duration) Neg() (out Duration)
  • func (d Duration) OK() bool
  • func (d Duration) Seconds() (seconds int64, nano int64)
  • func (d Duration) Sign() int
  • func (d Duration) State() State
  • func (d Duration) String() string
  • func (d Duration) Sub(o Duration) (out Duration)
  • func (d Duration) SubNano(nanoseconds int64) (out Duration)
• type Instant
  • func Unix(unixSeconds int64, nano int64) Instant
  • func (i Instant) Add(duration Duration) Instant
  • func (i Instant) AddNano(nanoseconds int64) Instant
  • func (i Instant) After(o Instant) bool
  • func (i Instant) Before(o Instant) bool
  • func (i Instant) Between(lo, hi Instant) bool
  • func (i Instant) Cmp(o Instant) int
  • func (i Instant) Diff(instant Instant) Duration
  • func (i Instant) Equal(o Instant) bool
  • func (i Instant) OK() bool
  • func (i Instant) State() State
  • func (i Instant) String() string
  • func (i Instant) Sub(duration Duration) Instant
  • func (i Instant) SubNano(nanoseconds int64) Instant
  • func (i Instant) Unix() (seconds int64, nano int64)
• type NowFunc
  • func (f NowFunc) Now() Instant
• type State

Constants

const (
	SecondsPerMinute = 60
	MinutesPerHour   = 60
	HoursPerDay      = 24
	SecondsPerHour   = SecondsPerMinute * MinutesPerHour
	SecondsPerDay    = SecondsPerHour * HoursPerDay
)

const NanosPerSecond = 1_000_000_000

Variables

var MaxDuration = Duration{/* contains filtered or unexported fields */}

var MaxInstant = Instant{/* contains filtered or unexported fields */}

var MinDuration = Duration{/* contains filtered or unexported fields */}

var MinInstant = Instant{/* contains filtered or unexported fields */}

Types

type Clock

type Clock interface {
	Now() Instant
}

Clock represents a source of instants.

func FixedClock

func FixedClock(fixAt Instant) Clock

FixedClock returns a Clock that always returns the instant fixAt.

func NewClock

func NewClock(now NowFunc) Clock

NewClock creates a Clock from a NowFunc.

func OffsetClock

func OffsetClock(original Clock, offset Duration) Clock

OffsetClock returns a Clock that returns the instant offset from the original Clock.

func WallClock

func WallClock() Clock

WallClock returns a Clock that returns the current time based on time.Now().

type Duration

type Duration struct {
	// contains filtered or unexported fields
}

Duration represents an amount between two instants.

func Days

func Days(days int64) (d Duration)

Days returns a Duration of days.

func Hours

func Hours(hours int64) (d Duration)

Hours returns a Duration of hours.

func Minutes

func Minutes(minutes int64) (d Duration)

Minutes returns a Duration of minutes.

func Nanoseconds

func Nanoseconds(nanoseconds int64) (d Duration)

Nanoseconds returns a Duration of nanoseconds.

func Seconds

func Seconds(seconds int64, nano int64) (d Duration)

Seconds returns a Duration of seconds and nanoseconds.

func (Duration) Abs

func (d Duration) Abs() Duration

Abs returns the absolute value of the Duration.

func (Duration) Add

func (d Duration) Add(o Duration) (out Duration)

Add returns the Duration adding the other duration.

func (Duration) AddNano

func (d Duration) AddNano(nanoseconds int64) (out Duration)

AddNano returns the Duration adding the nanoseconds.

func (Duration) Cmp

func (d Duration) Cmp(o Duration) int

Cmp compares the Duration with the other Duration.

func (Duration) Neg

func (d Duration) Neg() (out Duration)

Neg returns the negated Duration.

func (Duration) OK

func (d Duration) OK() bool

func (Duration) Seconds

func (d Duration) Seconds() (seconds int64, nano int64)

Seconds returns the number of seconds and nanoseconds.

func (Duration) Sign

func (d Duration) Sign() int

Sign returns the sign of the Duration.

func (Duration) State

func (d Duration) State() State

func (Duration) String

func (d Duration) String() string

String returns the string representation of the Duration.

func (Duration) Sub

func (d Duration) Sub(o Duration) (out Duration)

Sub returns the Duration subtracting the other duration.

func (Duration) SubNano

func (d Duration) SubNano(nanoseconds int64) (out Duration)

SubNano returns the Duration subtracting the nanoseconds.

type Instant

type Instant struct {
	// contains filtered or unexported fields
}

Instant represents a point in time.

func Unix

func Unix(unixSeconds int64, nano int64) Instant

Unix returns an Instant since the Unix epoch.

func (Instant) Add

func (i Instant) Add(duration Duration) Instant

Add returns the Instant going forward by the amount of duration.

func (Instant) AddNano

func (i Instant) AddNano(nanoseconds int64) Instant

AddNano returns the Instant going forward by the amount of nanoseconds.

func (Instant) After

func (i Instant) After(o Instant) bool

After returns whether the instant is after the other instant.

func (Instant) Before

func (i Instant) Before(o Instant) bool

Before returns whether the instant is before the other instant.

func (Instant) Between

func (i Instant) Between(lo, hi Instant) bool

Between returns whether the instant is between the lo and hi.

func (Instant) Cmp

func (i Instant) Cmp(o Instant) int

Cmp compares the instant with the other instant.

func (Instant) Diff

func (i Instant) Diff(instant Instant) Duration

Diff returns the duration of difference from the instant.

func (Instant) Equal

func (i Instant) Equal(o Instant) bool

Equal returns whether the instant is equal to the other instant.

func (Instant) OK

func (i Instant) OK() bool

func (Instant) State

func (i Instant) State() State

func (Instant) String

func (i Instant) String() string

String returns the string representation of the instant.

func (Instant) Sub

func (i Instant) Sub(duration Duration) Instant

Sub returns the Instant going backward by the amount of duration.

func (Instant) SubNano

func (i Instant) SubNano(nanoseconds int64) Instant

SubNano returns the Instant going backward by the amount of nanoseconds.

func (Instant) Unix

func (i Instant) Unix() (seconds int64, nano int64)

Unix returns the number of seconds and nanoseconds since the Unix epoch.

type NowFunc

type NowFunc func() Instant

NowFunc is a function that returns an instant.

func (NowFunc) Now

func (f NowFunc) Now() Instant

Now returns a current instant.

type State

type State int8

const (
	// StateOK represents no error.
	StateOK State = (1 << iota) >> 1
	// StateOverflow bit is set if overflow occurred
	StateOverflow
)