Go time Package

package main

import (
    "fmt"
    "time"
)

func main() {
    now := time.Now()              // wall + monotonic

    fmt.Println(now)                // 2026-06-23 14:30:05.123456789 +0000 UTC m=+0.000000001
    fmt.Println(now.Year())         // 2026
    fmt.Println(now.Month())        // June
    fmt.Println(now.Day())          // 23
    fmt.Println(now.Hour())         // 0-23: 14
    fmt.Println(now.Minute())       // 0-59: 30
    fmt.Println(now.Second())       // 0-59: 5
    fmt.Println(now.Nanosecond())   // 0-999999999: 123456789
    fmt.Println(now.Weekday())      // Tuesday
    fmt.Println(now.YearDay())      // 1-366: 174
}

// time.Date(year, month, day, hour, min, sec, nsec, loc)
launch := time.Date(2026, time.July, 4, 9, 0, 0, 0, time.UTC)
fmt.Println(launch)

// Zero value — Jan 1, year 1, 00:00:00 UTC
var zero time.Time
fmt.Println(zero.IsZero()) // true

now := time.Now()

// Common patterns
fmt.Println(now.Format("2006-01-02"))
fmt.Println(now.Format("02/01/2006"))
fmt.Println(now.Format("Jan 2, 2006"))
fmt.Println(now.Format("3:04 PM"))
fmt.Println(now.Format("Mon, 02 Jan 2006 15:04:05 -0700"))

// Pre-defined layouts in the time package
fmt.Println(now.Format(time.RFC3339))
fmt.Println(now.Format(time.RFC822))
fmt.Println(now.Format(time.Kitchen))

// time.Parse(layout, value) — always UTC
t1, err := time.Parse("2006-01-02", "2026-06-23")
if err != nil {
    fmt.Println("error:", err)
}
fmt.Println(t1)

// time.ParseInLocation — respects local timezone
loc, _ := time.LoadLocation("America/New_York")
t2, _ := time.ParseInLocation("2006-01-02 15:04:05", "2026-06-23 09:00:00", loc)
fmt.Println(t2)

// RFC3339 is the most portable internet format
t3, _ := time.Parse(time.RFC3339, "2026-06-23T14:30:05Z")
fmt.Println(t3.Format(time.RFC3339))

d := 17*time.Minute + 45*time.Second

fmt.Println(d.Truncate(time.Minute)) // 17m0s  (floor)
fmt.Println(d.Round(time.Minute))    // 18m0s  (nearest)

now := time.Now()

// Add a duration to a time
tomorrow  := now.Add(24 * time.Hour)
nextWeek  := now.Add(7 * 24 * time.Hour)
yesterday := now.Add(-24 * time.Hour)

// AddDate(years, months, days) — calendar-aware
nextMonth := now.AddDate(0, 1, 0)
nextYear  := now.AddDate(1, 0, 0)

// Sub: time.Time − time.Time → time.Duration
elapsed := now.Sub(yesterday)
fmt.Println(elapsed) // 24h0m0s

// Since / Until — shortcuts using time.Now()
start := time.Now()
// ... do work ...
fmt.Println(time.Since(start)) // elapsed since start

deadline := now.Add(5 * time.Minute)
fmt.Println(time.Until(deadline)) // time remaining

func benchmark(name string, fn func()) {
    start := time.Now()
    fn()
    elapsed := time.Since(start)
    fmt.Printf("%s took %v\n", name, elapsed)
}

benchmark("heavy task", func() {
    time.Sleep(50 * time.Millisecond)
})

t1 := time.Date(2026, time.January, 1, 0, 0, 0, 0, time.UTC)
t2 := time.Date(2026, time.June, 23, 0, 0, 0, 0, time.UTC)
t3 := t1

fmt.Println(t1.Before(t2)) // true  — t1 is earlier
fmt.Println(t2.After(t1))  // true  — t2 is later
fmt.Println(t1.Equal(t3))  // true  — same instant
fmt.Println(t1 == t3)       // may be false! don't use ==

// Clamp: check if time is within a range
func inRange(t, lo, hi time.Time) bool {
    return !t.Before(lo) && !t.After(hi)
}

now := time.Now().UTC() // start in UTC

// Load IANA timezone (requires tzdata on system or embed)
ny, _  := time.LoadLocation("America/New_York")
lon, _ := time.LoadLocation("Europe/London")
tok, _ := time.LoadLocation("Asia/Tokyo")

// Convert — same instant, different display
fmt.Println(now.In(ny))
fmt.Println(now.In(lon))
fmt.Println(now.In(tok))

// Fixed offset (when IANA name is unknown)
ist := time.FixedZone("IST", 5*3600+30*60) // +05:30
fmt.Println(now.In(ist))

// Get timezone name + offset
name, offset := now.In(ny).Zone()
fmt.Printf("%s  offset=%d\n", name, offset)

// In any .go file (often main.go or a dedicated tz.go)
import _ "time/tzdata"

// This embeds the full IANA timezone database into your binary,
// so LoadLocation works even in scratch containers with no /usr/share/zoneinfo

now := time.Now()

// time.Time → Unix timestamp
fmt.Println(now.Unix())      // seconds since epoch
fmt.Println(now.UnixMilli()) // milliseconds
fmt.Println(now.UnixMicro()) // microseconds
fmt.Println(now.UnixNano())  // nanoseconds

// Unix timestamp → time.Time
ts := time.Unix(1750000000, 0)  // (sec, nsec)
fmt.Println(ts)

tsMs := time.UnixMilli(1750000000000)
fmt.Println(tsMs)

// JSON marshaling uses RFC3339 by default
type Event struct {
    At time.Time `json:"at"`
}

// Pause the current goroutine
time.Sleep(500 * time.Millisecond)
time.Sleep(2 * time.Second)
time.Sleep(1 * time.Minute)

// Context-aware sleep (can be cancelled)
func sleepCtx(ctx context.Context, d time.Duration) error {
    select {
    case <-time.After(d):
        return nil
    case <-ctx.Done():
        return ctx.Err()
    }
}

timer := time.NewTimer(2 * time.Second)
defer timer.Stop() // always clean up

select {
case t := <-timer.C:
    fmt.Println("Timer fired at", t)
case <-time.After(1 * time.Second):
    fmt.Println("Timed out waiting for timer")
}

// time.AfterFunc — callback in new goroutine
time.AfterFunc(500*time.Millisecond, func() {
    fmt.Println("callback fired")
})

timer := time.NewTimer(5 * time.Second)

// Safe reset pattern
if !timer.Stop() {
    select {
    case <-timer.C: // drain if already fired
    default:
    }
}
timer.Reset(10 * time.Second)

ticker := time.NewTicker(1 * time.Second)
done   := make(chan struct{})

go func() {
    for {
        select {
        case <-done:
            return
        case t := <-ticker.C:
            fmt.Println("tick at", t.Format(time.Kitchen))
        }
    }
}()

time.Sleep(5 * time.Second)
ticker.Stop()
close(done)
fmt.Println("ticker stopped")

func pollUntilDone(ctx context.Context, interval time.Duration) {
    ticker := time.NewTicker(interval)
    defer ticker.Stop()

    for {
        select {
        case <-ctx.Done():
            fmt.Println("context cancelled, stopping poll")
            return
        case <-ticker.C:
            if checkHealth() {
                fmt.Println("healthy!")
                return
            }
            fmt.Println("still waiting...")
        }
    }
}