Documentation ¶
Overview ¶
Package timex contains time and duration related calculations and utilities. It means to be a complement to the standard time package.
Index ¶
- func Diff(a, b time.Time) (year, month, day, hour, min, sec int)
- func ParseMonth(s string) (time.Month, error)
- func ParseWeekday(s string) (time.Weekday, error)
- func Round(d time.Duration, digits int) time.Duration
- func ShortDuration(d time.Duration) string
- func WeekStart(year, week int) time.Time
- func WeekStartTime(t time.Time) time.Time
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Diff ¶
Diff calculates the absolute difference between 2 time instances in years, months, days, hours, minutes and seconds.
For details, see https://stackoverflow.com/a/36531443/1705598
Example ¶
ExampleDiff shows how to use the Diff() function.
// Your birthday: let's say it's January 2nd, 1980, 3:30 AM birthday := time.Date(1980, 1, 2, 3, 30, 0, 0, time.UTC) now := time.Date(2020, 3, 9, 13, 57, 46, 0, time.UTC) year, month, day, hour, min, sec := Diff(birthday, now) fmt.Printf( "You are %d years, %d months, %d days, %d hours, %d mins and %d seconds old.", year, month, day, hour, min, sec, )
Output: You are 40 years, 2 months, 7 days, 10 hours, 27 mins and 46 seconds old.
func ParseMonth ¶
ParseMonth parses a month given by its name. Both long names such as "January", "February" and short names such as "Jan", "Feb" are recognized.
For details, see https://stackoverflow.com/a/59681275/1705598
func ParseWeekday ¶
ParseWeekday parses a weekday given by its name. Both long names such as "Monday", "Tuesday" and short names such as "Mon", "Tue" are recognized.
For details, see https://stackoverflow.com/a/52456320/1705598
func Round ¶
Round rounds the given duration so that when it is printed (when its String() method is called), result will have the given fraction digits at most.
For details, see https://stackoverflow.com/a/58415564/1705598
Example ¶
ExampleRound shows how to use the Round() function.
ds := []time.Duration{ time.Hour + time.Second + 123*time.Millisecond, // 1h0m1.123s time.Hour + time.Second + time.Microsecond, // 1h0m1.000001s 123456789 * time.Nanosecond, // 123.456789ms 123456 * time.Nanosecond, // 123.456µs 123 * time.Nanosecond, // 123ns } fmt.Println("Duration |0 digits |1 digit |2 digits |3 digits |") fmt.Println("-------------------------------------------------------------------") for _, d := range ds { fmt.Printf("%-14v|", d) for digits := 0; digits <= 3; digits++ { fmt.Printf("%-12v|", Round(d, digits)) } fmt.Println() }
Output: Duration |0 digits |1 digit |2 digits |3 digits | ------------------------------------------------------------------- 1h0m1.123s |1h0m1s |1h0m1.1s |1h0m1.12s |1h0m1.123s | 1h0m1.000001s |1h0m1s |1h0m1s |1h0m1s |1h0m1s | 123.456789ms |123ms |123.5ms |123.46ms |123.457ms | 123.456µs |123µs |123.5µs |123.46µs |123.456µs | 123ns |123ns |123ns |123ns |123ns |
func ShortDuration ¶
ShortDuration formats the given duration into a short format. The short format eludes trailing 0 units in the string.
For example:
5h4m3s => 5h4m3s 5h4m0s => 5h4m 5h0m3s => 5h0m3s 4m3s => 4m3s 5h0m0s => 5h 4m0s => 4m 3s => 3s
For details, see https://stackoverflow.com/a/41336257/1705598
Example ¶
ExampleShortDuration shows how to use the ShortDuration() function.
h, m, s := 5*time.Hour, 4*time.Minute, 3*time.Second ds := []time.Duration{ h + m + s, h + m, h + s, m + s, h, m, s, } fmt.Println("Default | Short |") fmt.Println("-------------------") for _, d := range ds { fmt.Printf("%-8v| %-8v|\n", d, ShortDuration(d)) }
Output: Default | Short | ------------------- 5h4m3s | 5h4m3s | 5h4m0s | 5h4m | 5h0m3s | 5h0m3s | 4m3s | 4m3s | 5h0m0s | 5h | 4m0s | 4m | 3s | 3s |
func WeekStart ¶
WeekStart returns the time instant pointing to the start of the week given by its year and ISO Week. Weeks are interpreted starting on Monday, so the returned instant will be 00:00 UTC of Monday of the designated week.
One nice property of this function is that it handles out-of-range weeks nicely. That is, if you pass 0 for the week, it will be interpreted as the last week of the previous year. If you pass -1 for the week, it will designate the second to last week of the previous year. Similarly, if you pass max week of the year plus 1, it will be interpreted as the first week of the next year etc.
This function only returns the given week's first day (Monday), because the last day of the week is always its first day + 6 days.
For details, see https://stackoverflow.com/a/52303730/1705598
Example ¶
ExampleWeekStart shows how to use the WeekStart() function.
inputs := []struct{ year, week int }{ {2018, -1}, {2018, 0}, {2018, 1}, {2018, 2}, {2019, 1}, {2019, 2}, {2019, 53}, {2019, 54}, } for _, c := range inputs { fmt.Printf("Week (%d,%2d) starts on: %v\n", c.year, c.week, WeekStart(c.year, c.week)) }
Output: Week (2018,-1) starts on: 2017-12-18 00:00:00 +0000 UTC Week (2018, 0) starts on: 2017-12-25 00:00:00 +0000 UTC Week (2018, 1) starts on: 2018-01-01 00:00:00 +0000 UTC Week (2018, 2) starts on: 2018-01-08 00:00:00 +0000 UTC Week (2019, 1) starts on: 2018-12-31 00:00:00 +0000 UTC Week (2019, 2) starts on: 2019-01-07 00:00:00 +0000 UTC Week (2019,53) starts on: 2019-12-30 00:00:00 +0000 UTC Week (2019,54) starts on: 2020-01-06 00:00:00 +0000 UTC
func WeekStartTime ¶
WeekStartTime returns the time instant pointing to the start of the (ISO) week denoted by the given timestamp. Weeks are interpreted starting on Monday, so the returned instant will be 00:00 UTC of Monday of the designated week.
This function only returns the given week's first day (Monday), because the last day of the week is always its first day + 6 days.
Example ¶
ExampleWeekStartTime shows how to use the WeekStartTime() function.
inputs := []struct{ t time.Time }{ {time.Date(2018, 12, 31, 11, 0, 0, 0, time.UTC)}, {time.Date(2019, 1, 1, 11, 0, 0, 0, time.UTC)}, {time.Date(2024, 8, 25, 11, 0, 0, 0, time.UTC)}, {time.Date(2024, 8, 26, 11, 0, 0, 0, time.UTC)}, {time.Date(2024, 8, 29, 11, 0, 0, 0, time.UTC)}, {time.Date(2024, 9, 1, 11, 0, 0, 0, time.UTC)}, {time.Date(2024, 9, 2, 11, 0, 0, 0, time.UTC)}, {time.Date(2024, 9, 1, 11, 0, 0, 0, time.FixedZone("F1H", 3600))}, {time.Date(2024, 9, 2, 11, 0, 0, 0, time.FixedZone("F-1H", -3600))}, } for _, c := range inputs { fmt.Printf("Week of %v starts on: %v\n", c.t, WeekStartTime(c.t)) }
Output: Week of 2018-12-31 11:00:00 +0000 UTC starts on: 2018-12-31 00:00:00 +0000 UTC Week of 2019-01-01 11:00:00 +0000 UTC starts on: 2018-12-31 00:00:00 +0000 UTC Week of 2024-08-25 11:00:00 +0000 UTC starts on: 2024-08-19 00:00:00 +0000 UTC Week of 2024-08-26 11:00:00 +0000 UTC starts on: 2024-08-26 00:00:00 +0000 UTC Week of 2024-08-29 11:00:00 +0000 UTC starts on: 2024-08-26 00:00:00 +0000 UTC Week of 2024-09-01 11:00:00 +0000 UTC starts on: 2024-08-26 00:00:00 +0000 UTC Week of 2024-09-02 11:00:00 +0000 UTC starts on: 2024-09-02 00:00:00 +0000 UTC Week of 2024-09-01 11:00:00 +0100 F1H starts on: 2024-08-26 00:00:00 +0000 UTC Week of 2024-09-02 11:00:00 -0100 F-1H starts on: 2024-09-02 00:00:00 +0000 UTC
Types ¶
This section is empty.