datetime.md

Datetime

Package datetime supports date and time format and compare.

Source:

• https://github.com/duke-git/lancet/blob/main/datetime/datetime.go
• https://github.com/duke-git/lancet/blob/main/datetime/conversion.go

Usage:

import (
    "github.com/duke-git/lancet/v2/datetime"
)

Index

• AddDay
• AddHour
• AddMinute
• BeginOfMinute
• BeginOfHour
• BeginOfDay
• BeginOfWeek
• BeginOfMonth
• BeginOfYear
• EndOfMinute
• EndOfHour
• EndOfDay
• EndOfWeek
• EndOfMonth
• EndOfYear
• GetNowDate
• GetNowTime
• GetNowDateTime
• GetZeroHourTimestamp
• GetNightTimestamp
• FormatTimeToStr
• FormatStrToTime
• NewUnixNow
• NewUnix
• NewFormat
• NewISO8601
• ToUnix
• ToFormat
• ToFormatForTpl
• ToIso8601

Documentation

Note:

1. 'format' string param in func FormatTimeToStr and FormatStrToTime function should be one of flows:

• 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
• yyyy
• mm
• hh:mm:ss
• mm:ss

AddDay

Add or sub days to time.

Signature:

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

Example:

package main

import (
    "fmt"
    "time"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    now := time.Now()

    tomorrow := datetime.AddDay(now, 1)
    diff1 := tomorrow.Sub(now)

    yesterday := datetime.AddDay(now, -1)
    diff2 := yesterday.Sub(now)

    fmt.Println(diff1)
    fmt.Println(diff2)

    // Output:
    // 24h0m0s
    // -24h0m0s
}

AddHour

Add or sub hours to time.

Signature:

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

Example:

package main

import (
    "fmt"
    "time"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    now := time.Now()

    after2Hours := datetime.AddHour(now, 2)
    diff1 := after2Hours.Sub(now)

    before2Hours := datetime.AddHour(now, -2)
    diff2 := before2Hours.Sub(now)

    fmt.Println(diff1)
    fmt.Println(diff2)

    // Output:
    // 2h0m0s
    // -2h0m0s
}

AddMinute

Add or sub minutes to time.

Signature:

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

Example:

package main

import (
    "fmt"
    "time"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    now := time.Now()

    after2Minutes := datetime.AddMinute(now, 2)
    diff1 := after2Minutes.Sub(now)

    before2Minutes := datetime.AddMinute(now, -2)
    diff2 := before2Minutes.Sub(now)

    fmt.Println(diff1)
    fmt.Println(diff2)

    // Output:
    // 2m0s
    // -2m0s
}

BeginOfMinute

Return beginning minute time of day.

Signature:

func BeginOfMinute(t time.Time) time.Time

Example:

package main

import (
    "fmt"
    "time"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    input := time.Date(2023, 1, 8, 18, 50, 10, 100, time.UTC)
    result := datetime.BeginOfMinute(input)

    fmt.Println(result)

    // Output:
    // 2023-01-08 18:50:00 +0000 UTC
}

BeginOfHour

Return zero time of day.

Signature:

func BeginOfHour(t time.Time) time.Time

Example:

package main

import (
    "fmt"
    "time"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    input := time.Date(2023, 1, 8, 18, 50, 10, 100, time.UTC)
    result := datetime.BeginOfHour(input)

    fmt.Println(result)

    // Output:
    // 2023-01-08 18:00:00 +0000 UTC
}

BeginOfDay

Return begin time of day.

Signature:

func BeginOfDay(t time.Time) time.Time

Example:

package main

import (
    "fmt"
    "time"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    input := time.Date(2023, 1, 8, 18, 50, 10, 100, time.UTC)
    result := datetime.BeginOfDay(input)

    fmt.Println(result)

    // Output:
    // 2023-01-08 00:00:00 +0000 UTC
}

BeginOfWeek

Return beginning time of week, week begin from Sunday.

Signature:

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

Example:

package main

import (
    "fmt"
    "time"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    input := time.Date(2023, 1, 8, 18, 50, 10, 100, time.UTC)
    result := datetime.BeginOfWeek(input)

    fmt.Println(result)

    // Output:
    // 2023-01-08 00:00:00 +0000 UTC
}

BeginOfMonth

Return beginning time of month

Signature:

func BeginOfMonth(t time.Time) time.Time

