Time and Date Handling in Go

Time and date handling is a critical aspect of most applications. Go provides a comprehensive time package that makes working with dates, times, and durations straightforward and efficient. This guide covers everything you need to know about time operations in Go.

Understanding Go’s Time Package

Go’s time package is part of the standard library and provides types and functions for measuring and displaying time. The key types are:

time.Time: Represents an instant in time
time.Duration: Represents a span of time
time.Location: Represents a timezone

Basic Time Operations

package main

import (
	"fmt"
	"time"
)

func main() {
	// Get current time
	now := time.Now()
	fmt.Println("Current time:", now)

	// Get current time in UTC
	utcNow := time.Now().UTC()
	fmt.Println("UTC time:", utcNow)

	// Get individual components
	fmt.Println("Year:", now.Year())
	fmt.Println("Month:", now.Month())
	fmt.Println("Day:", now.Day())
	fmt.Println("Hour:", now.Hour())
	fmt.Println("Minute:", now.Minute())
	fmt.Println("Second:", now.Second())
	fmt.Println("Nanosecond:", now.Nanosecond())
}

Creating Time Values

Using Time Constructors

package main

import (
	"fmt"
	"time"
)

func main() {
	// Create a specific time
	t := time.Date(2025, time.December, 18, 14, 30, 0, 0, time.UTC)
	fmt.Println("Created time:", t)

	// Create from Unix timestamp
	unixTime := time.Unix(1671360600, 0)
	fmt.Println("From Unix timestamp:", unixTime)

	// Create from Unix nanoseconds
	nanoTime := time.UnixNano(1671360600000000000)
	fmt.Println("From Unix nanoseconds:", nanoTime)
}

Parsing Time Strings

Go uses a reference time to define the layout for parsing: Mon Jan 2 15:04:05 MST 2006. This specific time is used as the pattern.

package main

import (
	"fmt"
	"log"
	"time"
)

func main() {
	// Parse with standard layout
	t, err := time.Parse(time.RFC3339, "2025-12-18T14:30:00Z")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Parsed RFC3339:", t)

	// Parse with custom layout
	layout := "2006-01-02 15:04:05"
	t2, err := time.Parse(layout, "2025-12-18 14:30:00")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Parsed custom:", t2)

	// Parse with location
	loc, _ := time.LoadLocation("America/New_York")
	t3, err := time.ParseInLocation(layout, "2025-12-18 14:30:00", loc)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Parsed with location:", t3)
}

Formatting Time

Standard Formatting

package main

import (
	"fmt"
	"time"
)

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

	// Using predefined layouts
	fmt.Println("RFC3339:", now.Format(time.RFC3339))
	fmt.Println("RFC1123:", now.Format(time.RFC1123))
	fmt.Println("RFC822:", now.Format(time.RFC822))
	fmt.Println("UnixDate:", now.Format(time.UnixDate))

	// Custom format
	fmt.Println("Custom:", now.Format("2006-01-02 15:04:05"))
	fmt.Println("Date only:", now.Format("2006-01-02"))
	fmt.Println("Time only:", now.Format("15:04:05"))
}

Common Layout Patterns

package main

import (
	"fmt"
	"time"
)

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

	// Common patterns
	patterns := map[string]string{
		"ISO 8601":        "2006-01-02T15:04:05Z07:00",
		"US Format":       "01/02/2006 3:04 PM",
		"European":        "02-01-2006 15:04:05",
		"Timestamp":       "2006-01-02 15:04:05",
		"Date only":       "2006-01-02",
		"Time only":       "15:04:05",
		"Month/Day/Year":  "01/02/2006",
		"Day Month Year":  "02 January 2006",
	}

	for name, layout := range patterns {
		fmt.Printf("%s: %s\n", name, now.Format(layout))
	}
}

Working with Durations

Duration Basics

package main

import (
	"fmt"
	"time"
)

