randutil

package module
v1.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 16, 2025 License: MIT Imports: 7 Imported by: 1

README

randutil

Secure random helpers for numbers, strings/bytes, time, and collections.

Install

import "github.com/aatuh/randutil"

Quick start

s := random.MustString(12)           // a1b2c3...
n := random.MustIntRange(1, 10)      // 1..10 inclusive
b := random.MustBool()               // true/false
t := random.MustDatetime()           // random time
e := random.MustEmail(16)            // local@domain.com (~16 chars)
c := random.MustChoice("a", "b", "c") // one of the args

Numbers

  • Int ranges: IntRange, AnyInt
  • int32: Int32Range, AnyInt32, PositiveInt32, NegativeInt32
  • int64: Int64Range, AnyInt64, PositiveInt64, NegativeInt64
i, err := random.IntRange(10, 20)

Strings and bytes

  • Random strings: String(length) (lowercase+digits)
  • Custom charset: GetWithCustomCharset(length, charset)
  • Base64 bytes: Base64(byteLen)
  • Hex string: Hex(strLen) (strLen must be even)
  • Slices: StringSlice(count, minLen, maxLen)
hex, _ := random.Hex(32)
b64, _ := random.Base64(24)
word, _ := random.String(8)

Collections

  • Pick/shuffle: SlicePickOne, SlicePickMany, Shuffle, Choice
v, _ := random.SlicePickOne([]any{"x", 2, true})
items := random.MustSlicePickMany([]any{1,2,3,4}, 50) // ~50% picked
arr := []any{1,2,3,4}; random.MustShuffle(arr)

Time

  • Datetime() random time.Time
  • TimeInNearPast() / TimeInNearFuture() (±5–10 minutes)
past := random.MustTimeInNearPast()
future := random.MustTimeInNearFuture()

Email

  • Email(totalLength) builds local@domain.com of approx total length
addr := random.MustEmail(20)

Notes

  • Uses crypto/rand throughout.
  • All numeric ranges are inclusive.
  • Must* variants panic on error.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AnyInt 

func AnyInt() (int, error)

AnyInt returns a secure random int from the full range of int.

Returns:

  • int: A random int in [-2147483647, 2147483648].
  • error: An error if crypto/rand fails.

func AnyInt32 

func AnyInt32() (int32, error)

AnyInt32 returns a random int32 in the full int32 range.

Returns:

  • int32: A random int32 in [-2147483647, 2147483648].
  • error: An error if crypto/rand fails.

func AnyInt64 

func AnyInt64() (int64, error)

AnyInt64 returns a secure random int64 in the full int64 range.

Returns:

  • int64: A random int64 in [-9223372036854775808, 9223372036854775807].
  • error: An error if crypto/rand fails.

func Base64 

func Base64(byteLen int) (string, error)

Base64 returns a base64 encoded random string built from byteLen random bytes.

Parameters:

  • byteLen: The length of the random bytes.

Returns:

  • string: Base64 encoded random string.
  • error: An error if crypto/rand fails.

func Bool 

func Bool() (bool, error)

Bool returns a secure random boolean.

Returns:

  • bool: A random boolean value.
  • error

func Choice 

func Choice(choices ...any) (any, error)

Choice returns a random choice from the provided arguments.

Returns:

  • any: A random choice from the provided arguments.
  • error: An error if crypto/rand fails.

func Datetime 

func Datetime() (time.Time, error)

Datetime returns a secure random time between year 1 and 9999.

Returns:

  • time.Time: A random time between year 1 and 9999.
  • error: An error if crypto/rand fails.

func Email 

func Email(totalLength int) (string, error)

Email returns a random email address of totalLength characters. The email is built as local@domain.com (5 characters reserved for "@" and ".com"). totalLength must be at least 6.

Returns:

  • string: A random email address.
  • error: An error if crypto/rand fails.

func GetWithCustomCharset 

func GetWithCustomCharset(length int, charset string) (string, error)

GetWithCustomCharset returns a random string of length characters drawn from the provided charset.

Parameters:

  • length: The length of the random string.
  • charset: The characters to draw from.

Returns:

  • string: A random string of length characters drawn from the provided charset.
  • error: An error if crypto/rand fails.

func Hex 

func Hex(strLen int) (string, error)

Hex returns a random hexadecimal string of length strLen. strLen must be even or it will return an error.

Parameters:

  • strLen: The length of the random hexadecimal string.

Returns:

  • string: A random hexadecimal string of length strLen.
  • error: An error if crypto/rand fails or strLen is not even.

func Int32Range 

func Int32Range(minInclusive int32, maxInclusive int32) (int32, error)

Int32Range returns a secure random int32 in [minInclusive, maxInclusive].

Parameters: - minInclusive: The minimum value (inclusive). - maxInclusive: The maximum value (inclusive).

Returns:

  • int32: A random int32 in [minInclusive, maxInclusive].
  • error: An error if crypto/rand fails.

