test: add examples for random package

random/random.go

@@ -19,7 +19,8 @@ const (
 	LETTERS       = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
 )
 
-// RandInt generate random int between min and max, maybe min,  not be max
+// RandInt generate random int between min and max, maybe min,  not be max.
+// Play: https://go.dev/play/p/pXyyAAI5YxD
 func RandInt(min, max int) int {
 	if min == max {
 		return min
@@ -28,10 +29,12 @@ func RandInt(min, max int) int {
 		min, max = max, min
 	}
 	r := rand.New(rand.NewSource(time.Now().UnixNano()))
+
 	return r.Intn(max-min) + min
 }
 
-// RandBytes generate random byte slice
+// RandBytes generate random byte slice.
+// Play: https://go.dev/play/p/EkiLESeXf8d
 func RandBytes(length int) []byte {
 	if length < 1 {
 		return []byte{}
@@ -41,45 +44,54 @@ func RandBytes(length int) []byte {
 	if _, err := io.ReadFull(crand.Reader, b); err != nil {
 		return nil
 	}
+
 	return b
 }
 
-// RandString generate random string
+// RandString generate random string of specified length.
+// Play: https://go.dev/play/p/W2xvRUXA7Mi
 func RandString(length int) string {
 	return random(LETTERS, length)
 }
 
-// RandUpper generate a random upper case string
+// RandUpper generate a random upper case string.
+// Play: https://go.dev/play/p/29QfOh0DVuh
 func RandUpper(length int) string {
 	return random(UPPER_LETTERS, length)
 }
 
-// RandLower generate a random lower case string
+// RandLower generate a random lower case string.
+// Play: https://go.dev/play/p/XJtZ471cmtI
 func RandLower(length int) string {
 	return random(LOWER_LETTERS, length)
 }
 
-// RandNumeral generate a random numeral string
+// RandNumeral generate a random numeral string of specified length.
+// Play: https://go.dev/play/p/g4JWVpHsJcf
 func RandNumeral(length int) string {
 	return random(NUMERAL, length)
 }
 
-// RandNumeralOrLetter generate a random numeral or letter string
+// RandNumeralOrLetter generate a random numeral or letter string.
+// Play: https://go.dev/play/p/19CEQvpx2jD
 func RandNumeralOrLetter(length int) string {
 	return random(NUMERAL+LETTERS, length)
 }
 
-// random generate a random string based on given string range
+// random generate a random string based on given string range.
 func random(s string, length int) string {
 	b := make([]byte, length)
 	r := rand.New(rand.NewSource(time.Now().UnixNano()))
+
 	for i := range b {
 		b[i] = s[r.Int63()%int64(len(s))]
 	}
+
 	return string(b)
 }
 
-// UUIdV4 generate a random UUID of version 4 according to RFC 4122
+// UUIdV4 generate a random UUID of version 4 according to RFC 4122.
+// Play: https://go.dev/play/p/_Z9SFmr28ft
 func UUIdV4() (string, error) {
 	uuid := make([]byte, 16)
 

random/random_example_test.go

@@ -0,0 +1,126 @@
+package random
+
+import (
+	"fmt"
+	"regexp"
+)
+
+func ExampleRandInt() {
+
+	result := RandInt(1, 10)
+
+	if result >= 1 && result < 10 {
+		fmt.Println("ok")
+	}
+
+	// Output:
+	// ok
+}
+
+func ExampleRandBytes() {
+	bytes := RandBytes(4)
+
+	fmt.Println(len(bytes))
+
+	// Output:
+	// 4
+}
+
+func ExampleRandString() {
+	pattern := `^[a-zA-Z]+$`
+	reg := regexp.MustCompile(pattern)
+
+	s := RandString(6)
+
+	result1 := reg.MatchString(s)
+	result2 := len(s)
+
+	fmt.Println(result1)
+	fmt.Println(result2)
+
+	// Output:
+	// true
+	// 6
+}
+
+func ExampleRandUpper() {
+	pattern := `^[A-Z]+$`
+	reg := regexp.MustCompile(pattern)
+
+	s := RandUpper(6)
+
+	result1 := reg.MatchString(s)
+	result2 := len(s)
+
+	fmt.Println(result1)
+	fmt.Println(result2)
+
+	// Output:
+	// true
+	// 6
+}
+
+func ExampleRandLower() {
+	pattern := `^[a-z]+$`
+	reg := regexp.MustCompile(pattern)
+
+	s := RandLower(6)
+
+	result1 := reg.MatchString(s)
+	result2 := len(s)
+
+	fmt.Println(result1)
+	fmt.Println(result2)
+
+	// Output:
+	// true
+	// 6
+}
+
+func ExampleRandNumeral() {
+	pattern := `^[0-9]+$`
+	reg := regexp.MustCompile(pattern)
+
+	s := RandNumeral(6)
+
+	result1 := reg.MatchString(s)
+	result2 := len(s)
+
+	fmt.Println(result1)
+	fmt.Println(result2)
+
+	// Output:
+	// true
+	// 6
+}
+
+func ExampleRandNumeralOrLetter() {
+	pattern := `^[0-9a-zA-Z]+$`
+	reg := regexp.MustCompile(pattern)
+
+	s := RandNumeralOrLetter(6)
+
+	result1 := reg.MatchString(s)
+	result2 := len(s)
+
+	fmt.Println(result1)
+	fmt.Println(result2)
+
+	// Output:
+	// true
+	// 6
+}
+
+func ExampleUUIdV4() {
+	pattern := `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$`
+	reg := regexp.MustCompile(pattern)
+
+	s, _ := UUIdV4()
+
+	result := reg.MatchString(s)
+
+	fmt.Println(result)
+
+	// Output:
+	// true
+}

random/random_test.go

@@ -68,6 +68,7 @@ func TestRandInt(t *testing.T) {
 	assert := internal.NewAssert(t, "TestRandInt")
 
 	r1 := RandInt(1, 10)
+	t.Log(r1)
 	assert.GreaterOrEqual(r1, 1)
 	assert.Less(r1, 10)