
The `time` package provides types and functions for measuring and displaying time. `time.Time` represents an instant in time with nanosecond precision. `time.Duration` represents an elapsed duration as an `int64` nanosecond count.

<ExamplePair>
<ExampleProse>

`time.Now()` returns the current local time. Access individual components with methods like `Year()`, `Month()`, `Day()`, `Hour()`, `Minute()`, `Second()`, and `Weekday()`.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "time"
)

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

    fmt.Println(now.Year(), now.Month(), now.Day())
    fmt.Println(now.Hour(), now.Minute(), now.Second())
    fmt.Println(now.Weekday())
    fmt.Println(now.Unix())     // seconds since epoch
    fmt.Println(now.UnixNano()) // nanoseconds since epoch
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Build `time.Duration` values using named constants: `time.Second`, `time.Minute`, `time.Hour`, etc. Add or subtract a duration from a `time.Time` with `Add`. Subtract two `time.Time` values with `Sub` to get a `Duration`.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "time"
)

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

    // Add durations to a time
    inAnHour := now.Add(1 * time.Hour)
    fmt.Println(inAnHour)

    yesterday := now.Add(-24 * time.Hour)
    fmt.Println(yesterday)

    // Subtract two times to get a duration
    diff := now.Sub(yesterday)
    fmt.Println(diff)            // 24h0m0s
    fmt.Println(diff.Hours())    // 24
    fmt.Println(diff.Minutes())  // 1440
    fmt.Println(diff.Seconds())  // 86400
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`time.Since(t)` returns the elapsed time since `t`. `time.Until(t)` returns the duration until `t`. Both use the monotonic clock for accuracy. Compare two `time.Time` values with `Before`, `After`, and `Equal`.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "time"
)

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

    time.Sleep(2 * time.Millisecond) // simulate work

    elapsed := time.Since(start)
    fmt.Printf("elapsed: %v\n", elapsed)

    deadline := time.Now().Add(5 * time.Second)
    fmt.Printf("time until deadline: %v\n", time.Until(deadline))

    t1 := time.Now()
    t2 := t1.Add(time.Second)
    fmt.Println(t1.Before(t2)) // true
    fmt.Println(t1.After(t2))  // false
    fmt.Println(t1.Equal(t1))  // true
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
`time.Time` contains both a wall clock reading and a monotonic clock reading. `time.Since` uses the monotonic clock, which is immune to NTP adjustments and DST transitions - always prefer it for measuring elapsed time. Use the wall clock (from `time.Now()`) for timestamps you store in databases or logs. Never compare two `time.Time` values with `==` when one may have been deserialized from a database: the monotonic component is stripped on round-trips through `time.Time.MarshalJSON` or SQL drivers, making the `Equal` method (which compares only wall time) the correct comparison. In HTTP handlers, record `time.Now()` at the top of the handler to measure end-to-end latency rather than calling `time.Since` with a captured start from middleware, where middleware overhead inflates the measurement.
</InProduction>


time.Time, time.Now, Duration arithmetic, time.Since and time.Until, Add and Sub, and comparisons with Before, After, and Equal.

Time


The Unix epoch is January 1, 1970 UTC. Go's `time` package provides direct access to epoch timestamps and can convert them back to `time.Time` values.

<ExamplePair>
<ExampleProse>

`t.Unix()` returns the number of seconds elapsed since the Unix epoch. `t.UnixMilli()` and `t.UnixNano()` return milliseconds and nanoseconds respectively. These are plain `int64` values - portable across every language and database.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "time"
)

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

    fmt.Println(now.Unix())      // e.g. 1714000000
    fmt.Println(now.UnixMilli()) // milliseconds
    fmt.Println(now.UnixNano())  // nanoseconds

    // Construct a specific time
    t := time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC)
    fmt.Println(t.Unix()) // 1704067200
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Convert an epoch integer back to `time.Time` with `time.Unix(sec, nsec)`. Always call `.UTC()` immediately to ensure the result is in UTC, regardless of the server's local timezone.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "time"
)

func main() {
    // Seconds since epoch → time.Time
    ts := int64(1704067200)
    t := time.Unix(ts, 0).UTC()
    fmt.Println(t) // 2024-01-01 00:00:00 +0000 UTC

    // Milliseconds since epoch → time.Time
    ms := int64(1704067200000)
    tms := time.UnixMilli(ms).UTC()
    fmt.Println(tms) // 2024-01-01 00:00:00 +0000 UTC

    // Nanoseconds
    ns := int64(1704067200000000000)
    tns := time.Unix(0, ns).UTC()
    fmt.Println(tns)
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Measure elapsed time precisely by subtracting two epoch values. For benchmarking short operations, prefer nanoseconds. For human-readable durations, convert the difference to a `time.Duration`.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "time"
)