func Int64Range 

func Int64Range(minInclusive int64, maxInclusive int64) (int64, error)

Int64Range returns a secure random int64 in [minInclusive, maxInclusive].

Parameters: - minInclusive: The minimum value (inclusive). - maxInclusive: The maximum value (inclusive).

Returns:

  • int64: A random int64 in [minInclusive, maxInclusive].
  • error: An error if crypto/rand fails.

func IntRange 

func IntRange(minInclusive int, maxInclusive int) (int, error)

IntRange returns a secure random int in [minInclusive, maxInclusive].

Parameters: - minInclusive: The minimum value (inclusive). - maxInclusive: The maximum value (inclusive).

Returns:

  • int: A random int in [minInclusive, maxInclusive].
  • error: An error if crypto/rand fails.

func MustAnyInt 

func MustAnyInt() int

MustAnyInt returns a secure random int from the full range of int. It panics if an error occurs.

Returns:

  • int: A random int in [-2147483647, 2147483648].

func MustAnyInt32 

func MustAnyInt32() int32

MustAnyInt32 returns a random int32 in the full int32 range. It panics if an error occurs.

Returns:

  • int32: A random int32 in [-2147483647, 2147483648].

func MustAnyInt64 

func MustAnyInt64() int64

MustAnyInt64 returns a secure random int64 in the full int64 range. It panics if an error occurs.

Returns:

  • int64: A random int64 in [-9223372036854775808, 9223372036854775807].

func MustBase64 

func MustBase64(byteLen int) string

Base64 returns a base64 encoded random string built from byteLen random bytes. It panics if an error occurs.

Parameters:

  • byteLen: The length of the random bytes.

Returns:

  • string: Base64 encoded random string.

func MustBool 

func MustBool() bool

Bool returns a secure random boolean. It panics if an error occurs.

Returns:

  • bool

func MustChoice 

func MustChoice(choices ...any) any

MustChoice returns a random choice from the provided arguments. It panics if an error occurs.

Parameters:

  • choices: A slice of any type.

func MustDatetime 

func MustDatetime() time.Time

Datetime returns a secure random time between year 1 and 9999. It panics if an error occurs.

Returns:

  • time.Time: A random time between year 1 and 9999.

func MustEmail 

func MustEmail(totalLength int) string

Email returns a random email address of totalLength characters. It panics on error.

Returns:

  • string: A random email address.

func MustGetWithCustomCharset 

func MustGetWithCustomCharset(length int,
	charset string) string

MustGetWithCustomCharset returns a random string of length characters drawn from the provided charset. It panics if an error occurs.

func MustHex 

func MustHex(strLen int) string

MustHex returns a random hexadecimal string of length strLen. It panics if an error occurs.

Parameters:

  • strLen: The length of the random hexadecimal string.

Returns:

  • string: A random hexadecimal string of length strLen.

func MustInt32Range 

func MustInt32Range(minInclusive int32, maxInclusive int32) int32

MustInt32Range returns a secure random int32 in [minInclusive, maxInclusive]. It panics if an error occurs.

Parameters: - minInclusive: The minimum value (inclusive). - maxInclusive: The maximum value (inclusive).

Returns:

  • int32: A random int32 in [minInclusive, maxInclusive].

func MustInt64Range 

func MustInt64Range(minInclusive int64, maxInclusive int64) int64

MustInt64Range returns a secure random int64 in [minInclusive, maxInclusive]. It panics if an error occurs.

Parameters: - minInclusive: The minimum value (inclusive). - maxInclusive: The maximum value (inclusive).

Returns:

  • int64: A random int64 in [minInclusive, maxInclusive].

func MustIntRange 

func MustIntRange(minInclusive int, maxInclusive int) int

MustIntRange returns a secure random int in [minInclusive, maxInclusive]. It panics if an error occurs.

Parameters: - minInclusive: The minimum value (inclusive). - maxInclusive: The maximum value (inclusive).

Returns:

  • int: A random int in [minInclusive, maxInclusive].

func MustNegativeInt32 

func MustNegativeInt32() int32

MustNegativeInt32 returns a secure random negative int32. It panics if an error occurs.

Returns:

  • int32: A random int32 in [-2147483647, -1].

func MustNegativeInt64 

func MustNegativeInt64() int64

MustNegativeInt64 returns a secure random negative int64. It panics if an error occurs.

Returns:

  • int64: A random int64 in [-9223372036854775808, -1].

func MustPositiveInt32 

func MustPositiveInt32() int32

MustPositiveInt32 returns a secure random positive int32. It panics if an error occurs.

Returns:

  • int32: A random int32 in [1, 2147483648].

func MustPositiveInt64 

func MustPositiveInt64() int64

MustPositiveInt64 returns a secure random positive int64. It panics if an error occurs.

Returns:

  • int64: A random int64 in [1, 9223372036854775807].