Example:

package main

import (
    "fmt"
    "time"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    input := time.Date(2023, 1, 8, 18, 50, 10, 100, time.UTC)
    result := datetime.BeginOfMonth(input)

    fmt.Println(result)

    // Output:
    // 2023-01-01 00:00:00 +0000 UTC
}

BeginOfYear

Return beginning time of year.

Signature:

func BeginOfYear(t time.Time) time.Time

Example:

package main

import (
    "fmt"
    "time"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    input := time.Date(2023, 1, 8, 18, 50, 10, 100, time.UTC)
    result := datetime.BeginOfYear(input)

    fmt.Println(result)

    // Output:
    // 2023-01-01 00:00:00 +0000 UTC
}

EndOfMinute

Return end time minute of day.

Signature:

func EndOfMinute(t time.Time) time.Time

Example:

package main

import (
    "fmt"
    "time"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    input := time.Date(2023, 1, 8, 18, 50, 10, 100, time.UTC)
    result := datetime.EndOfMinute(input)

    fmt.Println(result)

    // Output:
    // 2023-01-08 18:50:59.999999999 +0000 UTC
}

EndOfHour

Return end time hour of day.

Signature:

func EndOfHour(t time.Time) time.Time

Example:

package main

import (
    "fmt"
    "time"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    input := time.Date(2023, 1, 8, 18, 50, 10, 100, time.UTC)
    result := datetime.EndOfHour(input)

    fmt.Println(result)

    // Output:
    // 2023-01-08 18:59:59.999999999 +0000 UTC
}

EndOfDay

Return end time hour of day.

Signature:

func EndOfDay(t time.Time) time.Time

Example:

package main

import (
    "fmt"
    "time"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    input := time.Date(2023, 1, 8, 18, 50, 10, 100, time.UTC)
    result := datetime.EndOfDay(input)

    fmt.Println(result)

    // Output:
    // 2023-01-08 23:59:59.999999999 +0000 UTC
}

EndOfWeek

Return end time of week, week end with Saturday.

Signature:

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

Example:

package main

import (
    "fmt"
    "time"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    input := time.Date(2023, 1, 8, 18, 50, 10, 100, time.UTC)
    result := datetime.EndOfWeek(input)

    fmt.Println(result)

    // Output:
    // 2023-01-14 23:59:59.999999999 +0000 UTC
}

EndOfMonth

Return end time of month

Signature:

func EndOfMonth(t time.Time) time.Time

Example:

package main

import (
    "fmt"
    "time"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    input := time.Date(2023, 1, 8, 18, 50, 10, 100, time.UTC)
    result := datetime.EndOfMonth(input)

    fmt.Println(result)

    // Output:
    // 2023-01-31 23:59:59.999999999 +0000 UTC
}

EndOfYear

Return beginning time of year.

Signature:

func EndOfYear(t time.Time) time.Time

Example:

package main

import (
    "fmt"
    "time"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    input := time.Date(2023, 1, 8, 18, 50, 10, 100, time.UTC)
    result := datetime.EndOfYear(input)

    fmt.Println(result)

    // Output:
    // 2023-12-31 23:59:59.999999999 +0000 UTC
}

GetNowDate

Get current date string, format is yyyy-mm-dd.

Signature:

func GetNowDate() string

Example:

package main

import (
    "fmt"
    "time"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    now := time.Now()
    currentDate := datetime.GetNowDate()

    fmt.Println(currentDate) 
    
    // Output:
    // 2022-01-28
}

GetNowTime

Get current time string, format is hh:mm:ss.

Signature:

func GetNowTime() string

Example:

package main

import (
    "fmt"
    "time"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    now := time.Now()
    currentTime := datetime.GetNowTime()

    fmt.Println(currentTime) // 15:57:33

    // Output:
    // 15:57:33
}

GetNowDateTime

Get current date time string, format is yyyy-mm-dd hh:mm:ss.

Signature:

func GetNowDateTime() string

Example:

package main

import (
    "fmt"
    "time"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    now := time.Now()
    current := datetime.GetNowDateTime()

    fmt.Println(current) 
    
    // Output:
    // 2022-01-28 15:59:33
}

GetZeroHourTimestamp

Return timestamp of zero hour (timestamp of 00:00).

Signature:

func GetZeroHourTimestamp() int64

Example:

