timeutil

package
v13.20.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 17, 2025 License: Apache-2.0 Imports: 8 Imported by: 15

Documentation

Overview

Package timeutil provides methods for working with time and date

Index

Examples

Constants

View Source 
const (
	NS     = time.Nanosecond
	US     = time.Microsecond
	MS     = time.Millisecond
	SECOND = time.Second
	MINUTE = time.Minute
	HOUR   = time.Hour
	DAY    = 24 * HOUR
	WEEK   = 7 * DAY
	YEAR   = 365 * DAY
)

Variables

View Source 
var StartDate = uint32(1322611200)

StartDate contains start date timestamp

Functions

func DurationAs added in v13.20.2 

func DurationAs(t, unit time.Duration) int

DurationAs returns duration in given units

Example 
d1 := time.Date(2021, 1, 1, 12, 30, 15, 0, time.Local)
d2 := time.Date(2024, 6, 15, 14, 15, 45, 0, time.Local)

d := d2.Sub(d1)

fmt.Printf("Days: %d\n", DurationAs(d, DAY))

Output:

Days: 1261

func DurationToSeconds 

func DurationToSeconds(d time.Duration) float64

DurationToSeconds converts time.Duration to float64

Example 
fmt.Println(DurationToSeconds(2500 * time.Millisecond))

Output:

2.5

func EndOfDay added in v13.16.0 

func EndOfDay(t time.Time) time.Time

EndOfDay returns end of the day

Example 
d := time.Date(2021, 6, 15, 12, 30, 15, 0, time.UTC)

fmt.Println(EndOfDay(d))

Output:

2021-06-15 23:59:59.999999999 +0000 UTC

func EndOfHour added in v13.16.0 

func EndOfHour(t time.Time) time.Time

EndOfHour returns end of the hour

Example 
d := time.Date(2021, 6, 15, 12, 30, 15, 0, time.UTC)

fmt.Println(EndOfHour(d))

Output:

2021-06-15 12:59:59.999999999 +0000 UTC

func EndOfMonth added in v13.16.0 

func EndOfMonth(t time.Time) time.Time

EndOfMonth returns the last day of the month

Example 
d := time.Date(2021, 6, 15, 12, 30, 15, 0, time.UTC)

fmt.Println(EndOfMonth(d))

Output:

2021-06-30 23:59:59.999999999 +0000 UTC

func EndOfWeek added in v13.16.0 

func EndOfWeek(t time.Time, firstDay time.Weekday) time.Time

EndOfWeek returns the last day of the week

Example 
d := time.Date(2021, 6, 15, 12, 30, 15, 0, time.UTC)

fmt.Println(EndOfWeek(d, time.Monday))

Output:

2021-06-20 23:59:59.999999999 +0000 UTC

func EndOfYear added in v13.16.0 

func EndOfYear(t time.Time) time.Time

EndOfYear returns the last day of the year

Example 
d := time.Date(2021, 6, 15, 12, 30, 15, 0, time.UTC)

fmt.Println(EndOfYear(d))

Output:

2021-12-31 23:59:59.999999999 +0000 UTC

func Format 

func Format(d time.Time, f string) string

Format returns formatted date as a string

Interpreted sequences: 

