Time and Timers

package main

import (
	"fmt"
	"time"
)

func main() {
	// A loan period is a Duration: an int64 count of nanoseconds.
	loan := 21 * 24 * time.Hour
	grace := 90 * time.Minute
	fmt.Println(loan, grace, loan+grace)
	fmt.Printf("%d %T\n", time.Second, time.Second)

	// Accessors return float64 (Seconds, Minutes, Hours) or int64.
	fmt.Println(loan.Hours(), grace.Minutes(), grace.Milliseconds())

	// Parsing and printing.
	d, err := time.ParseDuration("1h15m30.5s")
	fmt.Println(d, err)
	_, err = time.ParseDuration("3 days")
	fmt.Println(err)

	// Round and Truncate round to a multiple; Abs (1.19) is safe at MinInt64.
	fmt.Println(d.Round(time.Minute), d.Truncate(time.Hour), (-d).Abs())

	// Multiply a Duration by a count only after converting the count.
	n := 3
	fmt.Println(time.Duration(n)*time.Second, 1500*time.Millisecond)

	// Duration arithmetic wraps around silently on overflow.
	big := time.Duration(1<<63 - 1)
	fmt.Println(big, big+1)
}

504h0m0s 1h30m0s 505h30m0s
1000000000 time.Duration
504 90 5400000
1h15m30.5s <nil>
time: unknown unit " days" in duration "3 days"
1h16m0s 1h0m0s 1h15m30.5s
3s 1.5s
2562047h47m16.854775807s -2562047h47m16.854775808s

package main

import (
	"fmt"
	"time"
)

func main() {
	ny, err := time.LoadLocation("America/New_York")
	if err != nil {
		fmt.Println(err)
		return
	}
	_, err = time.LoadLocation("Mars/Olympus_Mons")
	fmt.Println(err)

	// A branch closes at 18:00 local time, whatever the offset is that day.
	closing := time.Date(2026, time.March, 7, 18, 0, 0, 0, ny)
	fmt.Println(closing)

	// AddDate works on the calendar; Add works on the clock.
	fmt.Println(closing.AddDate(0, 0, 1))              // next day, still 18:00 local
	fmt.Println(closing.Add(24 * time.Hour))           // 24 hours later: 19:00 EDT
	fmt.Println(closing.AddDate(0, 0, 1).Sub(closing)) // only 23 hours apart

	// A wall time that does not exist is normalised; one that happens
	// twice picks one of the two instants.
	gap := time.Date(2026, time.March, 8, 2, 30, 0, 0, ny)
	fmt.Println("gap: ", gap)
	twice := time.Date(2026, time.November, 1, 1, 30, 0, 0, ny)
	fmt.Println("twice:", twice, twice.IsDST())

	// Zone, ZoneBounds (1.19) and In.
	name, offset := closing.Zone()
	start, end := closing.ZoneBounds()
	fmt.Println(name, offset, start, end)
	fmt.Println(closing.In(time.UTC), closing.UTC().Location(), time.Local != nil)

	// A fixed offset has no daylight saving rules.
	ist := time.FixedZone("IST", 5*3600+30*60)
	fmt.Println(closing.In(ist).Format(time.RFC1123Z))

	// Month overflow is normalised, not rejected.
	fmt.Println(time.Date(2026, time.January, 31, 0, 0, 0, 0, time.UTC).AddDate(0, 1, 0).Format(time.DateOnly))
	fmt.Println(time.Date(2026, time.February, 30, 25, 61, 0, 0, time.UTC))
}

unknown time zone Mars/Olympus_Mons
2026-03-07 18:00:00 -0500 EST
2026-03-08 18:00:00 -0400 EDT
2026-03-08 19:00:00 -0400 EDT
23h0m0s
gap:  2026-03-08 01:30:00 -0500 EST
twice: 2026-11-01 01:30:00 -0400 EDT true
EST -18000 2025-11-02 01:00:00 -0500 EST 2026-03-08 03:00:00 -0400 EDT
2026-03-07 23:00:00 +0000 UTC UTC true
Sun, 08 Mar 2026 04:30:00 +0530
2026-03-03
2026-03-03 02:01:00 +0000 UTC

Mon Jan 2 15:04:05 MST 2006

package main

import (
	"fmt"
	"time"
)

