datetime

package
v2.3.8 Latest Latest
Warning

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

 Go to latest Published: Nov 1, 2025 License: MIT Imports: 4 Imported by: 36

Documentation

Overview

Package datetime implements some functions to format date and time. Note: 1. `format` param in FormatTimeToStr function should be as flow (case no sensitive): "yyyy-mm-dd hh:mm:ss" "yyyy-mm-dd hh:mm" "yyyy-mm-dd hh" "yyyy-mm-dd" "yyyy-mm" "mm-dd" "dd-mm-yy hh:mm:ss" "yyyy/mm/dd hh:mm:ss" "yyyy/mm/dd hh:mm" "yyyy/mm/dd hh" "yyyy/mm/dd" "yyyy/mm" "mm/dd" "dd/mm/yy hh:mm:ss" "yyyymmdd" "mmddyy" "yyyy" "yy" "mm" "hh:mm:ss" "hh:mm" "mm:ss"

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddDay 

func AddDay(t time.Time, days int64) time.Time

AddDay add or sub days to the time. Play: https://go.dev/play/p/dIGbs_uTdFa

Example 
date, _ := time.Parse("2006-01-02 15:04:05", "2021-01-01 00:00:00")

after1Day := AddDay(date, 1)
before1Day := AddDay(date, -1)

fmt.Println(after1Day.Format("2006-01-02 15:04:05"))
fmt.Println(before1Day.Format("2006-01-02 15:04:05"))

Output:

2021-01-02 00:00:00
2020-12-31 00:00:00

func AddDaySafe added in v2.3.5 

func AddDaySafe(t time.Time, days int) time.Time

AddDaySafe add or sub days to the time and ensure that the returned date does not exceed the valid date of the target year and month. Play: https://go.dev/play/p/JTohZFpoDJ3

Example 
leapYearDate1, _ := time.Parse("2006-01-02", "2024-02-29")
result1 := AddDaySafe(leapYearDate1, 1)

leapYearDate2, _ := time.Parse("2006-01-02", "2024-03-01")
result2 := AddDaySafe(leapYearDate2, -1)

nonLeapYearDate1, _ := time.Parse("2006-01-02", "2025-02-28")
result3 := AddDaySafe(nonLeapYearDate1, 1)

nonLeaYearDate2, _ := time.Parse("2006-01-02", "2025-03-01")
result4 := AddDaySafe(nonLeaYearDate2, -1)

fmt.Println(result1.Format("2006-01-02"))
fmt.Println(result2.Format("2006-01-02"))
fmt.Println(result3.Format("2006-01-02"))
fmt.Println(result4.Format("2006-01-02"))

Output:

2024-03-01
2024-02-29
2025-03-01
2025-02-28

func AddHour 

func AddHour(t time.Time, hours int64) time.Time

AddHour add or sub hours to the time. Play: https://go.dev/play/p/rcMjd7OCsi5

Example 
date, _ := time.Parse("2006-01-02 15:04:05", "2021-01-01 00:00:00")

after2Hours := AddHour(date, 2)
before2Hours := AddHour(date, -2)

fmt.Println(after2Hours.Format("2006-01-02 15:04:05"))
fmt.Println(before2Hours.Format("2006-01-02 15:04:05"))

Output:

2021-01-01 02:00:00
2020-12-31 22:00:00

func AddMinute 

func AddMinute(t time.Time, minutes int64) time.Time

AddMinute add or sub minutes to the time. Play: https://go.dev/play/p/nT1heB1KUUK

Example 
date, _ := time.Parse("2006-01-02 15:04:05", "2021-01-01 00:00:00")

after2Minutes := AddMinute(date, 2)
before2Minutes := AddMinute(date, -2)

fmt.Println(after2Minutes.Format("2006-01-02 15:04:05"))
fmt.Println(before2Minutes.Format("2006-01-02 15:04:05"))

Output:

2021-01-01 00:02:00
2020-12-31 23:58:00

func AddMonth added in v2.3.5 

func AddMonth(t time.Time, months int64) time.Time

AddMonth add or sub months to the time. Play: https://go.dev/play/p/DLoiOnpLvsN

Example 
date, _ := time.Parse("2006-01-02", "2021-01-01")

after2Months := AddMonth(date, 2)
before2Months := AddMonth(date, -2)

fmt.Println(after2Months.Format("2006-01-02"))
fmt.Println(before2Months.Format("2006-01-02"))

Output:

2021-03-01
2020-11-01

func AddMonthSafe added in v2.3.5 

func AddMonthSafe(t time.Time, months int) time.Time

