
Go's `math/rand/v2` package (Go 1.22+) provides pseudo-random number generation for simulations and non-security use cases. For anything security-sensitive - tokens, session IDs, nonces - use `crypto/rand`.

<ExamplePair>
<ExampleProse>

`math/rand/v2` is auto-seeded in Go 1.22+. Call global functions directly - no setup required. `rand.IntN(n)` returns a non-negative random integer in [0, n). `rand.Float64()` returns a float in [0.0, 1.0).

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "math/rand/v2"
)

func main() {
    // Random int in [0, 100)
    fmt.Println(rand.IntN(100))

    // Random float in [0.0, 1.0)
    fmt.Println(rand.Float64())

    // Simulate a d6 roll
    roll := rand.IntN(6) + 1
    fmt.Println("d6:", roll)

    // Shuffle a slice
    s := []int{1, 2, 3, 4, 5}
    rand.Shuffle(len(s), func(i, j int) {
        s[i], s[j] = s[j], s[i]
    })
    fmt.Println(s)
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Create a local `rand.Rand` with an explicit source when you need reproducible output (e.g., in tests) or an isolated random stream that does not share state with global functions.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "math/rand/v2"
)

func main() {
    // Seeded source - deterministic output
    src := rand.NewPCG(42, 0)
    r := rand.New(src)

    fmt.Println(r.IntN(100))
    fmt.Println(r.IntN(100))

    // Same seed → same sequence
    src2 := rand.NewPCG(42, 0)
    r2 := rand.New(src2)
    fmt.Println(r2.IntN(100)) // same as first value above
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Use `crypto/rand` for cryptographically secure randomness. `rand.Read` fills a byte slice with random bytes from the OS. Encode with `base64.RawURLEncoding` to produce a URL-safe token string.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "crypto/rand"
    "encoding/base64"
    "fmt"
)

func secureToken(n int) string {
    b := make([]byte, n)
    if _, err := rand.Read(b); err != nil {
        panic(err)
    }
    return base64.RawURLEncoding.EncodeToString(b)
}

func main() {
    token := secureToken(32) // 256 bits of entropy
    fmt.Println(token)       // e.g. "dGhpcyBpcyBhIHRlc3Q..."

    // Random UUID v4 (simplified)
    var uuid [16]byte
    rand.Read(uuid[:])
    uuid[6] = (uuid[6] & 0x0f) | 0x40 // version 4
    uuid[8] = (uuid[8] & 0x3f) | 0x80 // variant bits
    fmt.Printf("%x-%x-%x-%x-%x\n",
        uuid[0:4], uuid[4:6], uuid[6:8], uuid[8:10], uuid[10:])
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
`math/rand/v2` is auto-seeded and safe for simulation, load testing, random sampling, and shuffling. Never use it for security-sensitive randomness - tokens, passwords, nonces, CSRF values, API keys. Use `crypto/rand` for all of those. The practical pattern: generate N bytes from `crypto/rand.Read`, base64url-encode them, and you have an opaque token with N*8 bits of entropy. 32 bytes (256 bits) is the conventional floor for tokens. For generating UUIDs in production, use the `github.com/google/uuid` package rather than rolling your own - it handles version 4 correctly and is extensively tested. In tests that need deterministic sequences (property tests, golden file generators), use `rand.NewPCG` with a fixed seed so failures are reproducible without relying on a global random state.
</InProduction>


math/rand/v2 for general-purpose randomness, global functions vs local Source, and crypto/rand for cryptographically secure randomness.

Random Numbers


The `strconv` package converts between strings and numeric types. `Atoi` is a shorthand for converting a decimal string to `int`; the `Parse*` functions give full control over base and bit size.

<ExamplePair>
<ExampleProse>

`strconv.Atoi` converts a decimal string to `int`. It returns both the value and an error. Always check the error - a failed parse returns `0`, which is also a valid integer.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "strconv"
)

func main() {
    n, err := strconv.Atoi("42")
    if err != nil {
        panic(err)
    }
    fmt.Println(n) // 42

    _, err = strconv.Atoi("abc")
    fmt.Println(err) // strconv.Atoi: parsing "abc": invalid syntax
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`strconv.ParseInt` parses a string in any base (2–36) and returns an `int64`. The `bitSize` argument (8, 16, 32, 64) specifies the integer type the result must fit into - it does not limit the input string, only the return type's range.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "strconv"
)

func main() {
    // base 10, fits in int64
    i64, _ := strconv.ParseInt("255", 10, 64)
    fmt.Println(i64) // 255

    // base 2 (binary)
    bin, _ := strconv.ParseInt("11111111", 2, 64)
    fmt.Println(bin) // 255

    // base 16 (hex), constrained to int8 range
    _, err := strconv.ParseInt("200", 16, 8) // 0x200 = 512, overflows int8
    fmt.Println(err)
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`strconv.ParseFloat` converts a string to `float64` or `float32`. `strconv.FormatInt` and `strconv.Itoa` go the other direction - number to string.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "strconv"
)