package main

import (
    "fmt"
    "time"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    now := time.Now()
    zeroTime := datetime.GetZeroHourTimestamp()
    
    fmt.Println(zeroTime) 
    
    // Output:
    // 1643299200
}

GetNightTimestamp

Return timestamp of zero hour (timestamp of 23:59).

Signature:

func GetNightTimestamp() int64

Example:

package main

import (
    "fmt"
    "time"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    now := time.Now()
    nightTime := datetime.GetNightTimestamp()

    fmt.Println(nightTime) 
    
    // Output:
    // 1643385599
}

FormatTimeToStr

Format time to string, `format` param specification see note 1.

Signature:

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

Example:

package main

import (
    "fmt"
    "time"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    t, _ := time.Parse("2006-01-02 15:04:05", "2021-01-02 16:04:08")

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

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

    // Output:
    // 2021-01-02 16:04:08
    // 2021-01-02
    // 02-01-21 16:04:08
}

FormatStrToTime

Format string to time, `format` param specification see note 1.

Signature:

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

Example:

package main

import (
    "fmt"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    result1, _ := datetime.FormatStrToTime("2021-01-02 16:04:08", "yyyy-mm-dd hh:mm:ss")
    result2, _ := datetime.FormatStrToTime("2021-01-02", "yyyy-mm-dd")
    result3, _ := datetime.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
}

NewUnixNow

Return unix timestamp of current time

Signature:

type theTime struct {
    unix int64
}
func NewUnixNow() *theTime

Example:

package main

import (
    "fmt"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    tm := datetime.NewUnixNow()
    fmt.Println(tm) 
    
    // Output:
    // &{1647597438}
}

NewUnix

Return unix timestamp of specified int64 value.

Signature:

type theTime struct {
    unix int64
}
func NewUnix(unix int64) *theTime

Example:

package main

import (
    "fmt"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    tm := datetime.NewUnix(1647597438)
    fmt.Println(tm) 
    
    // Output:
    // &{1647597438}
}

NewFormat

Return unix timestamp of specified time string, t should be "yyyy-mm-dd hh:mm:ss".

Signature:

type theTime struct {
    unix int64
}
func NewFormat(t string) (*theTime, error)

Example:

package main

import (
    "fmt"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    tm, err := datetime.NewFormat("2022-03-18 17:04:05")
    fmt.Println(tm) 
    
    // Output:
    // &{1647594245}
}

NewISO8601

Return unix timestamp of specified iso8601 time string.

Signature:

type theTime struct {
    unix int64
}
func NewISO8601(iso8601 string) (*theTime, error)

Example:

package main

import (
    "fmt"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    tm, err := datetime.NewISO8601("2006-01-02T15:04:05.999Z")
    fmt.Println(tm) 
    
    // Output:
    // &{1136214245}
}

ToUnix

Return unix timestamp.

Signature:

func (t *theTime) ToUnix() int64

Example:

package main

import (
    "fmt"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    tm := datetime.NewUnixNow()
    fmt.Println(tm.ToUnix()) 
    
    // Output:
    // 1647597438
}

ToFormat

Return time string 'yyyy-mm-dd hh:mm:ss'.

Signature:

func (t *theTime) ToFormat() string

Example:

package main

import (
    "fmt"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    tm, _ := datetime.NewFormat("2022-03-18 17:04:05")
    fmt.Println(tm.ToFormat()) 
    
    // Output:
    // 2022-03-18 17:04:05
}

ToFormatForTpl

Return the time string which format is specified tpl.

Signature:

func (t *theTime) ToFormatForTpl(tpl string) string

Example:

package main

import (
    "fmt"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    tm, _ := datetime.NewFormat("2022-03-18 17:04:05")
    ts := tm.ToFormatForTpl("2006/01/02 15:04:05")
    fmt.Println(ts) 
    
    // Output:
    // 2022/03/18 17:04:05
}

ToIso8601

Return iso8601 time string.

Signature:

func (t *theTime) ToIso8601() string

Example:

package main

import (
    "fmt"
    "github.com/duke-git/lancet/v2/datetime"
)

func main() {
    tm, _ := datetime.NewISO8601("2006-01-02T15:04:05.999Z")
    ts := tm.ToIso8601()
    fmt.Println(ts) 
    
    // Output:
    // 2006-01-02T23:04:05+08:00
}