AddMonthSafe add or sub months to the time and ensure that the returned date does not exceed the valid date of the target year and month. Play: https://go.dev/play/p/KLw0lo6mbVW

Example 
date1, _ := time.Parse("2006-01-02", "2025-01-31")
result1 := AddMonthSafe(date1, 1)

date2, _ := time.Parse("2006-01-02", "2024-02-29")
result2 := AddMonthSafe(date2, -1)

fmt.Println(result1.Format("2006-01-02"))
fmt.Println(result2.Format("2006-01-02"))

Output:

2025-02-28
2024-01-29

func AddWeek added in v2.3.5 

func AddWeek(t time.Time, weeks int64) time.Time

AddWeek add or sub weeks to the time. play: https://go.dev/play/p/M9TqdMiaA2p

Example 
date, _ := time.Parse("2006-01-02", "2021-01-01")

after2Weeks := AddWeek(date, 2)
before2Weeks := AddWeek(date, -2)

fmt.Println(after2Weeks.Format("2006-01-02"))
fmt.Println(before2Weeks.Format("2006-01-02"))

Output:

2021-01-15
2020-12-18

func AddYear added in v2.2.0 

func AddYear(t time.Time, year int64) time.Time

AddYear add or sub year to the time. Play: https://go.dev/play/p/MqW2ujnBx10

Example 
date, _ := time.Parse("2006-01-02", "2021-01-01")

after2Years := AddYear(date, 2)
before2Years := AddYear(date, -2)

fmt.Println(after2Years.Format("2006-01-02"))
fmt.Println(before2Years.Format("2006-01-02"))

Output:

2023-01-01
2019-01-01

func AddYearSafe added in v2.3.5 

func AddYearSafe(t time.Time, years int) time.Time

AddYearSafe add or sub years to the time and ensure that the returned date does not exceed the valid date of the target year and month. Play: https://go.dev/play/p/KVGXWZZ54ZH

Example 
date, _ := time.Parse("2006-01-02", "2020-02-29")

result1 := AddYearSafe(date, 1)
result2 := AddYearSafe(date, -1)

fmt.Println(result1.Format("2006-01-02"))
fmt.Println(result2.Format("2006-01-02"))

Output:

2021-02-28
2019-02-28

func BeginOfDay 

func BeginOfDay(t time.Time) time.Time

BeginOfDay return beginning hour time of day. Play: https://go.dev/play/p/94m_UT6cWs9

Example 
input := time.Date(2023, 1, 8, 18, 50, 10, 100, time.UTC)

result := BeginOfDay(input)

fmt.Println(result)

Output:

2023-01-08 00:00:00 +0000 UTC

func BeginOfHour 

func BeginOfHour(t time.Time) time.Time

BeginOfHour return beginning hour time of day. Play: https://go.dev/play/p/GhdGFnDWpYs

Example 
input := time.Date(2023, 1, 8, 18, 50, 10, 100, time.UTC)

result := BeginOfHour(input)

fmt.Println(result)

Output:

2023-01-08 18:00:00 +0000 UTC

func BeginOfMinute 

func BeginOfMinute(t time.Time) time.Time

BeginOfMinute return beginning minute time of day. Play: https://go.dev/play/p/ieOLVJ9CiFT

Example 
input := time.Date(2023, 1, 8, 18, 50, 10, 100, time.UTC)

result := BeginOfMinute(input)

fmt.Println(result)

Output:

2023-01-08 18:50:00 +0000 UTC

func BeginOfMonth 

func BeginOfMonth(t time.Time) time.Time

BeginOfMonth return beginning of month. Play: https://go.dev/play/p/bWXVFsmmzwL

Example 
input := time.Date(2023, 1, 8, 18, 50, 10, 100, time.UTC)

result := BeginOfMonth(input)

fmt.Println(result)

Output:

2023-01-01 00:00:00 +0000 UTC

func BeginOfWeek 

func BeginOfWeek(t time.Time, beginFrom time.Weekday) time.Time

BeginOfWeek return beginning week, default week begin from Sunday. Play: https://go.dev/play/p/DCHdcL6gnfV

Example 
input := time.Date(2023, 1, 8, 18, 50, 10, 100, time.UTC)

result := BeginOfWeek(input, time.Monday)

fmt.Println(result)

Output:

2023-01-02 00:00:00 +0000 UTC

func BeginOfYear 

func BeginOfYear(t time.Time) time.Time

BeginOfYear return the date time at the begin of year. Play: https://go.dev/play/p/i326DSwLnV8

Example 
input := time.Date(2023, 1, 8, 18, 50, 10, 100, time.UTC)