func main() {
	// Create durations
	d1 := 5 * time.Second
	d2 := 2 * time.Minute
	d3 := 1 * time.Hour
	d4 := 24 * time.Hour

	fmt.Println("5 seconds:", d1)
	fmt.Println("2 minutes:", d2)
	fmt.Println("1 hour:", d3)
	fmt.Println("24 hours:", d4)

	// Parse duration from string
	d5, _ := time.ParseDuration("1h30m45s")
	fmt.Println("Parsed duration:", d5)

	// Duration arithmetic
	fmt.Println("Total seconds:", d1.Seconds())
	fmt.Println("Total minutes:", d2.Minutes())
	fmt.Println("Total hours:", d3.Hours())
}

Time Arithmetic

package main

import (
	"fmt"
	"time"
)

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

	// Add time
	tomorrow := now.Add(24 * time.Hour)
	fmt.Println("Tomorrow:", tomorrow)

	// Subtract time
	yesterday := now.Add(-24 * time.Hour)
	fmt.Println("Yesterday:", yesterday)

	// Add specific durations
	nextWeek := now.AddDate(0, 0, 7)
	fmt.Println("Next week:", nextWeek)

	nextMonth := now.AddDate(0, 1, 0)
	fmt.Println("Next month:", nextMonth)

	nextYear := now.AddDate(1, 0, 0)
	fmt.Println("Next year:", nextYear)

	// Calculate difference
	diff := tomorrow.Sub(now)
	fmt.Println("Difference:", diff)
}

Timezone Handling

Working with Timezones

package main

import (
	"fmt"
	"log"
	"time"
)

func main() {
	// Get timezone
	loc, err := time.LoadLocation("America/New_York")
	if err != nil {
		log.Fatal(err)
	}

	// Convert time to timezone
	now := time.Now()
	nyTime := now.In(loc)
	fmt.Println("New York time:", nyTime)

	// Get timezone name and offset
	name, offset := nyTime.Zone()
	fmt.Printf("Timezone: %s, Offset: %d seconds\n", name, offset)

	// Multiple timezones
	timezones := []string{
		"UTC",
		"America/New_York",
		"Europe/London",
		"Asia/Tokyo",
		"Australia/Sydney",
	}

	for _, tz := range timezones {
		loc, _ := time.LoadLocation(tz)
		fmt.Printf("%s: %s\n", tz, now.In(loc).Format("2006-01-02 15:04:05 MST"))
	}
}

Handling Daylight Saving Time

package main

import (
	"fmt"
	"time"
)

func main() {
	// Create times around DST transition
	loc, _ := time.LoadLocation("America/New_York")

	// Before DST
	before := time.Date(2025, time.March, 8, 1, 30, 0, 0, loc)
	fmt.Println("Before DST:", before)

	// After DST (add 2 hours)
	after := before.Add(2 * time.Hour)
	fmt.Println("After DST:", after)

	// Check if DST is in effect
	_, offset := after.Zone()
	fmt.Println("UTC offset:", offset/3600, "hours")
}

Comparing and Checking Times

Time Comparisons

package main

import (
	"fmt"
	"time"
)

func main() {
	t1 := time.Date(2025, time.December, 18, 10, 0, 0, 0, time.UTC)
	t2 := time.Date(2025, time.December, 18, 15, 0, 0, 0, time.UTC)
	t3 := time.Date(2025, time.December, 18, 10, 0, 0, 0, time.UTC)

	// Comparison methods
	fmt.Println("t1 before t2:", t1.Before(t2))
	fmt.Println("t1 after t2:", t1.After(t2))
	fmt.Println("t1 equal t3:", t1.Equal(t3))

	// Using comparison operators
	fmt.Println("t1 < t2:", t1.Before(t2))
	fmt.Println("t1 > t2:", t1.After(t2))
	fmt.Println("t1 == t3:", t1.Equal(t3))
}

Checking Time Properties

package main

import (
	"fmt"
	"time"
)

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

	// Get day of week
	fmt.Println("Day of week:", now.Weekday())

	// Get day of year
	fmt.Println("Day of year:", now.YearDay())

	// Check if it's a specific day
	if now.Weekday() == time.Monday {
		fmt.Println("It's Monday!")
	}

	// Get week number
	year, week := now.ISOWeek()
	fmt.Printf("ISO Week: %d, Week: %d\n", year, week)
}

