randx

README

randx

Convenient random generation functions for Go, covering integers, floats, booleans, durations, strings, and slices.

---

CHINESE README

中文说明

Main Features

🎲 Range-Based Random: Generate random int, int64, uint64, float64 within a given range ⏱️ Duration Random: Generate random time.Duration between two bounds 🔤 String Generation: Generate random strings from customizable charsets (digits, hex, alphabet, etc.) 🔀 Shuffle: Shuffle strings and slices in place 🎯 Boolean & Rate: Random boolean with configurable rate/percentage 📋 Generic Choose: Pick a random element from any slice using generics

---

Installation

go get github.com/yylego/randx

---

Quick Start

package main

import (
	"fmt"

	"github.com/yylego/randx"
)

func main() {
	// Random int in [10, 20)
	fmt.Println(randx.IntBetween(10, 20))

	// Random boolean
	fmt.Println(randx.Boolean())

	// Random string of 16 alphanumeric chars
	fmt.Println(randx.AlphaDigits.New(16))

	// Pick a random element from a slice
	fruits := []string{"apple", "banana", "orange", "grape"}
	fmt.Println(randx.Choose(fruits))
}

---

API

Numeric Functions

Function	Description
IntBetween(a, b int) int	Random int in [min, max)
Int64Between(a, b int64) int64	Random int64 in [min, max)
Uint64Between(a, b uint64) uint64	Random uint64 in [min, max)
Float64Between(a, b float64) float64	Random float64 in [min, max)
IntSign() int	Returns +1 or -1 at random
IntPerm(n int) []int	Random sequence of [0, n)

Boolean Functions

Function	Description
Boolean() bool	50/50 random boolean
RateBoolean(n, v int) bool	True with v/n chance
PercentBoolean(v int) bool	True with v% chance

Duration Functions

Function	Description
DurationBetween(a, b time.Duration)	Random duration in [a, b)
SecondsBetween(a, b int)	Random seconds
MillisBetween(a, b int)	Random milliseconds
MicrosBetween(a, b int)	Random microseconds
MinutesBetween(a, b int)	Random minutes

String & Slice Functions

Function	Description
GenChars.New(size int) string	Generate random string from charset
GenChars.Shuffle() string	Shuffle charset chars
ShuffleString(s string) string	Shuffle a string
ShuffleSlice[T](a []T)	Shuffle a slice in place
Choose[T](a []T) T	Pick a random element

Predefined Charsets

Constant	Chars
Digits	0123456789
HexDigits	0123456789ABCDEF
Lowercase	abcdefghijklmnopqrstuvwxyz
Uppercase	ABCDEFGHIJKLMNOPQRSTUVWXYZ
Alphabet	A-Z + a-z
AlphaDigits	A-Z + a-z + 0-9

---

📄 License

MIT License - see LICENSE.

---

💬 Contact & Feedback

Contributions are welcome! Report bugs, suggest features, and contribute code:

• 🐛 Mistake reports? Open an issue on GitHub with reproduction steps
• 💡 Fresh ideas? Create an issue to discuss
• 📖 Documentation confusing? Report it so we can improve
• 🚀 Need new features? Share the use cases to help us understand requirements
• ⚡ Performance issue? Help us optimize through reporting slow operations
• 🔧 Configuration problem? Ask questions about complex setups
• 📢 Follow project progress? Watch the repo to get new releases and features
• 🌟 Success stories? Share how this package improved the workflow
• 💬 Feedback? We welcome suggestions and comments

---

🔧 Development

New code contributions, follow this process:

1. Fork: Fork the repo on GitHub (using the webpage UI).
2. Clone: Clone the forked project (git clone https://github.com/yourname/repo-name.git).
3. Navigate: Navigate to the cloned project (cd repo-name)
4. Branch: Create a feature branch (git checkout -b feature/xxx).
5. Code: Implement the changes with comprehensive tests
6. Testing: (Golang project) Ensure tests pass (go test ./...) and follow Go code style conventions
7. Documentation: Update documentation to support client-facing changes
8. Stage: Stage changes (git add .)
9. Commit: Commit changes (git commit -m "Add feature xxx") ensuring backward compatible code
10. Push: Push to the branch (git push origin feature/xxx).
11. PR: Open a merge request on GitHub (on the GitHub webpage) with detailed description.

Please ensure tests pass and include relevant documentation updates.

---

🌟 Support

Welcome to contribute to this project via submitting merge requests and reporting issues.

Project Support:

• ⭐ Give GitHub stars if this project helps you
• 🤝 Share with teammates and (golang) programming friends
• 📝 Write tech blogs about development tools and workflows - we provide content writing support
• 🌟 Join the ecosystem - committed to supporting open source and the (golang) development scene

Have Fun Coding with this package! 🎉🎉🎉

---

GitHub Stars

Documentation

Index

• func Boolean() bool
• func Choose[T any](a []T) T
• func DurationBetween(a, b time.Duration) time.Duration
• func Float64Between(a, b float64) float64
• func Int64Between(a, b int64) int64
• func IntBetween(a, b int) int
• func IntPerm(n int) []int
• func IntSign() int
• func MicrosBetween(a, b int) time.Duration
• func MillisBetween(a, b int) time.Duration
• func MinutesBetween(a, b int) time.Duration
• func PercentBoolean(v int) bool
• func RateBoolean(n, v int) bool
• func SecondsBetween(a, b int) time.Duration
• func ShuffleSlice[T any](a []T)
• func ShuffleString(s string) string
• func Uint64Between(a, b uint64) uint64
• type GenChars
  • func (cs GenChars) New(size int) string
  • func (cs GenChars) Shuffle() string

Functions

func Boolean

func Boolean() bool

Boolean returns true or false at random.

func Choose

func Choose[T any](a []T) T

Choose returns a random element from the given slice.

func DurationBetween

func DurationBetween(a, b time.Duration) time.Duration

DurationBetween returns a random duration in [a, b) or [b, a).

func Float64Between

func Float64Between(a, b float64) float64

Float64Between returns a random float64 in [a, b).

func Int64Between

func Int64Between(a, b int64) int64

Int64Between returns a random int64 in [a, b) or [b, a).

func IntBetween

func IntBetween(a, b int) int

IntBetween returns a random int in [a, b) or [b, a) depending on which is smaller.

func IntPerm

func IntPerm(n int) []int

IntPerm returns a random sequence of [0, n).

func IntSign

func IntSign() int

IntSign returns +1 or -1 at random.

func MicrosBetween

func MicrosBetween(a, b int) time.Duration

MicrosBetween returns a random duration in [a, b) microseconds.

func MillisBetween

func MillisBetween(a, b int) time.Duration

MillisBetween returns a random duration in [a, b) milliseconds.

func MinutesBetween

func MinutesBetween(a, b int) time.Duration

MinutesBetween returns a random duration in [a, b) minutes.

func PercentBoolean

func PercentBoolean(v int) bool

PercentBoolean returns true with v% chance.

func RateBoolean

func RateBoolean(n, v int) bool

RateBoolean returns true with v/n chance.

func SecondsBetween

func SecondsBetween(a, b int) time.Duration

SecondsBetween returns a random duration in [a, b) seconds.

func ShuffleSlice

func ShuffleSlice[T any](a []T)

ShuffleSlice shuffles the given slice in place.

func ShuffleString

func ShuffleString(s string) string

ShuffleString returns a shuffled copy of the given string.

func Uint64Between

func Uint64Between(a, b uint64) uint64

Uint64Between returns a random uint64 in [a, b) or [b, a).

Types

type GenChars

type GenChars string

GenChars defines a charset used to generate random strings.

const (
	Digits      GenChars = "0123456789"
	HexDigits   GenChars = Digits + "ABCDEF"
	Lowercase   GenChars = "abcdefghijklmnopqrstuvwxyz"
	Uppercase   GenChars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
	Alphabet    GenChars = Uppercase + Lowercase
	AlphaDigits GenChars = Alphabet + Digits
)

func (GenChars) New

func (cs GenChars) New(size int) string

New generates a random string of the given size using this charset.

func (GenChars) Shuffle

func (cs GenChars) Shuffle() string

Shuffle returns a shuffled copy of this charset.