rands

Go package providing a suite of functions that use crypto/rand to generate cryptographically secure random data in various forms and formats.

rands package

rands is intended for use in production code where random data generation is required. All functions have a error return value which should be checked.

For tests there is the randsmust package, which has all the same functions but with single return values, and they panic in the event of an error.

Import

import "github.com/jimeh/rands"

Usage

s, err := rands.Base64(16)       // => CYxqEdUB1Rzno3SyZu2g/g==
s, err := rands.Base64URL(16)    // => zlqw9aFqcFggbk2asn3_aQ
s, err := rands.Hex(16)          // => 956e2ec9e7f19ddd58bb935826926531
s, err := rands.Alphanumeric(16) // => Fvk1PkrmG5crgOjT
s, err := rands.Alphabetic(16)   // => XEJIzcZufHkuUmRM
s, err := rands.Upper(16)        // => UMAGAFPPNDRGLUPZ
s, err := rands.UpperNumeric(16) // => DF0CQS0TK9CPUO3E
s, err := rands.Lower(16)        // => ocsmggykzrxzfwgt
s, err := rands.LowerNumeric(16) // => rwlv7a1p7klqffs5
s, err := rands.Numeric(16)      // => 9403373143598295

s, err := rands.String(16, "abcdefABCDEF")                               // => adCDCaDEdeffeDeb
s, err := rands.UnicodeString(16, []rune("九七二人入八力十下三千上口土夕大")) // => 下下口九力下土夕下土八上二夕大三

s, err := rands.DNSLabel(16) // => z0ij9o8qkbs0ru-h
s, err := rands.UUID()       // => a62b8712-f238-43ba-a47e-333f5fffe785
s, err := rands.UUIDv7()     // => 01954a31-867f-7ffb-876e-b818f960ec3b

n, err := rands.Int(2147483647)                   // => 1334400235
n, err := rands.Int64(int64(9223372036854775807)) // => 8256935979116161233

b, err := rands.Bytes(8) // => [0 220 137 243 135 204 34 63]

err := rands.Shuffle(len(arr), func(i, j) { arr[i], arr[j] = arr[j], arr[i] })
err := rands.ShuffleSlice(arr)

randsmust package

randsmust is specifically intended as an alternative to rands for use in tests. All functions return a single value, and panic in the event of an error. This makes them easy to use when building structs in test cases that need random data.

For production code, make sure to use the rands package and check returned errors.

Import

import "github.com/jimeh/rands/randsmust"

Usage

s := randsmust.Base64(16)       // => d1wm/wS6AQGduO3uaey1Cg==
s := randsmust.Base64URL(16)    // => 4pHWVcddXsL_45vhOfCdng
s := randsmust.Hex(16)          // => b5552558bc009264d129c422a666fe56
s := randsmust.Alphanumeric(16) // => j5WkpNKmW8K701XF
s := randsmust.Alphabetic(16)   // => OXxsqfFjNLvmZqDb
s := randsmust.Upper(16)        // => AOTLYQRCVNMEPRCX
s := randsmust.UpperNumeric(16) // => 1NTY6KATDVAXBTY2
s := randsmust.Lower(16)        // => xmftrwvurrritqfu
s := randsmust.LowerNumeric(16) // => yszg56fzeql7pjpl
s := randsmust.Numeric(16)      // => 0761782105447226

s := randsmust.String(16, "abcdefABCDEF")                               // => dfAbBfaDDdDFDaEa
s := randsmust.UnicodeString(16, []rune("九七二人入八力十下三千上口土夕大")) // => 十十千口三十十下九上千口七夕土口

s := randsmust.DNSLabel(16) // => pu31o0gqyk76x35f
s := randsmust.UUID()       // => d616c873-f3dd-4690-bcd6-ed307eec1105
s := randsmust.UUIDv7()     // => 01954a30-add2-7590-8238-6cf6b2790c1e

n := randsmust.Int(2147483647)                   // => 1293388115
n := randsmust.Int64(int64(9223372036854775807)) // => 6168113630900161239

b := randsmust.Bytes(8) // => [205 128 54 95 0 95 53 51]

randsmust.Shuffle(len(arr), func(i, j) { arr[i], arr[j] = arr[j], arr[i] })
randsmust.ShuffleSlice(arr)

Documentation

Please see the Go Reference for documentation and examples:

• rands
• randsmust

Benchmarks

Benchmark reports and graphs are available here: https://jimeh.me/rands/dev/bench/

License

MIT