result := BeginOfYear(input)

fmt.Println(result)

Output:

2023-01-01 00:00:00 +0000 UTC

func BetweenSeconds added in v2.2.1 

func BetweenSeconds(t1 time.Time, t2 time.Time) int64

BetweenSeconds returns the number of seconds between two times. Play: https://go.dev/play/p/n3YDRyfyXJu

Example 
today := time.Now()
tomorrow := AddDay(today, 1)
yesterday := AddDay(today, -1)

result1 := BetweenSeconds(today, tomorrow)
result2 := BetweenSeconds(today, yesterday)

fmt.Println(result1)
fmt.Println(result2)

Output:

86400
-86400

func DayOfYear added in v2.2.1 

func DayOfYear(t time.Time) int

DayOfYear returns which day of the year the parameter date `t` is. Play: https://go.dev/play/p/0hjqhTwFNlH

Example 
date1 := time.Date(2023, 02, 01, 1, 1, 1, 0, time.Local)
result1 := DayOfYear(date1)

date2 := time.Date(2023, 01, 02, 1, 1, 1, 0, time.Local)
result2 := DayOfYear(date2)

date3 := time.Date(2023, 01, 01, 1, 1, 1, 0, time.Local)
result3 := DayOfYear(date3)

fmt.Println(result1)
fmt.Println(result2)
fmt.Println(result3)

Output:

31
1
0

func DaysBetween added in v2.3.3 

func DaysBetween(start, end time.Time) int

DaysBetween returns the number of days between two times. Play: https://go.dev/play/p/qD6qGb3TbOy

Example 
start := time.Date(2024, time.September, 1, 0, 0, 0, 0, time.UTC)
end := time.Date(2024, time.September, 10, 0, 0, 0, 0, time.UTC)

result := DaysBetween(start, end)

fmt.Println(result)

Output:

9

func EndOfDay 

func EndOfDay(t time.Time) time.Time

EndOfDay return end time of day. Play: https://go.dev/play/p/eMBOvmq5Ih1

Example 
input := time.Date(2023, 1, 8, 18, 50, 10, 100, time.UTC)

result := EndOfDay(input)

fmt.Println(result)

Output:

2023-01-08 23:59:59.999999999 +0000 UTC

func EndOfHour 

func EndOfHour(t time.Time) time.Time

EndOfHour return end hour time of day. Play: https://go.dev/play/p/6ce3j_6cVqN

Example 
input := time.Date(2023, 1, 8, 18, 50, 10, 100, time.UTC)

result := EndOfHour(input)

fmt.Println(result)

Output:

2023-01-08 18:59:59.999999999 +0000 UTC

func EndOfMinute 

func EndOfMinute(t time.Time) time.Time

EndOfMinute return end minute time of day. Play: https://go.dev/play/p/yrL5wGzPj4z

Example 
input := time.Date(2023, 1, 8, 18, 50, 10, 100, time.UTC)

result := EndOfMinute(input)

fmt.Println(result)

Output:

2023-01-08 18:50:59.999999999 +0000 UTC

func EndOfMonth 

func EndOfMonth(t time.Time) time.Time

EndOfMonth return end of month. Play: https://go.dev/play/p/_GWh10B3Nqi

Example 
input := time.Date(2023, 1, 8, 18, 50, 10, 100, time.UTC)

result := EndOfMonth(input)

fmt.Println(result)

Output:

2023-01-31 23:59:59.999999999 +0000 UTC

func EndOfWeek 

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

EndOfWeek return end week time, default week end with Saturday. Play: https://go.dev/play/p/mGSA162YgX9

Example 
input := time.Date(2023, 1, 8, 18, 50, 10, 100, time.UTC)

result := EndOfWeek(input, time.Sunday)

fmt.Println(result)

Output:

2023-01-08 23:59:59.999999999 +0000 UTC

func EndOfYear 

func EndOfYear(t time.Time) time.Time

EndOfYear return the date time at the end of year. Play: https://go.dev/play/p/G01cKlMCvNm

Example 
input := time.Date(2023, 1, 8, 18, 50, 10, 100, time.UTC)

result := EndOfYear(input)

fmt.Println(result)

Output:

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

func FormatStrToTime 

func FormatStrToTime(str, format string, timezone ...string) (time.Time, error)

FormatStrToTime convert string to time. Play: https://go.dev/play/p/1h9FwdU8ql4

Example 
result1, _ := FormatStrToTime("2021-01-02 16:04:08", "yyyy-mm-dd hh:mm:ss")
result2, _ := FormatStrToTime("2021-01-02", "yyyy-mm-dd")
result3, _ := FormatStrToTime("02-01-21 16:04:08", "dd-mm-yy hh:mm:ss")