Practical Examples

Measuring Elapsed Time

package main

import (
	"fmt"
	"time"
)

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

	// Simulate some work
	time.Sleep(2 * time.Second)

	elapsed := time.Since(start)
	fmt.Printf("Elapsed time: %v\n", elapsed)
	fmt.Printf("Elapsed seconds: %.2f\n", elapsed.Seconds())
}

Rate Limiting with Time

package main

import (
	"fmt"
	"time"
)

func main() {
	ticker := time.NewTicker(1 * time.Second)
	defer ticker.Stop()

	count := 0
	for range ticker.C {
		count++
		fmt.Printf("Tick %d at %s\n", count, time.Now().Format("15:04:05"))

		if count >= 5 {
			break
		}
	}
}

Timeout Example

package main

import (
	"fmt"
	"time"
)

func main() {
	// Create a channel for results
	done := make(chan string)

	// Start a goroutine
	go func() {
		time.Sleep(2 * time.Second)
		done <- "Operation completed"
	}()

	// Wait with timeout
	select {
	case result := <-done:
		fmt.Println(result)
	case <-time.After(1 * time.Second):
		fmt.Println("Operation timed out")
	}
}

Scheduling Tasks

package main

import (
	"fmt"
	"time"
)

func main() {
	// Execute after delay
	time.AfterFunc(2*time.Second, func() {
		fmt.Println("Executed after 2 seconds")
	})

	// Wait for execution
	time.Sleep(3 * time.Second)

	// Periodic execution
	ticker := time.NewTicker(1 * time.Second)
	defer ticker.Stop()

	for i := 0; i < 3; i++ {
		<-ticker.C
		fmt.Println("Periodic task at", time.Now().Format("15:04:05"))
	}
}

Best Practices

✅ Good Practices

// Always use UTC internally
func processTime(t time.Time) {
	utcTime := t.UTC()
	// Process with UTC
}

// Use time.Time for all time values
func getEventTime() time.Time {
	return time.Now()
}

// Parse with proper error handling
func parseUserTime(input string) (time.Time, error) {
	return time.Parse(time.RFC3339, input)
}

// Use time.Duration for intervals
func waitForEvent(timeout time.Duration) {
	select {
	case <-time.After(timeout):
		// Handle timeout
	}
}

// Store timezone information
type Event struct {
	Time     time.Time
	Location *time.Location
}

❌ Anti-Patterns

// Don't use strings for time values
func badProcessTime(timeStr string) {
	// Hard to work with, error-prone
}

// Don't ignore timezone information
func badTimezone() {
	t := time.Now()
	// Loses timezone context
}

// Don't use int64 for time (use time.Time)
func badTimestamp(ts int64) {
	// Unclear what unit this is
}

// Don't hardcode time layouts
func badParse(input string) time.Time {
	t, _ := time.Parse("01/02/2006", input)
	return t
}

Common Pitfalls

Timezone Confusion

// ❌ Wrong: Assumes local timezone
t := time.Date(2025, 12, 18, 14, 30, 0, 0, nil)

// ✅ Correct: Explicitly specify timezone
t := time.Date(2025, 12, 18, 14, 30, 0, 0, time.UTC)

Layout String Mistakes

// ❌ Wrong: Using standard time format
t, _ := time.Parse("2006-01-02", "2025-12-18")

// ✅ Correct: Using reference time
t, _ := time.Parse("2006-01-02", "2025-12-18")

Ignoring Errors

// ❌ Wrong: Ignoring parse errors
t, _ := time.Parse(time.RFC3339, userInput)

// ✅ Correct: Handle errors properly
t, err := time.Parse(time.RFC3339, userInput)
if err != nil {
	log.Printf("Invalid time format: %v", err)
	return
}

Resources

Summary

Go’s time package provides powerful and flexible tools for working with dates and times. Key takeaways:

Use time.Time for all time values
Always work with UTC internally
Use time.Duration for intervals
Parse and format with proper error handling
Be explicit about timezones
Leverage predefined layouts when possible

With these tools and practices, you can handle complex time operations reliably and efficiently in your Go applications.