func MustShuffle 

func MustShuffle(slice []any)

MustShuffle performs an in-place secure Fisher–Yates shuffle of the slice. It panics if an error occurs.

Parameters:

  • slice: A slice of any type.

func MustSlicePickMany 

func MustSlicePickMany(slice []any, chanceThreshold int) []any

MustSlicePickMany returns a subset of items from the slice. It panics if an error occurs.

Parameters:

  • slice: A slice of any type.
  • chanceThreshold: An integer between 0 and 100.

Returns:

  • []any: A slice of any type.

func MustSlicePickOne 

func MustSlicePickOne(slice []any) any

MustSlicePickOne returns one random element from the slice. It panics if an error occurs.

Parameters:

  • slice: A slice of any type.

Returns:

  • any: A random element from the slice.

func MustString 

func MustString(length int) string

MustString returns a secure random string of the given length using the default charset (lowerCaseAndNumbers). It panics if an error occurs.

Parameters:

  • length: The length of the random string.

Returns:

  • string: A random string of length characters drawn from the default

func MustStringSlice 

func MustStringSlice(sliceLength, minStrLen,
	maxStrLen int) []string

StringSlice returns a slice of random strings. It panics if an error occurs.

Parameters:

  • sliceLength: The length of the slice.
  • minStrLen: The minimum length of each string.
  • maxStrLen: The maximum length of each string.

Returns:

  • []string: A slice of random strings.

func MustTimeInNearFuture 

func MustTimeInNearFuture() time.Time

TimeInNearFuture returns a time a few minutes in the future. It panics if an error occurs.

Returns:

  • time.Time: A time a few minutes in the future.

func MustTimeInNearPast 

func MustTimeInNearPast() time.Time

TimeInNearPast returns a time a few minutes in the past. It panics if an error occurs.

Returns:

  • time.Time: A time a few minutes in the past.

func NegativeInt32 

func NegativeInt32() (int32, error)

NegativeInt32 returns a secure random negative int32.

Returns:

  • int32: A random int32 in [-2147483647, -1].
  • error: An error if crypto/rand fails.

func NegativeInt64 

func NegativeInt64() (int64, error)

NegativeInt64 returns a secure random negative int64.

Returns:

  • int64: A random int64 in [-9223372036854775808, -1].
  • error: An error if crypto/rand fails.

func PositiveInt32 

func PositiveInt32() (int32, error)

PositiveInt32 returns a secure random positive int32.

Returns:

  • int32: A random int32 in [1, 2147483648].
  • error: An error if crypto/rand fails.

func PositiveInt64 

func PositiveInt64() (int64, error)

PositiveInt64 returns a secure random positive int64.

Returns:

  • int64: A random int64 in [1, 9223372036854775807].
  • error: An error if crypto/rand fails.

func Shuffle 

func Shuffle(slice []any) error

Shuffle performs an in-place secure Fisher–Yates shuffle of the slice.

Returns:

  • error: An error if crypto/rand fails.

func SlicePickMany 

func SlicePickMany(slice []any, chanceThreshold int) ([]any, error)

SlicePickMany returns a subset of items from the slice. For each item, a random chance is compared with chanceThreshold (0-100) to decide if it should be included.

Parameters:

  • slice: A slice of any type.
  • chanceThreshold: An integer between 0 and 100.

Returns:

  • []any: A slice of any type.
  • error: An error if crypto/rand fails.

func SlicePickOne 

func SlicePickOne(slice []any) (any, error)

SlicePickOne returns one random element from the slice. Returns an error if the slice is empty.

Returns:

  • any: A random element from the slice.
  • error: An error if the slice is empty or if crypto/rand fails.

func String 

func String(length int) (string, error)

String returns a secure random string of the given length using the default charset (lowerCaseAndNumbers).

Parameters:

  • length: The length of the random string.

Returns:

  • string: A random string of length characters drawn from the default charset.
  • error: An error if crypto/rand fails.

func StringSlice 

func StringSlice(
	sliceLength int, minStrLen int, maxStrLen int,
) ([]string, error)

StringSlice returns a slice of random strings. Each string length is randomly chosen between minStrLen and maxStrLen.

Parameters:

  • sliceLength: The length of the slice.
  • minStrLen: The minimum length of each string.
  • maxStrLen: The maximum length of each string.

Returns:

  • []string: A slice of random strings.
  • error: An error if crypto/rand fails.

func TimeInNearFuture 

func TimeInNearFuture() (time.Time, error)

TimeInNearFuture returns a time a few minutes in the future.

Returns:

  • time.Time: A time a few minutes in the future.
  • error: An error if crypto/rand fails.

func TimeInNearPast 

func TimeInNearPast() (time.Time, error)

TimeInNearPast returns a time a few minutes in the past.

Returns:

  • time.Time: A time a few minutes in the past.
  • error: An error if crypto/rand fails.

Types

This section is empty.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.