'%%' a literal %
'%a' locale's abbreviated weekday name (e.g., Sun)
'%A' locale's full weekday name (e.g., Sunday)
'%b' locale's abbreviated month name (e.g., Jan)
'%B' locale's full month name (e.g., January)
'%c' locale's date and time (e.g., Thu Mar 3 23:05:25 2005)
'%C' century; like %Y, except omit last two digits (e.g., 20)
'%d' day of month (e.g, 01)
'%D' date; same as %m/%d/%y
'%e' day of month, space padded
'%F' full date; same as %Y-%m-%d
'%g' last two digits of year of ISO week number (see %G)
'%G' year of ISO week number (see %V); normally useful only with %V
'%h' same as %b
'%H' hour (00..23)
'%I' hour (01..12)
'%j' day of year (001..366)
'%k' hour ( 0..23)
'%K' milliseconds (000..999)
'%l' hour ( 1..12)
'%m' month (01..12)
'%M' minute (00..59)
'%n' a newline
'%N' nanoseconds (000000000..999999999)
'%p' AM or PM
'%P' like %p, but lower case
'%r' locale's 12-hour clock time (e.g., 11:11:04 PM)
'%R' 24-hour hour and minute; same as %H:%M
'%s' seconds since 1970-01-01 00:00:00 UTC
'%S' second (00..60)
'%t' a tab
'%T' time; same as %H:%M:%S
'%u' day of week (1..7); 1 is Monday
'%U' week number of year, with Sunday as first day of week (00..53)
'%V' ISO week number, with Monday as first day of week (01..53)
'%w' day of week (0..6); 0 is Sunday
'%W' week number of year, with Monday as first day of week (00..53)
'%x' locale's date representation (e.g., 12/31/99)
'%X' locale's time representation (e.g., 23:13:48)
'%y' last two digits of year (00..99)
'%Y' year
'%z' +hhmm numeric timezone (e.g., -0400)
'%:z' +hh:mm numeric timezone (e.g., -04:00)
'%Z' alphabetic time zone abbreviation (e.g., EDT)
Example 
date := time.Date(2010, 6, 15, 15, 30, 45, 1234, time.Local)

fmt.Println(Format(date, "%A %d/%b/%Y %H:%M:%S.%N"))

Output:

Tuesday 15/Jun/2010 15:30:45.000001234

func FromISOWeek 

func FromISOWeek(week, year int, loc *time.Location) time.Time

FromISOWeek returns date for given week number in given year

Example 
t := FromISOWeek(25, 2021, time.UTC)

fmt.Println(t)

Output:

2021-06-18 00:00:00 +0000 UTC

func IsWeekend added in v13.16.0 

func IsWeekend(t time.Time) bool

IsWeekend returns true if given day is weekend (saturday or sunday)

Example 
d := time.Date(2021, 6, 6, 12, 30, 15, 0, time.UTC)

fmt.Println(IsWeekend(d))

Output:

true

func MiniDuration 

func MiniDuration(d time.Duration, separator ...string) string

MiniDuration returns formatted value of duration (d/hr/m/s/ms/us/ns)

Example 
fmt.Println(MiniDuration(36 * HOUR))
fmt.Println(MiniDuration(18 * time.Second))
fmt.Println(MiniDuration(time.Second / 125))

// You can remove or change separator
fmt.Println(MiniDuration(time.Second/2000, ""))

Output:

2 d
18 s
8 ms
500μs

func NextDay 

func NextDay(t time.Time) time.Time

NextDay returns next day date

Example 
d := time.Date(2021, 6, 1, 12, 30, 15, 0, time.UTC)

fmt.Println(NextDay(d))

Output:

2021-06-02 00:00:00 +0000 UTC

func NextMonth 

func NextMonth(t time.Time) time.Time

NextMonth returns next month date

Example 
d := time.Date(2021, 6, 1, 12, 30, 15, 0, time.UTC)

fmt.Println(NextMonth(d))

Output:

2021-07-01 00:00:00 +0000 UTC

func NextWeek added in v13.19.0 

func NextWeek(t time.Time, firstDay time.Weekday) time.Time

NextWeek returns next week date

Example 
d := time.Date(2021, 6, 1, 12, 30, 15, 0, time.UTC)

fmt.Println(NextWeek(d, time.Monday))

Output:

2021-06-07 00:00:00 +0000 UTC

func NextWeekend 

func NextWeekend(t time.Time) time.Time

NextWeekend returns next weekend

Example 
d := time.Date(2021, 6, 6, 12, 30, 15, 0, time.UTC)

fmt.Println(NextWeekend(d))

Output:

2021-06-12 00:00:00 +0000 UTC

func NextWorkday 

func NextWorkday(t time.Time) time.Time

NextWorkday returns next workday

Example 
d := time.Date(2021, 6, 6, 12, 30, 15, 0, time.UTC)

fmt.Println(NextWorkday(d))

Output:

2021-06-07 00:00:00 +0000 UTC

func NextYear 

func NextYear(t time.Time) time.Time

NextYear returns next year date

Example 
d := time.Date(2021, 6, 1, 12, 30, 15, 0, time.UTC)

fmt.Println(NextYear(d))

Output:

2022-01-01 00:00:00 +0000 UTC

func ParseDuration 

func ParseDuration(dur string, defMod ...rune) (time.Duration, error)

ParseDuration parses duration in 1w2d3h5m6s format and return as seconds

Example 
d, _ := ParseDuration("2w3d10h20m35s")

fmt.Println(PrettyDuration(d))

Output:

2 weeks 3 days 10 hours 20 minutes and 35 seconds

func PrettyDuration 

func PrettyDuration(d any) string

PrettyDuration returns pretty duration (e.g. 1 hour 45 seconds)

Example 
// you can use int/int64/uint as seconds...
fmt.Println(PrettyDuration(300))

// ...or time.Duration types
fmt.Println(PrettyDuration(123456 * time.Second))

Output:

5 minutes
1 day 10 hours 17 minutes and 36 seconds

func PrettyDurationInDays 

func PrettyDurationInDays(d any) string

PrettyDurationInDays returns pretty duration in days (e.g. 15 days)

Example 
fmt.Println(PrettyDurationInDays(2 * time.Hour))
fmt.Println(PrettyDurationInDays(168 * HOUR))

Output:

1 day
7 days

func PrettyDurationSimple 

func PrettyDurationSimple(d any) string

PrettyDurationSimple returns simple pretty duration (seconds → minutes → hours → days)

Example 
// you can use int/int64/uint as seconds...
fmt.Println(PrettyDurationSimple(300))

// ...or time.Duration types
fmt.Println(PrettyDurationSimple(50400 * time.Second))

Output:

5 minutes
14 hours

func PrevDay 

func PrevDay(t time.Time) time.Time

PrevDay returns previous day date

Example 
d := time.Date(2021, 6, 1, 12, 30, 15, 0, time.UTC)

fmt.Println(PrevDay(d))

Output:

2021-05-31 00:00:00 +0000 UTC

func PrevMonth 

func PrevMonth(t time.Time) time.Time

PrevMonth returns previous month date

Example 
d := time.Date(2021, 6, 1, 12, 30, 15, 0, time.UTC)

fmt.Println(PrevMonth(d))

Output:

2021-05-01 00:00:00 +0000 UTC

func PrevWeek added in v13.19.0 

func PrevWeek(t time.Time, firstDay time.Weekday) time.Time

PrevWeek returns previous week date

Example 
d := time.Date(2021, 6, 1, 12, 30, 15, 0, time.UTC)

fmt.Println(PrevWeek(d, time.Monday))

Output:

2021-05-24 00:00:00 +0000 UTC

func PrevWeekend 

func PrevWeekend(t time.Time) time.Time

NextWeekend returns previous weekend

Example 
d := time.Date(2021, 6, 6, 12, 30, 15, 0, time.UTC)

fmt.Println(PrevWeekend(d))

Output:

2021-06-05 00:00:00 +0000 UTC

func PrevWorkday 

func PrevWorkday(t time.Time) time.Time

NextWorkday returns previous workday

Example 
d := time.Date(2021, 6, 6, 12, 30, 15, 0, time.UTC)

fmt.Println(PrevWorkday(d))

Output:

2021-06-04 00:00:00 +0000 UTC

func PrevYear 

func PrevYear(t time.Time) time.Time

PrevYear returns previous year date

Example 
d := time.Date(2021, 6, 1, 12, 30, 15, 0, time.UTC)

fmt.Println(PrevYear(d))

Output:

2020-01-01 00:00:00 +0000 UTC

func SecondsToDuration 

func SecondsToDuration(d float64) time.Duration

SecondsToDuration converts float64 to time.Duration

Example 
fmt.Println(SecondsToDuration(3600))

Output:

1h0m0s

func ShortDuration 

func ShortDuration(d any, highPrecision ...bool) string