func main() {
	t := time.Date(2026, time.October, 18, 15, 4, 5, 123456789, time.UTC)

	// The layout is the reference time written the way you want the output.
	// Mon Jan 2 15:04:05 MST 2006 is 01/02 03:04:05PM '06 -0700.
	layouts := []struct{ name, layout string }{
		{"DateTime", time.DateTime},
		{"DateOnly", time.DateOnly},
		{"TimeOnly", time.TimeOnly},
		{"RFC3339", time.RFC3339},
		{"RFC3339Nano", time.RFC3339Nano},
		{"RFC1123", time.RFC1123},
		{"Kitchen", time.Kitchen},
		{"custom", "Mon 2 Jan 2006, 3:04pm"},
		{"millis", "2006-01-02 15:04:05.000"},
		{"trimmed fraction", "15:04:05.999"},
	}
	for _, l := range layouts {
		fmt.Printf("%-16s %s\n", l.name, t.Format(l.layout))
	}

	// Parse reads the same layouts; a missing zone means UTC.
	p, err := time.Parse(time.DateTime, "2026-11-08 09:30:00")
	fmt.Println(p, err)

	// ParseInLocation interprets an offset-less time in a given location.
	ny, _ := time.LoadLocation("America/New_York")
	q, err := time.ParseInLocation(time.DateTime, "2026-11-08 09:30:00", ny)
	fmt.Println(q, err)

	// Errors are *time.ParseError values.
	_, err = time.Parse(time.DateOnly, "18/10/2026")
	fmt.Println(err)
	_, err = time.Parse(time.DateOnly, "2026-02-30")
	fmt.Println(err)

	// The classic trap: 2016 is not a year in the reference time.
	fmt.Println(t.Format("2016-01-02"))
	fmt.Println(t.Format("2006-01-02"))

	// AppendFormat avoids an allocation when building log lines.
	buf := []byte("due=")
	buf = t.AppendFormat(buf, time.DateOnly)
	fmt.Println(string(buf))
}

DateTime         2026-10-18 15:04:05
DateOnly         2026-10-18
TimeOnly         15:04:05
RFC3339          2026-10-18T15:04:05Z
RFC3339Nano      2026-10-18T15:04:05.123456789Z
RFC1123          Sun, 18 Oct 2026 15:04:05 UTC
Kitchen          3:04PM
custom           Sun 18 Oct 2026, 3:04pm
millis           2026-10-18 15:04:05.123
trimmed fraction 15:04:05.123
2026-11-08 09:30:00 +0000 UTC <nil>
2026-11-08 09:30:00 -0500 EST <nil>
parsing time "18/10/2026" as "2006-01-02": cannot parse "18/10/2026" as "2006"
parsing time "2026-02-30": day out of range
18106-10-18
2026-10-18
due=2026-10-18

package main

import (
	"encoding/json"
	"fmt"
	"time"
)

type Loan struct {
	Member string        `json:"member"`
	Due    time.Time     `json:"due"`
	Grace  time.Duration `json:"grace"`
}

func main() {
	// Time marshals as RFC 3339 with nanoseconds; Duration as a bare integer.
	est := time.FixedZone("EST", -5*3600)
	l := Loan{"ada", time.Date(2026, time.October, 18, 9, 0, 0, 0, est), 90 * time.Minute}
	b, _ := json.Marshal(l)
	fmt.Println(string(b))

	var back Loan
	fmt.Println(json.Unmarshal(b, &back), back.Due.Equal(l.Due), back.Due == l.Due)

	var bad Loan
	fmt.Println(json.Unmarshal([]byte(`{"due":"2026-10-18"}`), &bad))

	// == on Time compares the location pointer too, so it is a poor map key:
	utc := time.Date(2026, time.October, 18, 14, 0, 0, 0, time.UTC)
	seen := map[time.Time]string{utc: "UTC"}
	_, ok := seen[utc.In(est)]
	fmt.Println("same instant found via map key:", ok)
	byUnix := map[int64]string{utc.UnixNano(): "UTC"}
	_, ok = byUnix[utc.In(est).UnixNano()]
	fmt.Println("same instant found via UnixNano:", ok)

	// Truncate rounds down relative to the zero time (UTC), not to local midnight.
	ist := time.FixedZone("IST", 5*3600+30*60)
	t := time.Date(2026, time.October, 18, 10, 0, 0, 0, ist)
	fmt.Println(t.Truncate(24*time.Hour), "vs", time.Date(t.Year(), t.Month(), t.Day(), 0, 0, 0, 0, t.Location()))

	// Sub saturates at the Duration limits instead of wrapping.
	fmt.Println(time.Time{}.Sub(time.Date(3000, 1, 1, 0, 0, 0, 0, time.UTC)) == time.Duration(-1<<63))
}

{"member":"ada","due":"2026-10-18T09:00:00-05:00","grace":5400000000000}
<nil> true false
parsing time "2026-10-18" as "2006-01-02T15:04:05Z07:00": cannot parse "" as "T"
same instant found via map key: false
same instant found via UnixNano: true
2026-10-18 05:30:00 +0530 IST vs 2026-10-18 00:00:00 +0530 IST
true

package main

import (
	"context"
	"errors"
	"fmt"
	"time"
)

// fetch stands in for a slow call; it returns when work is done.
func fetch(delay time.Duration) <-chan string {
	ch := make(chan string, 1) // buffered: the sender never blocks if nobody listens
	go func() {
		time.Sleep(delay)
		ch <- "catalogue page"
	}()
	return ch
}

