timediff

README

timediff

timediff is a Go package for printing human readable, relative time differences. Output is based on ranges defined in the Day.js JavaScript library, and can be customized if needed.

Here are examples of durations and their corresponding string outputs (taken from test output), using default options:

-864000h   100 years ago
-172800h   20 years ago
-17280h    2 years ago
-8640h     a year ago
-7200h1m   a year ago
-7200h     10 months ago
-6480h     9 months ago
-1920h     3 months ago
-1104h     2 months ago
-1080h     a month ago
-624h      a month ago
-600h      25 days ago
-240h      10 days ago
-36h       2 days ago
-24h       a day ago
-22h       a day ago
-21h30m    a day ago
-21h       21 hours ago
-20h       20 hours ago
-2h        2 hours ago
-90m       2 hours ago
-89m       an hour ago
-80m       an hour ago
-1h        an hour ago
-60m       an hour ago
-45m       an hour ago
-44m       44 minutes ago
-10m       10 minutes ago
-2m        2 minutes ago
-90s       2 minutes ago
-89s       a minute ago
-45s       a minute ago
-44s       a few seconds ago
-10s       a few seconds ago
10s        in a few seconds
44s        in a few seconds
45s        in a minute
89s        in a minute
90s        in 2 minutes
2m         in 2 minutes
10m        in 10 minutes
44m        in 44 minutes
45m        in an hour
60m        in an hour
1h         in an hour
80m        in an hour
89m        in an hour
90m        in 2 hours
2h         in 2 hours
20h        in 20 hours
21h        in 21 hours
21h30m     in a day
22h        in a day
24h        in a day
36h        in 2 days
240h       in 10 days
600h       in 25 days
624h       in a month
1080h      in a month
1104h      in 2 months
1920h      in 3 months
6480h      in 9 months
7200h      in 10 months
7200h1m    in a year
8640h      in a year
17280h     in 2 years
172800h    in 20 years
864000h    in 100 years

Documentation

Index

• Variables
• func TimeDiff(t time.Time, options ...TimeDiffOption) string
• type RangeFormatters
• type TimeDiffOption
  • func WithStartTime(t time.Time) TimeDiffOption

Variables

var DefaultTimeDiffRangeFormatters = RangeFormatters{
	-1 << 63:                    func(d time.Duration) string { return fmt.Sprintf("in %.0f years", -d.Hours()/(24.0*30*12)) },
	-17 * (24 * time.Hour) * 30: func(_ time.Duration) string { return "in a year" },
	-10 * (24 * time.Hour) * 30: func(d time.Duration) string { return fmt.Sprintf("in %.0f months", -d.Hours()/(24.0*30)) },
	-45 * (24 * time.Hour):      func(d time.Duration) string { return "in a month" },
	-25 * (24 * time.Hour):      func(d time.Duration) string { return fmt.Sprintf("in %.0f days", -d.Hours()/24.0) },
	-35 * time.Hour:             func(_ time.Duration) string { return "in a day" },
	-21 * time.Hour:             func(d time.Duration) string { return fmt.Sprintf("in %.0f hours", -d.Hours()) },
	-89 * time.Minute:           func(_ time.Duration) string { return "in an hour" },
	-44 * time.Minute:           func(d time.Duration) string { return fmt.Sprintf("in %.0f minutes", -d.Minutes()) },
	-89 * time.Second:           func(_ time.Duration) string { return "in a minute" },
	-44 * time.Second:           func(_ time.Duration) string { return "in a few seconds" },

	44 * time.Second:           func(_ time.Duration) string { return "a few seconds ago" },
	89 * time.Second:           func(_ time.Duration) string { return "a minute ago" },
	44 * time.Minute:           func(d time.Duration) string { return fmt.Sprintf("%.0f minutes ago", d.Minutes()) },
	89 * time.Minute:           func(_ time.Duration) string { return "an hour ago" },
	21 * time.Hour:             func(d time.Duration) string { return fmt.Sprintf("%.0f hours ago", d.Hours()) },
	35 * time.Hour:             func(_ time.Duration) string { return "a day ago" },
	25 * (24 * time.Hour):      func(d time.Duration) string { return fmt.Sprintf("%.0f days ago", d.Hours()/24.0) },
	45 * (24 * time.Hour):      func(d time.Duration) string { return "a month ago" },
	10 * (24 * time.Hour) * 30: func(d time.Duration) string { return fmt.Sprintf("%.0f months ago", d.Hours()/(24.0*30)) },
	17 * (24 * time.Hour) * 30: func(_ time.Duration) string { return "a year ago" },
	1<<63 - 1:                  func(d time.Duration) string { return fmt.Sprintf("%.0f years ago", d.Hours()/(24.0*30*12)) },
}

DefaultTimeDiffRangeFormatters are the time ranges and their corresponding string formatters.

Functions

func TimeDiff

func TimeDiff(t time.Time, options ...TimeDiffOption) string

TimeDiff prints a human-readable string representing the difference between two `time.Time`s. By default, the "start" time is time.Now(), but can be overridden with the WithStartTime(t time.Time) option.

Types

type RangeFormatters

type RangeFormatters map[time.Duration]func(d time.Duration) string

RangeFormatters is a collection of associations between a min/max duration and a function for formatting an output string

type TimeDiffOption

type TimeDiffOption func(*timeDiffOptions)

TimeDiffOption is an otion used to customize a call to TimeDiff

func WithStartTime

func WithStartTime(t time.Time) TimeDiffOption

WithStartTime changes the start time from which time diff calculations are made. Defaults to time.Now().