ShortDuration returns pretty short duration (e.g. 1:37)

Example 
fmt.Println(ShortDuration(time.Second * 85))
fmt.Println(ShortDuration(3215*time.Millisecond, true))

Output:

1:25
0:03.215

func Since added in v13.20.0 

func Since(t time.Time, unit time.Duration) int

Since returns time since given moment in given units

Example 
d := time.Date(2012, 6, 6, 12, 30, 15, 0, time.UTC)

fmt.Println(Since(d, DAY))

Output:

func StartOfDay 

func StartOfDay(t time.Time) time.Time

StartOfDay returns start of the day

Example 
d := time.Date(2021, 6, 15, 12, 30, 15, 0, time.UTC)

fmt.Println(StartOfDay(d))

Output:

2021-06-15 00:00:00 +0000 UTC

func StartOfHour 

func StartOfHour(t time.Time) time.Time

StartOfHour returns start of the hour

Example 
d := time.Date(2021, 6, 15, 12, 30, 15, 0, time.UTC)

fmt.Println(StartOfHour(d))

Output:

2021-06-15 12:00:00 +0000 UTC

func StartOfMonth 

func StartOfMonth(t time.Time) time.Time

StartOfMonth returns the first day of the month

Example 
d := time.Date(2021, 6, 15, 12, 30, 15, 0, time.UTC)

fmt.Println(StartOfMonth(d))

Output:

2021-06-01 00:00:00 +0000 UTC

func StartOfWeek 

func StartOfWeek(t time.Time, firstDay time.Weekday) time.Time

StartOfWeek returns the first day of the week

Example 
d := time.Date(2021, 6, 15, 12, 30, 15, 0, time.UTC)

fmt.Println(StartOfWeek(d, time.Monday))

Output:

2021-06-14 00:00:00 +0000 UTC

func StartOfYear 

func StartOfYear(t time.Time) time.Time

StartOfYear returns the first day of the year

Example 
d := time.Date(2021, 6, 15, 12, 30, 15, 0, time.UTC)

fmt.Println(StartOfYear(d))

Output:

2021-01-01 00:00:00 +0000 UTC

func Until added in v13.16.0 

func Until(t time.Time, unit time.Duration) int

Until returns time until given moment in given units

Example 
d := time.Date(2030, 6, 6, 12, 30, 15, 0, time.UTC)

fmt.Println(Until(d, DAY))

Output:

Types

type Date 

type Date uint32

Date is tiny date

Example 
StartDate = 1577836800

t := int64(1583020800)
d := TinyDate(t)

fmt.Println(t)
fmt.Println(d)

Output:

1583020800
5184000

func TinyDate 

func TinyDate(t int64) Date

TinyDate creates tiny date struct by timestamp

func (Date) Time 

func (d Date) Time() time.Time

Time returns time struct

Example 
StartDate = 1577836800

d := TinyDate(1583020800)

fmt.Println(d.Time().In(time.UTC))

Output:

2020-03-01 00:00:00 +0000 UTC

func (Date) Unix 

func (d Date) Unix() int64

Unix returns unix timestamp

Example 
StartDate = 1577836800

d := TinyDate(1583020800)

fmt.Println(d.Unix())

Output:

1583020800

type Period added in v13.20.0 

type Period struct {
	Start time.Time
	End   time.Time
}

Period is a struct with the start and end date of the period

func (Period) Contains added in v13.20.0 

func (p Period) Contains(t time.Time) bool

Contains returns true if period contains given date

Example 
p := Period{
	time.Date(2021, 1, 1, 12, 30, 15, 0, time.Local),
	time.Date(2023, 6, 15, 18, 45, 30, 0, time.Local),
}

d := time.Date(2021, 1, 1, 12, 30, 16, 0, time.Local)

fmt.Printf("Period contains date: %t\n", p.Contains(d))

Output:

Period contains date: true

func (Period) Days added in v13.20.0 

func (p Period) Days() int

Days returns duration in days

Example 
p := Period{
	time.Date(2021, 1, 1, 12, 30, 15, 0, time.Local),
	time.Date(2021, 6, 15, 14, 15, 45, 0, time.Local),
}