fmt.Println(result1)
fmt.Println(result2)
fmt.Println(result3)

Output:

2021-01-02 16:04:08 +0000 UTC
2021-01-02 00:00:00 +0000 UTC
2021-01-02 16:04:08 +0000 UTC

func FormatTimeToStr 

func FormatTimeToStr(t time.Time, format string, timezone ...string) string

FormatTimeToStr convert time to string. Play: https://go.dev/play/p/_Ia7M8H_OvE

Example 
datetime, _ := time.Parse("2006-01-02 15:04:05", "2021-01-02 16:04:08")

result1 := FormatTimeToStr(datetime, "yyyy-mm-dd hh:mm:ss")
result2 := FormatTimeToStr(datetime, "yyyy-mm-dd")
result3 := FormatTimeToStr(datetime, "dd-mm-yy hh:mm:ss")
result4 := FormatTimeToStr(datetime, "yyyy-mm-dd hh")

fmt.Println(result1)
fmt.Println(result2)
fmt.Println(result3)
fmt.Println(result4)

Output:

2021-01-02 16:04:08
2021-01-02
02-01-21 16:04:08
2021-01-02 16

func GenerateDatetimesBetween added in v2.3.3 

func GenerateDatetimesBetween(start, end time.Time, layout string, interval string) ([]string, error)

GenerateDatetimesBetween returns a slice of strings between two times. layout: the format of the datetime string interval: the interval between two datetimes Play: https://go.dev/play/p/6kHBpAxD9ZC

Example 
start := time.Date(2024, time.September, 1, 0, 0, 0, 0, time.UTC)
end := time.Date(2024, time.September, 1, 2, 0, 0, 0, time.UTC)

layout := "2006-01-02 15:04:05"
interval := "1h"

result, err := GenerateDatetimesBetween(start, end, layout, interval)

fmt.Println(result)
fmt.Println(err)

Output:

[2024-09-01 00:00:00 2024-09-01 01:00:00 2024-09-01 02:00:00]
<nil>

func GetNightTimestamp 

func GetNightTimestamp() int64

GetNightTimestamp return timestamp of zero hour (timestamp of 23:59). Play: https://go.dev/play/p/UolysR3MYP1

func GetNowDate 

func GetNowDate() string

GetNowDate return format yyyy-mm-dd of current date. Play: https://go.dev/play/p/PvfkPpcpBBf

Example 
result := GetNowDate()

expected := time.Now().Format("2006-01-02")

fmt.Println(result == expected)

Output:

true

func GetNowDateTime 

func GetNowDateTime() string

GetNowDateTime return format yyyy-mm-dd hh-mm-ss of current datetime. Play: https://go.dev/play/p/pI4AqngD0al

Example 
result := GetNowDateTime()

expected := time.Now().Format("2006-01-02 15:04:05")

fmt.Println(result == expected)

Output:

true

func GetNowTime 

func GetNowTime() string

GetNowTime return format hh-mm-ss of current time. Play: https://go.dev/play/p/l7BNxCkTmJS

Example 
result := GetNowTime()

expected := time.Now().Format("15:04:05")

fmt.Println(result == expected)

Output:

true

func GetTodayEndTime added in v2.2.3 

func GetTodayEndTime() string

GetTodayEndTime return the end time of today, format: yyyy-mm-dd 23:59:59. Play: https://go.dev/play/p/jjrLnfoqgn3

func GetTodayStartTime added in v2.2.3 

func GetTodayStartTime() string

GetTodayStartTime return the start time of today, format: yyyy-mm-dd 00:00:00. Play: https://go.dev/play/p/84siyYF7t99

func GetZeroHourTimestamp 

func GetZeroHourTimestamp() int64

GetZeroHourTimestamp return timestamp of zero hour (timestamp of 00:00). Play: https://go.dev/play/p/QmL2oIaGE3q

func IsLeapYear added in v2.2.0 

func IsLeapYear(year int) bool

IsLeapYear check if param year is leap year or not. Play: https://go.dev/play/p/xS1eS2ejGew

Example 
result1 := IsLeapYear(2000)
result2 := IsLeapYear(2001)

fmt.Println(result1)
fmt.Println(result2)

Output:

true
false

func IsWeekend added in v2.2.1 

func IsWeekend(t time.Time) bool

IsWeekend checks if passed time is weekend or not. Play: https://go.dev/play/p/cupRM5aZOIY Deprecated Use '== Weekday' instead

