add go.mod, tests, CI workflow, and fix issues

- Add go.mod for Go 1.24
- Add comprehensive tests for all functions
- Add GitHub Actions workflow for Go 1.24/1.25
- Add bounds checking to readint31n
- Deprecate Simple and SimpleFastReader with security warnings
- Update to math/rand/v2 API
- Improve documentation for all exports
- Make Makefile portable

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: MagicalTux

.github/workflows/test.yml

@@ -0,0 +1,37 @@
+name: Test
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        go-version: ['1.24', '1.25']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Go ${{ matrix.go-version }}
+        uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go-version }}
+
+      - name: Build
+        run: go build -v ./...
+
+      - name: Test
+        run: go test -v -race ./...
+
+      - name: Test Coverage
+        run: go test -coverprofile=coverage.out ./...
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.out
+          fail_ci_if_error: false

Makefile

@@ -1,20 +1,18 @@
 #!/bin/make
 
-GOROOT:=$(shell PATH="/pkg/main/dev-lang.go/bin:$$PATH" go env GOROOT)
-GO_TAG:=$(shell /bin/sh -c 'eval `$(GOROOT)/bin/go tool dist env`; echo "$${GOOS}_$${GOARCH}"')
-GIT_TAG:=$(shell git rev-parse --short HEAD)
-GOPATH:=$(shell $(GOROOT)/bin/go env GOPATH)
+.PHONY: all test fmt
 
-all: build
+all: fmt build
 
-.PHONY: build test deps
+fmt:
+	goimports -w -l . || gofmt -w -l .
 
 build:
-	$(GOPATH)/bin/goimports -w -l .
-	$(GOROOT)/bin/go build ./...
+	go build -v ./...
 
 test:
-	$(GOROOT)/bin/go test -v ./...
+	go test -v ./...
 
-deps:
-	$(GOROOT)/bin/go get -v -t .
+coverage:
+	go test -coverprofile=coverage.out ./...
+	go tool cover -html=coverage.out -o coverage.html

go.mod

@@ -0,0 +1,3 @@
+module github.com/KarpelesLab/rndstr
+
+go 1.24

rand.go

@@ -2,9 +2,13 @@ package rndstr
 
 import (
 	"encoding/binary"
+	"errors"
 	"io"
 )
 