fmt.Printf("Period duration: %d\n", p.Days())

Output:

Period duration: 165

func (Period) Duration added in v13.20.0 

func (p Period) Duration() time.Duration

Duration returns duration of period

Example 
p := Period{
	time.Date(2021, 1, 1, 12, 30, 15, 0, time.Local),
	time.Date(2021, 1, 1, 14, 15, 45, 0, time.Local),
}

fmt.Printf("Period duration: %s\n", p.Duration())

Output:

Period duration: 1h45m30s

func (Period) DurationAs added in v13.20.2 

func (p Period) DurationAs(unit time.Duration) int

DurationAs returns duration of period in given units

Example 
p := Period{
	time.Date(2021, 1, 1, 12, 30, 15, 0, time.Local),
	time.Date(2021, 6, 15, 14, 15, 45, 0, time.Local),
}

fmt.Printf("Period duration (hours): %d\n", p.DurationAs(HOUR))
fmt.Printf("Period duration (days): %d\n", p.DurationAs(DAY))
fmt.Printf("Period duration (weeks): %d\n", p.DurationAs(WEEK))

Output:

Period duration (hours): 3962
Period duration (days): 165
Period duration (weeks): 24

func (Period) Hours added in v13.20.0 

func (p Period) Hours() int

Hours returns duration in hours

Example 
p := Period{
	time.Date(2021, 1, 1, 12, 30, 15, 0, time.Local),
	time.Date(2021, 6, 15, 14, 15, 45, 0, time.Local),
}

fmt.Printf("Period duration: %d\n", p.Hours())

Output:

Period duration: 3962

func (Period) Minutes added in v13.20.0 

func (p Period) Minutes() int

Minutes returns duration in minutes

Example 
p := Period{
	time.Date(2021, 1, 1, 12, 30, 15, 0, time.Local),
	time.Date(2021, 6, 15, 14, 15, 45, 0, time.Local),
}

fmt.Printf("Period duration: %d\n", p.Minutes())

Output:

Period duration: 237706

func (Period) Seconds added in v13.20.0 

func (p Period) Seconds() int

Seconds returns duration in seconds

Example 
p := Period{
	time.Date(2021, 1, 1, 12, 30, 15, 0, time.Local),
	time.Date(2021, 6, 15, 14, 15, 45, 0, time.Local),
}

fmt.Printf("Period duration: %d\n", p.Seconds())

Output:

Period duration: 14262330

func (Period) String added in v13.20.0 

func (p Period) String() string

String returns string representation of period

Example 
p := Period{
	time.Date(2021, 1, 1, 12, 30, 15, 0, time.Local),
	time.Date(2021, 1, 1, 14, 15, 45, 0, time.Local),
}

fmt.Println(p)

Output:

2021/01/01 12:30:15 → 2021/01/01 14:15:45

func (Period) Stringf added in v13.20.2 

func (p Period) Stringf(f string) string

Stringf returns string representation of period using given format

Example 
p := Period{
	time.Date(2021, 1, 1, 12, 30, 15, 0, time.Local),
	time.Date(2021, 1, 1, 14, 15, 45, 0, time.Local),
}

fmt.Println(p.Stringf(`%H:%M`))

Output:

12:30 → 14:15

func (Period) Weeks added in v13.20.0 

func (p Period) Weeks() int

Weeks returns duration in weeks

Example 
p := Period{
	time.Date(2021, 1, 1, 12, 30, 15, 0, time.Local),
	time.Date(2021, 6, 15, 14, 15, 45, 0, time.Local),
}

fmt.Printf("Period duration: %d\n", p.Weeks())

Output:

Period duration: 24

func (Period) Years added in v13.20.0 

func (p Period) Years() int

Years returns duration in years

Example 
p := Period{
	time.Date(2021, 1, 1, 12, 30, 15, 0, time.Local),
	time.Date(2024, 6, 15, 14, 15, 45, 0, time.Local),
}

fmt.Printf("Period duration: %d\n", p.Years())

Output:

Period duration: 3

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.