func main() {
    f, _ := strconv.ParseFloat("3.14159", 64)
    fmt.Printf("%.5f\n", f) // 3.14159

    // int to string
    s := strconv.Itoa(42)
    fmt.Println(s + " is the answer") // 42 is the answer

    // int64 to hex string
    hex := strconv.FormatInt(255, 16)
    fmt.Println(hex) // ff
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
Always check the error from `strconv` functions - a `0` return on failure is the zero value, not a successfully parsed zero. `ParseInt`'s `bitSize` parameter specifies the target type's range, not a cap on the input string; passing `"200"` with `bitSize=8` returns an overflow error because 200 doesn't fit in an `int8`, but the string itself is still valid. Prefer `strconv` over `fmt.Sscanf` for number parsing: `Sscanf` is slower, less precise, and its error messages are harder to act on. In HTTP handlers that parse numeric path or query parameters, always validate with `strconv` at the boundary and return a 400 before the parsed value reaches business logic.
</InProduction>


strconv.Atoi and ParseInt for integers, ParseFloat for floats, FormatInt and Itoa for the reverse, and error handling on invalid input.

Number Parsing


Go formats and parses time using a reference time rather than format codes. The reference time is `Mon Jan 2 15:04:05 MST 2006` - a specific moment whose components form a mnemonic: month=1, day=2, hour=3, minute=4, second=5, year=6.

<ExamplePair>
<ExampleProse>

Format a `time.Time` by constructing a layout string from the reference time's components. `time.RFC3339` and similar constants provide commonly used layouts. Custom layouts are built from the same reference components.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "time"
)

func main() {
    t := time.Date(2024, 3, 15, 14, 30, 0, 0, time.UTC)

    // Predefined layouts
    fmt.Println(t.Format(time.RFC3339))       // 2024-03-15T14:30:00Z
    fmt.Println(t.Format(time.RFC1123))       // Fri, 15 Mar 2024 14:30:00 UTC
    fmt.Println(t.Format(time.DateOnly))      // 2024-03-15
    fmt.Println(t.Format(time.TimeOnly))      // 14:30:00

    // Custom layouts use the reference time components
    fmt.Println(t.Format("January 2, 2006"))           // March 15, 2024
    fmt.Println(t.Format("02 Jan 2006 15:04"))         // 15 Mar 2024 14:30
    fmt.Println(t.Format("3:04 PM on Monday"))         // 2:30 PM on Friday
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Parse a time string with `time.Parse(layout, value)`. The layout must match the reference time pattern. `time.ParseInLocation` parses relative to a specific timezone to avoid silent UTC interpretation.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "time"
)

func main() {
    // Parse RFC3339 (always includes timezone offset)
    t, err := time.Parse(time.RFC3339, "2024-03-15T14:30:00Z")
    if err != nil {
        panic(err)
    }
    fmt.Println(t) // 2024-03-15 14:30:00 +0000 UTC

    // Parse with a custom layout
    t2, err := time.Parse("January 2, 2006", "March 15, 2024")
    if err != nil {
        panic(err)
    }
    fmt.Println(t2) // 2024-03-15 00:00:00 +0000 UTC

    // Parse in a specific location
    loc, _ := time.LoadLocation("America/New_York")
    t3, _ := time.ParseInLocation("2006-01-02 15:04", "2024-03-15 14:30", loc)
    fmt.Println(t3) // 2024-03-15 14:30:00 -0400 EDT
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Convert between timezones with `t.In(loc)`. `time.UTC` and `time.Local` are pre-loaded locations. Use `time.LoadLocation` for named IANA timezone strings like `"America/Los_Angeles"`.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "time"
)

func main() {
    utc := time.Date(2024, 3, 15, 18, 0, 0, 0, time.UTC)
    fmt.Println("UTC:", utc.Format(time.RFC3339))

    ny, _ := time.LoadLocation("America/New_York")
    fmt.Println("NYC:", utc.In(ny).Format(time.RFC3339))

    tokyo, _ := time.LoadLocation("Asia/Tokyo")
    fmt.Println("Tokyo:", utc.In(tokyo).Format(time.RFC3339))

    // Format for display without timezone info
    fmt.Println(utc.Format("Mon, 02 Jan 2006 15:04:05"))
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
Go's reference-time format string is the most surprising API in the stdlib - the numbers (1 2 3 4 5 6 7) correspond to month, day, hour, minute, second, year, timezone offset. Memorize the mnemonic or keep it in a comment near your format strings. Always parse user-supplied time strings with `time.ParseInLocation` using an explicit `time.Location` - `time.Parse` with a layout that lacks timezone info (like `"2006-01-02"`) interprets the result as UTC, which silently converts a user's "today in Tokyo" to yesterday in UTC. Always call `.UTC()` after parsing before storing. When accepting times from external APIs, validate that the string is RFC3339 - it is the only format that is unambiguous and includes timezone offset. Log and return clear errors when parsing fails; a zero `time.Time{}` is January 1, year 1, which will produce confusing timestamps if silently accepted.
</InProduction>


time.Format with Go's reference time, time.Parse, time.RFC3339 and other constants, and location-aware parsing.