func doWork() {
    time.Sleep(10 * time.Millisecond)
}

func main() {
    start := time.Now().UnixNano()
    doWork()
    end := time.Now().UnixNano()

    elapsedNs := end - start
    elapsed := time.Duration(elapsedNs)
    fmt.Printf("elapsed: %v\n", elapsed) // e.g. 10.123ms

    // Prefer time.Since for this - it's cleaner
    t := time.Now()
    doWork()
    fmt.Printf("elapsed: %v\n", time.Since(t))
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
Store timestamps as UTC Unix seconds (`int64`) in databases for maximum portability - every language and database understands them, they sort correctly, and they never drift with timezone changes. Convert to `time.Time` in UTC immediately after reading from storage, and format for display only at the presentation layer. Never store a `time.Time` directly in SQL without UTC normalization: Go's default `time.Time.String()` includes the local timezone, which produces inconsistent data if your service runs in multiple regions. Use `t.UTC().Format(time.RFC3339)` for string storage or a UTC-aware SQL driver. When receiving epoch timestamps from external APIs, confirm whether the value is in seconds or milliseconds - off-by-1000 bugs produce dates in 1970 or 55,000 years in the future, both of which slip through typical validation.
</InProduction>


Unix epoch seconds and nanoseconds, converting back with time.Unix, and best practices for storing timestamps in databases.

Epoch


The `encoding/xml` package encodes Go values to XML and decodes XML into Go values. Struct tags (`xml:"name"`) control how Go fields map to XML elements and attributes.

<ExamplePair>
<ExampleProse>

Encode a struct to XML with `xml.Marshal`. The `xml.Header` constant provides the standard XML declaration. Use `xml:",attr"` to map a field to an XML attribute instead of a child element.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "encoding/xml"
    "fmt"
)

type Book struct {
    XMLName xml.Name `xml:"book"`
    ID      int      `xml:"id,attr"`
    Title   string   `xml:"title"`
    Author  string   `xml:"author"`
}

func main() {
    b := Book{ID: 1, Title: "The Go Programming Language", Author: "Donovan"}
    out, err := xml.MarshalIndent(b, "", "  ")
    if err != nil {
        panic(err)
    }
    fmt.Println(xml.Header + string(out))
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Decode XML into a struct with `xml.Unmarshal`. Fields without a tag use their lowercased name. Unknown elements are silently ignored by default.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "encoding/xml"
    "fmt"
)

type Book struct {
    XMLName xml.Name `xml:"book"`
    ID      int      `xml:"id,attr"`
    Title   string   `xml:"title"`
    Author  string   `xml:"author"`
}

func main() {
    data := []byte(`<book id="42"><title>The Go Programming Language</title><author>Donovan</author></book>`)

    var b Book
    if err := xml.Unmarshal(data, &b); err != nil {
        panic(err)
    }
    fmt.Printf("ID:%d Title:%s Author:%s\n", b.ID, b.Title, b.Author)
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Use `xml.Decoder` for streaming. It reads tokens one at a time and avoids loading the full document into memory - essential for large XML files or feeds.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "encoding/xml"
    "fmt"
    "strings"
)

type Item struct {
    Title string `xml:"title"`
}

func main() {
    feed := `<feed><item><title>First</title></item><item><title>Second</title></item></feed>`

    dec := xml.NewDecoder(strings.NewReader(feed))
    for {
        tok, err := dec.Token()
        if err != nil {
            break // io.EOF
        }
        if se, ok := tok.(xml.StartElement); ok && se.Name.Local == "item" {
            var item Item
            dec.DecodeElement(&item, &se)
            fmt.Println(item.Title)
        }
    }
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
XML is common in enterprise integrations, SOAP services, and RSS/Atom feeds. `encoding/xml` handles straightforward cases well, but for large XML streams use `xml.Decoder` token-by-token to avoid loading the entire document into memory - a 500 MB XML export will OOM your service if passed to `xml.Unmarshal`. For namespace-heavy XML (SOAP envelopes, XHTML), embed `xml.Name` with the `Space` field to match qualified names precisely. When generating XML for third-party consumers, always test the output against their schema validator - whitespace, attribute ordering, and namespace prefixes can all cause rejections even when the data is structurally correct.
</InProduction>


encoding/xml Marshal and Unmarshal, struct tags for element and attribute mapping, streaming with Encoder/Decoder, and handling namespaces.