feat(regexamples): add regex example generation package (#239)

* feat(regexamples): add regex example generation package

Adds a new `regexamples` package that generates random strings matching
a given regular expression. Supports all common regex constructs via
Go's stdlib `regexp/syntax` AST walker, restricts output to printable
ASCII, and exposes both a one-shot `Generate` function and a reusable
`Generator` type with optional deterministic seeding via `SetSeed`.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(regexamples): clean up dead code, add concurrency docs, and list in main README

- Remove unreachable defensive checks in pickFromRanges and randPrintable
- Eliminate redundant countRunes call via pickFromRangesN helper
- Add concurrency safety doc comment on Generator
- Fix relative link in regexamples/README.md
- Add regexamples package to main README table

Reviewed and applied via Claude Code

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

---------

Co-authored-by: yabanci <yabanciinbt@gmail.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Kashif Khan <kashifkhan_9@yahoo.com>

Author: 4 people

README.md

@@ -63,6 +63,7 @@ cd utils
 | **queue** | Queue data structure| [README](queue/README.md) | [EXAMPLES](queue/EXAMPLES.md) |
 | **rand**      | Random number and string generation utilities      | [README](rand/README.md)      | [EXAMPLES](rand/EXAMPLES.md)      |
 | **ratelimiter** | Token-bucket rate limiter (allow/wait, adjustable capacity & refill rate) | [README](ratelimiter/README.md) | [EXAMPLES](ratelimiter/EXAMPLES.md) |
+| **regexamples** | Generate random strings that match a given regular expression | [README](regexamples/README.md) | [EXAMPLES](regexamples/EXAMPLES.md) |
 | **slice**     | Slice manipulation and de-duplication utilities    | [README](slice/README.md)     | [EXAMPLES](slice/EXAMPLES.md)     |
 | **slugger**   | A simple and efficient way to generate URL-friendly slugs from strings             | [README](slugger/README.md)       | [EXAMPLES](slugger/EXAMPLES.md)       |
 | **sort**      | Sorting algorithms                                 | [README](sort/README.md)      | [EXAMPLES](sort/EXAMPLES.md)      |

regexamples/EXAMPLES.md

@@ -0,0 +1,227 @@
+## Regex Examples Function Examples
+
+### Generate examples for a digit pattern
+
+```go
+package main
+
+import (
+	"fmt"
+
+	"github.com/kashifkhan0771/utils/regexamples"
+)
+
+func main() {
+	examples, err := regexamples.Generate(`\d{4}`, 5)
+	if err != nil {
+		fmt.Println("Error:", err)
+		return
+	}
+
+	for _, s := range examples {
+		fmt.Println(s)
+	}
+}
+```
+
+#### Output:
+
+```
+7392
+0154
+8820
+3467
+5901
+```
+
+---
+
+### Generate examples for a word pattern with a range quantifier
+
+```go
+package main
+
+import (
+	"fmt"
+
+	"github.com/kashifkhan0771/utils/regexamples"
+)
+
+func main() {
+	examples, err := regexamples.Generate(`\w{3,6}`, 5)
+	if err != nil {
+		fmt.Println("Error:", err)
+		return
+	}
+
+	for _, s := range examples {
+		fmt.Println(s)
+	}
+}
+```
+
+#### Output:
+
+```
+aB3
+kQz19w
+mR7
+x2Lp
+Tz4kWn
+```
+
+---
+
+### Generate examples for an alternation pattern
+
+```go
+package main
+
+import (
+	"fmt"
+
+	"github.com/kashifkhan0771/utils/regexamples"
+)
+
+func main() {
+	examples, err := regexamples.Generate(`(foo|bar|baz)`, 5)
+	if err != nil {
+		fmt.Println("Error:", err)
+		return
+	}
+
+	for _, s := range examples {
+		fmt.Println(s)
+	}
+}
+```
+
+#### Output:
+
+```
+bar
+foo
+baz
+foo
+bar
+```
+
+---
+
+### Generate examples for an email-like pattern
+
+```go
+package main
+
+import (
+	"fmt"
+
+	"github.com/kashifkhan0771/utils/regexamples"
+)
+
+func main() {
+	examples, err := regexamples.Generate(`[a-z]{4,8}@[a-z]{3,6}\.(com|net|org)`, 5)
+	if err != nil {
+		fmt.Println("Error:", err)
+		return
+	}
+
+	for _, s := range examples {
+		fmt.Println(s)
+	}
+}
+```
+
+#### Output:
+
+```
+jktr@mxpw.com
+abcdefgh@zlo.net
+pwqr@abcde.org
+mnop@xyz.com
+lkjh@qrst.net
+```
+
+---
+
+### Reuse a Generator for multiple batches
+
+```go
+package main
+
+import (
+	"fmt"
+
+	"github.com/kashifkhan0771/utils/regexamples"
+)
+
+func main() {
+	g, err := regexamples.NewGenerator(`[A-Z]{2}\d{4}`)
+	if err != nil {
+		fmt.Println("Error:", err)
+		return
+	}
+
+	for range 3 {
+		batch, err := g.Generate(3)
+		if err != nil {
+			fmt.Println("Error:", err)
+			return
+		}
+
+		fmt.Println(batch)
+	}
+}
+```
+
+#### Output:
+
+```
+[KT8301 PX4720 BN0093]
+[ZA1154 MQ6688 RL2279]
+[CF9900 YD3341 WS7712]
+```
+
+---
+
+### Deterministic generation with SetSeed
+
+```go
+package main
+
+import (
+	"fmt"
+
+	"github.com/kashifkhan0771/utils/regexamples"
+)
+
+func main() {
+	g, err := regexamples.NewGenerator(`[a-z]{5}-\d{3}`)
+	if err != nil {
+		fmt.Println("Error:", err)
+		return
+	}
+
+	g.SetSeed(42)
+
+	examples, err := g.Generate(3)
+	if err != nil {
+		fmt.Println("Error:", err)
+		return
+	}
+
+	for _, s := range examples {
+		fmt.Println(s)
+	}
+}
+```
+
+#### Output:
+
+```
+mxkqr-581
+azpwt-047
+lbnvc-923
+```
+
+---

regexamples/README.md

@@ -0,0 +1,12 @@
+### Regex Examples (regexamples)
+
+- **Generate**: Generates n random strings that match the given regular expression pattern.
+- **NewGenerator**: Compiles a regex pattern into a reusable Generator, avoiding repeated parsing overhead when generating multiple batches.
+- **Generator.Generate**: Generates n matching strings from a pre-compiled Generator.
+- **Generator.SetSeed**: Sets a deterministic seed on the Generator so that subsequent calls produce the same sequence of strings.
+
+## Examples:
+
+For examples of each function, please checkout [EXAMPLES.md](./EXAMPLES.md)
+
+---