func main() {
	// 1. time.After in a select: a one-shot timeout.
	select {
	case v := <-fetch(10 * time.Millisecond):
		fmt.Println("got", v)
	case <-time.After(time.Second):
		fmt.Println("timeout")
	}
	select {
	case v := <-fetch(time.Second):
		fmt.Println("got", v)
	case <-time.After(20 * time.Millisecond):
		fmt.Println("timeout")
	}

	// 2. Ticker: periodic work. Stop it when finished.
	tk := time.NewTicker(10 * time.Millisecond)
	defer tk.Stop()
	for i := 1; i <= 3; i++ {
		<-tk.C
		fmt.Println("tick", i)
	}
	tk.Reset(5 * time.Millisecond) // change the period (1.15)

	// 3. AfterFunc: run f in its own goroutine after d. No channel.
	done := make(chan struct{})
	hold := time.AfterFunc(20*time.Millisecond, func() {
		fmt.Println("hold expired")
		close(done)
	})
	<-done
	fmt.Println("Stop after run:", hold.Stop())

	// 4. A cancelled AfterFunc never runs.
	never := time.AfterFunc(time.Hour, func() { fmt.Println("never printed") })
	fmt.Println("Stop before run:", never.Stop())

	// 5. Prefer a context for deadlines that cross function boundaries.
	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond)
	defer cancel()
	select {
	case <-fetch(time.Second):
	case <-ctx.Done():
		fmt.Println(ctx.Err(), errors.Is(ctx.Err(), context.DeadlineExceeded))
	}
}

got catalogue page
timeout
tick 1
tick 2
tick 3
hold expired
Stop after run: false
Stop before run: true
context deadline exceeded true

package main

import (
	"fmt"
	"time"
)

func report(label string, d time.Duration) {
	fmt.Println(label, d < time.Millisecond)
}

func work() {
	start := time.Now()
	// Wrong: time.Since(start) is evaluated now, when defer runs the statement.
	defer report("evaluated early, under 1ms:", time.Since(start))
	// Right: the closure reads the clock when the function returns.
	defer func() { report("evaluated late, under 1ms:", time.Since(start)) }()
	time.Sleep(30 * time.Millisecond)
}

func main() { work() }

./main.go:15:46: call to time.Since is not deferred

evaluated late, under 1ms: false
evaluated early, under 1ms: true

package overdue

import (
	"context"
	"time"
)

// Loan is a book lent until Due.
type Loan struct {
	Member string
	Due    time.Time
}

// IsOverdue reports whether l is past due at now. The caller supplies the
// clock reading, so tests need no fake clock at all.
func (l Loan) IsOverdue(now time.Time) bool { return now.After(l.Due) }

// Remind sends the member's name on out every interval once l is overdue,
// until ctx is done.
func Remind(ctx context.Context, l Loan, interval time.Duration, out chan<- string) {
	tk := time.NewTicker(interval)
	defer tk.Stop()
	for {
		select {
		case <-ctx.Done():
			return
		case now := <-tk.C:
			if l.IsOverdue(now) {
				out <- l.Member
			}
		}
	}
}

package overdue

import (
	"context"
	"testing"
	"testing/synctest"
	"time"
)

func TestIsOverdue(t *testing.T) {
	due := time.Date(2026, time.October, 18, 0, 0, 0, 0, time.UTC)
	l := Loan{Member: "ada", Due: due}
	if l.IsOverdue(due) {
		t.Error("overdue exactly at the due time")
	}
	if !l.IsOverdue(due.Add(time.Nanosecond)) {
		t.Error("not overdue one nanosecond later")
	}
}

func TestRemind(t *testing.T) {
	synctest.Test(t, func(t *testing.T) {
		start := time.Now() // always midnight UTC 2000-01-01 in a bubble
		t.Logf("bubble starts at %s", start.UTC().Format(time.DateTime))

		l := Loan{Member: "ada", Due: start.Add(2 * time.Hour)}
		out := make(chan string)
		ctx, cancel := context.WithCancel(t.Context())
		go Remind(ctx, l, time.Hour, out)

		// Nothing is sent before the loan is due: let the goroutine reach
		// its select and the clock reach the first tick, one hour in.
		synctest.Sleep(time.Hour)
		select {
		case m := <-out:
			t.Fatalf("early reminder for %s at %s", m, time.Since(start))
		default:
		}

		// The tick at 2h is not yet past the due time; the one at 3h is.
		synctest.Sleep(time.Hour)
		<-out
		t.Logf("first reminder after %s", time.Since(start))

		cancel()
		synctest.Wait() // Remind has returned; no goroutine leaks from the bubble
	})
}

=== RUN   TestIsOverdue
--- PASS: TestIsOverdue (0.00s)
=== RUN   TestRemind
    overdue_test.go:24: bubble starts at 2000-01-01 00:00:00
    overdue_test.go:43: first reminder after 3h0m0s
--- PASS: TestRemind (0.00s)
PASS
ok  	example.com/shelf/e09	0.403s