+// ErrInvalidRange is returned when an invalid range parameter is provided.
+var ErrInvalidRange = errors.New("rndstr: range must be greater than zero")
+
 func readuint32(r io.Reader) (uint32, error) {
 	b := make([]byte, 4)
 	_, err := io.ReadFull(r, b)
@@ -54,6 +58,9 @@ func readuint32(r io.Reader) (uint32, error) {
 // https://lemire.me/blog/2016/06/27/a-fast-alternative-to-the-modulo-reduction
 // https://lemire.me/blog/2016/06/30/fast-random-shuffling
 func readint31n(r io.Reader, n int32) (int32, error) {
+	if n <= 0 {
+		return 0, ErrInvalidRange
+	}
 	v, err := readuint32(r)
 	if err != nil {
 		return 0, err

rand_test.go

@@ -0,0 +1,146 @@
+package rndstr
+
+import (
+	"bytes"
+	"crypto/rand"
+	"encoding/binary"
+	"io"
+	"testing"
+)
+
+func TestReaduint32(t *testing.T) {
+	tests := []struct {
+		name    string
+		input   []byte
+		want    uint32
+		wantErr bool
+	}{
+		{"zero", []byte{0, 0, 0, 0}, 0, false},
+		{"one", []byte{1, 0, 0, 0}, 1, false},
+		{"max", []byte{255, 255, 255, 255}, 0xFFFFFFFF, false},
+		{"mixed", []byte{0x78, 0x56, 0x34, 0x12}, 0x12345678, false},
+		{"short", []byte{1, 2, 3}, 0, true},
+		{"empty", []byte{}, 0, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			r := bytes.NewReader(tt.input)
+			got, err := readuint32(r)
+			if (err != nil) != tt.wantErr {
+				t.Errorf("readuint32() error = %v, wantErr %v", err, tt.wantErr)
+				return
+			}
+			if !tt.wantErr && got != tt.want {
+				t.Errorf("readuint32() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestReadint31n(t *testing.T) {
+	tests := []struct {
+		name    string
+		n       int32
+		wantErr error
+	}{
+		{"positive", 100, nil},
+		{"one", 1, nil},
+		{"large", 1000000, nil},
+		{"zero", 0, ErrInvalidRange},
+		{"negative", -1, ErrInvalidRange},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := readint31n(rand.Reader, tt.n)
+			if err != tt.wantErr {
+				t.Errorf("readint31n(rand.Reader, %d) error = %v, want %v", tt.n, err, tt.wantErr)
+				return
+			}
+			if tt.wantErr == nil {
+				if got < 0 || got >= tt.n {
+					t.Errorf("readint31n(rand.Reader, %d) = %d, want [0, %d)", tt.n, got, tt.n)
+				}
+			}
+		})
+	}
+}
+
+func TestReadint31nDistribution(t *testing.T) {
+	const n = 10
+	const iterations = 10000
+	counts := make([]int, n)
+
+	for i := 0; i < iterations; i++ {
+		v, err := readint31n(rand.Reader, n)
+		if err != nil {
+			t.Fatalf("readint31n error: %v", err)
+		}
+		if v < 0 || v >= n {
+			t.Fatalf("readint31n returned out of range value: %d", v)
+		}
+		counts[v]++
+	}
+
+	expected := float64(iterations) / float64(n)
+	tolerance := expected * 0.2 // 20% tolerance
+
+	for i, count := range counts {
+		if float64(count) < expected-tolerance || float64(count) > expected+tolerance {
+			t.Errorf("readint31n distribution: value %d appeared %d times, expected ~%.0f (tolerance %.0f)",
+				i, count, expected, tolerance)
+		}
+	}
+}
+
+func TestReadint31nReadError(t *testing.T) {
+	r := bytes.NewReader([]byte{1, 2}) // only 2 bytes, need 4
+	_, err := readint31n(r, 10)
+	if err == nil {
+		t.Error("readint31n with short reader should return error")
+	}
+}
+
+type deterministicReader struct {
+	values []uint32
+	pos    int
+}
+
+func (d *deterministicReader) Read(p []byte) (n int, err error) {
+	if d.pos >= len(d.values) {
+		return 0, io.EOF
+	}
+	binary.LittleEndian.PutUint32(p, d.values[d.pos])
+	d.pos++
+	return 4, nil
+}
+
+func TestReadint31nRejectionSampling(t *testing.T) {
+	// Test that rejection sampling works correctly
+	// For n=3, threshold = (2^32 - 3) % 3 = 1
+	// Values where (v * n) & 0xFFFFFFFF < threshold should be rejected
+
+	// Create a reader that first returns a value that should be rejected,
+	// then a value that should be accepted
+	dr := &deterministicReader{
+		values: []uint32{0, 0x55555555}, // First rejected, second accepted
+	}
+
+	got, err := readint31n(dr, 3)
+	if err != nil {
+		t.Fatalf("readint31n error: %v", err)
+	}
+	// The second value 0x55555555 * 3 = 0xFFFFFFFF
+	// High 32 bits = 0, so result should be 1
+	expected := int32((uint64(0x55555555) * 3) >> 32)
+	if got != expected {
+		t.Errorf("readint31n with rejection = %d, want %d", got, expected)
+	}
+}
+
+func BenchmarkReadint31n(b *testing.B) {
+	for i := 0; i < b.N; i++ {
+		readint31n(rand.Reader, 62)
+	}
+}

range.go

@@ -1,10 +1,17 @@
 package rndstr
 
-// various constants for easy code generation
-
+// Character sets for random string generation.
 const (
-	Alpha    = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
-	Alnum    = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
-	Code     = "ABCDEFGHJKLMNPRSTUVWXYZ23456789"
+	// Alpha contains lowercase and uppercase ASCII letters.
+	Alpha = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
+
+	// Alnum contains lowercase and uppercase ASCII letters plus digits.
+	Alnum = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+
+	// Code contains uppercase letters and digits, excluding ambiguous
+	// characters (I, O, Q, 0, 1) for improved human readability.
+	Code = "ABCDEFGHJKLMNPRSTUVWXYZ23456789"
+
+	// Password contains alphanumeric characters plus common special characters.
 	Password = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789&~#([-|_^@)]{}$*,?;.:/!<>"
 )

range_test.go

@@ -0,0 +1,120 @@
+package rndstr
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestAlpha(t *testing.T) {
+	if len(Alpha) != 52 {
+		t.Errorf("Alpha length = %d, want 52", len(Alpha))
+	}
+
+	for _, c := range "abcdefghijklmnopqrstuvwxyz" {
+		if !strings.ContainsRune(Alpha, c) {
+			t.Errorf("Alpha missing lowercase %c", c)
+		}
+	}
+
+	for _, c := range "ABCDEFGHIJKLMNOPQRSTUVWXYZ" {
+		if !strings.ContainsRune(Alpha, c) {
+			t.Errorf("Alpha missing uppercase %c", c)
+		}
+	}
+}
+
+func TestAlnum(t *testing.T) {
+	if len(Alnum) != 62 {
+		t.Errorf("Alnum length = %d, want 62", len(Alnum))
+	}
+
+	for _, c := range "abcdefghijklmnopqrstuvwxyz" {
+		if !strings.ContainsRune(Alnum, c) {
+			t.Errorf("Alnum missing lowercase %c", c)
+		}
+	}
+
+	for _, c := range "ABCDEFGHIJKLMNOPQRSTUVWXYZ" {
+		if !strings.ContainsRune(Alnum, c) {
+			t.Errorf("Alnum missing uppercase %c", c)
+		}
+	}
+
+	for _, c := range "0123456789" {
+		if !strings.ContainsRune(Alnum, c) {
+			t.Errorf("Alnum missing digit %c", c)
+		}
+	}
+}
+
+func TestCode(t *testing.T) {
+	if len(Code) != 31 {
+		t.Errorf("Code length = %d, want 31", len(Code))
+	}
+
+	// Verify ambiguous characters are excluded
+	ambiguous := "IOQ01"
+	for _, c := range ambiguous {
+		if strings.ContainsRune(Code, c) {
+			t.Errorf("Code should not contain ambiguous character %c", c)
+		}
+	}
+
+	// Verify expected characters are present
+	for _, c := range "ABCDEFGHJKLMNPRSTUVWXYZ23456789" {
+		if !strings.ContainsRune(Code, c) {
+			t.Errorf("Code missing expected character %c", c)
+		}
+	}
+}
+
+func TestPassword(t *testing.T) {
+	if len(Password) != 87 {
+		t.Errorf("Password length = %d, want 87", len(Password))
+	}
+
+	// Verify alphanumeric characters are present
+	for _, c := range "abcdefghijklmnopqrstuvwxyz" {
+		if !strings.ContainsRune(Password, c) {
+			t.Errorf("Password missing lowercase %c", c)
+		}
+	}
+
+	for _, c := range "ABCDEFGHIJKLMNOPQRSTUVWXYZ" {
+		if !strings.ContainsRune(Password, c) {
+			t.Errorf("Password missing uppercase %c", c)
+		}
+	}
+
+	for _, c := range "0123456789" {
+		if !strings.ContainsRune(Password, c) {
+			t.Errorf("Password missing digit %c", c)
+		}
+	}
+
+	// Verify some special characters are present
+	for _, c := range "&~#@!" {
+		if !strings.ContainsRune(Password, c) {
+			t.Errorf("Password missing special character %c", c)
+		}
+	}
+}
+
+func TestNoDuplicates(t *testing.T) {
+	charsets := map[string]string{
+		"Alpha":    Alpha,
+		"Alnum":    Alnum,
+		"Code":     Code,
+		"Password": Password,
+	}
+
+	for name, charset := range charsets {
+		seen := make(map[rune]bool)
+		for _, c := range charset {
+			if seen[c] {
+				t.Errorf("%s contains duplicate character %c", name, c)
+			}
+			seen[c] = true
+		}
+	}
+}