Example 
date1 := time.Date(2023, 06, 03, 0, 0, 0, 0, time.Local)
date2 := time.Date(2023, 06, 04, 0, 0, 0, 0, time.Local)
date3 := time.Date(2023, 06, 02, 0, 0, 0, 0, time.Local)

result1 := IsWeekend(date1)
result2 := IsWeekend(date2)
result3 := IsWeekend(date3)

fmt.Println(result1)
fmt.Println(result2)
fmt.Println(result3)

Output:

true
true
false

func Max added in v2.3.4 

func Max(t1 time.Time, times ...time.Time) time.Time

Max returns the latest time among the given times. Play: https://go.dev/play/p/9m6JMk1LB7-

Example 
result := Max(time.Date(2024, time.September, 1, 0, 0, 0, 0, time.UTC), time.Date(2024, time.September, 2, 0, 0, 0, 0, time.UTC))

fmt.Println(result)

Output:

2024-09-02 00:00:00 +0000 UTC

func MaxMin added in v2.3.4 

func MaxMin(t1 time.Time, times ...time.Time) (maxTime time.Time, minTime time.Time)

MaxMin returns the latest and earliest time among the given times. Play: https://go.dev/play/p/rbW51cDtM_2

Example 
max, min := MaxMin(time.Date(2024, time.September, 1, 0, 0, 0, 0, time.UTC), time.Date(2024, time.September, 2, 0, 0, 0, 0, time.UTC), time.Date(2024, time.September, 3, 0, 0, 0, 0, time.UTC))

fmt.Println(max)
fmt.Println(min)

Output:

2024-09-03 00:00:00 +0000 UTC
2024-09-01 00:00:00 +0000 UTC

func Min added in v2.3.4 

func Min(t1 time.Time, times ...time.Time) time.Time

Min returns the earliest time among the given times. Play: https://go.dev/play/p/MCIDvHNOGGb

Example 
result := Min(time.Date(2024, time.September, 1, 0, 0, 0, 0, time.UTC), time.Date(2024, time.September, 2, 0, 0, 0, 0, time.UTC))

fmt.Println(result)

Output:

2024-09-01 00:00:00 +0000 UTC

func NewFormat added in v2.0.1 

func NewFormat(t string) (*theTime, error)

NewFormat return unix timestamp of specified time string, t should be "yyyy-mm-dd hh:mm:ss". Play: https://go.dev/play/p/VkW08ZOaXPZ

func NewISO8601 added in v2.0.1 

func NewISO8601(iso8601 string) (*theTime, error)

NewISO8601 return unix timestamp of specified iso8601 time string. Play: https://go.dev/play/p/mkhOHQkdeA2

func NewUnix added in v2.0.1 

func NewUnix(unix int64) *theTime

NewUnix return unix timestamp of specified time. Play: https://go.dev/play/p/psoSuh_kLRt

Example 
result := NewUnix(1647597438)

fmt.Println(result)

Output:

&{1647597438}

func NewUnixNow added in v2.0.1 

func NewUnixNow() *theTime

NewUnixNow return unix timestamp of current time. Play: https://go.dev/play/p/U4PPx-9D0oz

Example 
tm1 := NewUnixNow()

unixTimestamp := tm1.ToUnix()

tm2 := NewUnix(unixTimestamp)

fmt.Println(reflect.DeepEqual(tm1, tm2))

Output:

true

func NowDateOrTime added in v2.2.4 

func NowDateOrTime(format string, timezone ...string) string

NowDateOrTime return current datetime with specific format and timezone. Play: https://go.dev/play/p/EZ-begEjtT0

func Timestamp added in v2.2.4 

func Timestamp(timezone ...string) int64

Timestamp return current second timestamp. Play: https://go.dev/play/p/iU5b7Vvjx6x

func TimestampMicro added in v2.2.4 

func TimestampMicro(timezone ...string) int64

TimestampMicro return current micro second timestamp. Play: https://go.dev/play/p/2maANglKHQE

func TimestampMilli added in v2.2.4 

func TimestampMilli(timezone ...string) int64

TimestampMilli return current mill second timestamp. Play: https://go.dev/play/p/4gvEusOTu1T

func TimestampNano added in v2.2.4 

func TimestampNano(timezone ...string) int64

TimestampNano return current nano second timestamp. Play: https://go.dev/play/p/A9Oq_COrcCF

func TrackFuncTime added in v2.3.3 

func TrackFuncTime(pre time.Time) func()

TrackFuncTime track the time of function execution. call it at top of the func like `defer TrackFuncTime(time.Now())()` Play: https://go.dev/play/p/QBSEdfXHPTp

Types

This section is empty.

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.