{"id":29354290,"url":"https://github.com/mew-sh/pqueue","last_synced_at":"2025-10-07T01:44:31.281Z","repository":{"id":303289593,"uuid":"1014985047","full_name":"mew-sh/pqueue","owner":"mew-sh","description":"A high-performance Go library that provides intelligent priority queue operations and adaptive sorting algorithms","archived":false,"fork":false,"pushed_at":"2025-07-06T19:50:53.000Z","size":17,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-17T14:01:33.278Z","etag":null,"topics":["algorithm","go","golang"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mew-sh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-06T19:39:26.000Z","updated_at":"2025-07-06T19:50:56.000Z","dependencies_parsed_at":"2025-07-06T20:42:27.600Z","dependency_job_id":"78210bd8-6249-405a-a685-3dc1e942a10d","html_url":"https://github.com/mew-sh/pqueue","commit_stats":null,"previous_names":["mew-sh/pqueue"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mew-sh/pqueue","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mew-sh%2Fpqueue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mew-sh%2Fpqueue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mew-sh%2Fpqueue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mew-sh%2Fpqueue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mew-sh","download_url":"https://codeload.github.com/mew-sh/pqueue/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mew-sh%2Fpqueue/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278708044,"owners_count":26031932,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algorithm","go","golang"],"created_at":"2025-07-09T03:12:49.572Z","updated_at":"2025-10-07T01:44:31.274Z","avatar_url":"https://github.com/mew-sh.png","language":"Go","readme":"# PQueue - Intelligent Priority Queue and Sorting Library\n\n[![Go Version](https://img.shields.io/badge/Go-1.24+-blue.svg)](https://golang.org)\n[![GoDoc](https://pkg.go.dev/badge/github.com/mew-sh/pqueue.svg)](https://pkg.go.dev/github.com/mew-sh/pqueue)\n[![Go Report Card](https://goreportcard.com/badge/github.com/mew-sh/pqueue)](https://goreportcard.com/report/github.com/mew-sh/pqueue)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n\nPQueue is a high-performance Go library that provides intelligent priority queue operations and adaptive sorting algorithms. It automatically selects the optimal sorting algorithm based on data characteristics, ensuring maximum performance across different scenarios.\n\n## Features\n\n- 🧠 **Intelligent Algorithm Selection**: Automatically chooses the best sorting algorithm based on data type, size, and patterns\n- 🚀 **High Performance**: Optimized implementations of multiple sorting algorithms\n- 🔧 **Generic Support**: Works with any comparable type using Go generics\n- 📊 **Priority Queue Operations**: Push, pop, peek operations with automatic ordering\n- 🎯 **Multiple Data Types**: Built-in support for integers, floats, strings, and custom types\n- 📈 **Comprehensive Testing**: Extensive test suite with benchmarks\n\n## Quick Start\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"github.com/mew-sh/pqueue\"\n)\n\nfunc main() {\n    // Example as requested\n    a := []int{6, 5, 4, 9, 2, 7, 1, 8}\n    p := pqueue.NewInts(a)\n    \n    // Pop minimum element\n    min, _ := p.Pop()\n    fmt.Printf(\"Popped: %d\\n\", min) // Output: 1\n    \n    // Sort remaining elements\n    p.Sort()\n    fmt.Printf(\"Sorted: %v\\n\", p.ToSlice()) // Output: [2 4 5 6 7 8 9]\n}\n```\n\n## Supported Data Types\n\nPQueue provides comprehensive support for all Go data types through intelligent type inference and optimized algorithms:\n\n### Basic Types\n- **Integers**: `int`, `int8`, `int16`, `int32`, `int64`, `uint`, `uint8`, `uint16`, `uint32`, `uint64`\n- **Floating Point**: `float32`, `float64`\n- **Strings**: `string`\n- **Byte Slices**: `[]byte`\n- **Rune Slices**: `[]rune`\n\n### Complex Types\n- **Slices**: `[]T` (slice of any type)\n- **Arrays**: `[N]T` (fixed-size arrays)\n- **Structs**: Custom struct types with comparison functions\n- **Pointers**: `*T` (with nil-safe comparisons)\n- **Maps**: `map[K]V` (with custom comparison logic)\n- **Interfaces**: Interface types\n- **Channels**: `chan T`\n- **Functions**: `func` types\n\n### Constructor Functions\n\n```go\n// Basic types\nintQueue := pqueue.NewInts([]int{3, 1, 4, 1, 5})\nfloatQueue := pqueue.NewFloats([]float64{3.14, 2.71, 1.41})\nstringQueue := pqueue.NewStrings([]string{\"zebra\", \"apple\", \"banana\"})\n\n// Complex types\nbyteQueue := pqueue.NewBytes([][]byte{[]byte(\"hello\"), []byte(\"world\")})\nruneQueue := pqueue.NewRunes([][]rune{[]rune(\"世界\"), []rune(\"hello\")})\n\n// Generic constructor for any type\ncustomQueue := pqueue.New(data, func(a, b CustomType) bool {\n    return a.Field \u003c b.Field\n})\n\n// For comparable types\ncomparableQueue := pqueue.NewComparable(data, lessFunc)\n```\n\n## Algorithm Selection Strategy\n\nThe library automatically selects the optimal algorithm based on data characteristics:\n\n| Scenario | Optimization Algorithm | Use Case |\n|----------|------------------------|----------|\n| Very Small Arrays (≤16) | Insertion Sort | Minimal overhead for tiny datasets |\n| Nearly Sorted Data | Insertion Sort | Exploits existing order |\n| Small Integer Range | Counting Sort | Linear time for bounded integers |\n| Large Integer Data | Radix Sort | Non-comparative sorting |\n| Large General Data | Introsort | Hybrid approach with guaranteed O(n log n) |\n| Real-world Data | Timsort | Adaptive to real-world patterns |\n| Distributed/Parallel | Merge Sort | Stable and parallelizable |\n\n## API Reference\n\n### Creating Priority Queues\n\n```go\n// For integers\npq := pqueue.NewInts([]int{3, 1, 4, 1, 5})\n\n// For floats\npq := pqueue.NewFloats([]float64{3.14, 2.71, 1.41})\n\n// For strings\npq := pqueue.NewStrings([]string{\"apple\", \"banana\", \"cherry\"})\n\n// For custom types with custom comparison\npq := pqueue.New(data, func(a, b MyType) bool { return a.Value \u003c b.Value })\n```\n\n### Basic Operations\n\n```go\n// Priority Queue Operations\nsize := pq.Size()           // Get number of elements\nisEmpty := pq.IsEmpty()     // Check if empty\npq.Push(item)              // Add element\nitem, err := pq.Pop()      // Remove and return minimum\nitem, err := pq.Peek()     // Get minimum without removing\n\n// Sorting Operations\npq.Sort()                                    // Auto-select best algorithm\npq.SortWithStrategy(pqueue.QuickStrategy)    // Use specific algorithm\ndata := pq.ToSlice()                        // Get sorted copy\n```\n\n### Available Sorting Strategies\n\n```go\ntype SortStrategy int\n\nconst (\n    AutoStrategy      // Automatic selection (default)\n    RadixStrategy     // Radix sort (integers only)\n    CountingStrategy  // Counting sort (small range integers)\n    InsertionStrategy // Insertion sort (small/nearly sorted data)\n    TimsortStrategy   // Timsort (adaptive merge sort)\n    IntrosortStrategy // Introsort (quick + heap + insertion)\n    MergeStrategy     // Merge sort (stable, parallelizable)\n    QuickStrategy     // Quick sort (general purpose)\n)\n```\n\n## Performance Examples\n\n### Automatic Algorithm Selection\n\n```go\n// Small data → Insertion Sort\nsmallData := []int{3, 1, 4, 1, 5}\npq := pqueue.NewInts(smallData)\npq.Sort() // Uses insertion sort automatically\n\n// Nearly sorted → Insertion Sort  \nnearlySorted := []int{1, 2, 3, 5, 4, 6, 7}\npq2 := pqueue.NewInts(nearlySorted)\npq2.Sort() // Detects pattern, uses insertion sort\n\n// Large dataset → Introsort\nlargeData := make([]int, 10000)\n// ... populate with random data\npq3 := pqueue.NewInts(largeData)\npq3.Sort() // Uses introsort for guaranteed performance\n```\n\n### Specific Algorithm Usage\n\n```go\ndata := []int{170, 45, 75, 90, 2, 802, 24, 66}\npq := pqueue.NewInts(data)\n\n// Force specific algorithms\npq.SortWithStrategy(pqueue.RadixStrategy)     // Good for integers\npq.SortWithStrategy(pqueue.MergeStrategy)     // Stable sort\npq.SortWithStrategy(pqueue.CountingStrategy)  // Small range integers\n```\n\n## Benchmarks\n\nPerformance comparison on 5000 random integers:\n\n```\nAuto Selection:    245.2µs\nQuick Sort:        312.8µs  \nMerge Sort:        387.1µs\nIntrosort:        251.4µs\nTimsort:          298.7µs\n```\n\n*Auto selection chooses the optimal algorithm, often outperforming manual selection.*\n\n## Installation\n\n```bash\ngo mod init your-project\ngo get github.com/mew-sh/pqueue\n```\n\n## Advanced Usage\n\n### Custom Types\n\n```go\ntype Person struct {\n    Name string\n    Age  int\n}\n\npeople := []Person{\n    {\"Alice\", 30},\n    {\"Bob\", 25},\n    {\"Charlie\", 35},\n}\n\n// Sort by age\npq := pqueue.New(people, func(a, b Person) bool {\n    return a.Age \u003c b.Age\n})\n\npq.Sort()\nsorted := pq.ToSlice() // Sorted by age\n```\n\n### Multiple Criteria Sorting\n\n```go\n// Sort by multiple criteria\npq := pqueue.New(people, func(a, b Person) bool {\n    if a.Age == b.Age {\n        return a.Name \u003c b.Name\n    }\n    return a.Age \u003c b.Age\n})\n```\n\n## Testing\n\nRun the comprehensive test suite:\n\n```bash\ngo test ./...                    # Run all tests\ngo test -bench=.                # Run benchmarks\ngo test -v                      # Verbose output\ngo test -race                   # Race condition detection\n```\n\n## Examples\n\nSee the [example](example/main.go) directory for comprehensive usage examples including:\n\n- Basic priority queue operations\n- Automatic algorithm selection\n- Performance comparisons\n- Different data types\n- Custom comparison functions\n\nRun the example:\n\n```bash\ngo run example/main.go\n```\n\n## Data Type Examples\n\n```go\n// 1. Numeric Types\nintegers := []int{6, 5, 4, 9, 2, 7, 1, 8}\nintQueue := pqueue.NewInts(integers)\nintQueue.Sort()\nfmt.Println(intQueue.ToSlice()) // [1 2 4 5 6 7 8 9]\n\nfloats := []float64{3.14, 2.71, 1.41, 1.73}\nfloatQueue := pqueue.NewFloats(floats)\nfloatQueue.Sort()\nfmt.Println(floatQueue.ToSlice()) // [1.41 1.73 2.71 3.14]\n\n// 2. String Types\nstrings := []string{\"zebra\", \"apple\", \"banana\"}\nstringQueue := pqueue.NewStrings(strings)\nstringQueue.Sort()\nfmt.Println(stringQueue.ToSlice()) // [apple banana zebra]\n\n// Unicode strings with runes\nwords := [][]rune{[]rune(\"世界\"), []rune(\"hello\"), []rune(\"αβγ\")}\nruneQueue := pqueue.NewRunes(words)\nruneQueue.Sort()\n\n// Byte slices\nbyteSlices := [][]byte{[]byte(\"zebra\"), []byte(\"apple\")}\nbyteQueue := pqueue.NewBytes(byteSlices)\nbyteQueue.Sort()\n\n// 3. Custom Struct Types\ntype Person struct {\n    Name string\n    Age  int\n}\n\npeople := []Person{\n    {Name: \"Alice\", Age: 30},\n    {Name: \"Bob\", Age: 25},\n    {Name: \"Charlie\", Age: 35},\n}\n\n// Sort by age, then by name\npersonQueue := pqueue.New(people, func(a, b Person) bool {\n    if a.Age != b.Age {\n        return a.Age \u003c b.Age\n    }\n    return a.Name \u003c b.Name\n})\npersonQueue.Sort()\n\n// 4. Pointer Types\nvalues := []int{5, 2, 8, 1, 9}\nptrs := make([]*int, len(values))\nfor i := range values {\n    ptrs[i] = \u0026values[i]\n}\n\nptrQueue := pqueue.New(ptrs, func(a, b *int) bool {\n    if a == nil || b == nil {\n        return a == nil \u0026\u0026 b != nil // nil values first\n    }\n    return *a \u003c *b\n})\nptrQueue.Sort()\n\n// 5. Slice Types (2D arrays)\nslicesOfInts := [][]int{\n    {3, 2, 1},\n    {1, 2, 3},\n    {2, 1, 3},\n}\n\nsliceQueue := pqueue.New(slicesOfInts, func(a, b []int) bool {\n    // Custom comparison: by sum, then lexicographically\n    sumA, sumB := sum(a), sum(b)\n    if sumA != sumB {\n        return sumA \u003c sumB\n    }\n    for i := 0; i \u003c len(a) \u0026\u0026 i \u003c len(b); i++ {\n        if a[i] != b[i] {\n            return a[i] \u003c b[i]\n        }\n    }\n    return len(a) \u003c len(b)\n})\nsliceQueue.Sort()\n\n// 6. Interface Types\ntype Comparable interface {\n    CompareTo(other interface{}) int\n}\n\n// For types implementing Comparable interface\ncomparableQueue := pqueue.NewWithComparable([]ComparableType{...})\n```\n\n## Algorithm Details\n\n### Insertion Sort\n- **Best Case**: O(n) for nearly sorted data\n- **Average/Worst**: O(n²)\n- **Use**: Small arrays (≤16 elements), nearly sorted data\n\n### Quick Sort\n- **Average**: O(n log n)\n- **Worst**: O(n²)\n- **Use**: General purpose, good cache performance\n\n### Merge Sort\n- **All Cases**: O(n log n)\n- **Use**: Stable sorting, parallel processing\n- **Space**: O(n)\n\n### Introsort\n- **All Cases**: O(n log n) guaranteed\n- **Use**: Large datasets, unknown data patterns\n- **Features**: Hybrid of quicksort, heapsort, and insertion sort\n\n### Timsort\n- **Best**: O(n) for real-world data\n- **Average/Worst**: O(n log n)\n- **Use**: Real-world data with existing patterns\n\n### Radix Sort\n- **Complexity**: O(d × n) where d is number of digits\n- **Use**: Integers, strings with fixed-length keys\n- **Space**: O(n + k)\n\n### Counting Sort\n- **Complexity**: O(n + k) where k is range\n- **Use**: Small range integers\n- **Space**: O(k)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Inspired by the intelligent sorting strategies used in production systems\n- Algorithm implementations based on proven computer science research\n- Performance optimizations derived from real-world usage patterns\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmew-sh%2Fpqueue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmew-sh%2Fpqueue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmew-sh%2Fpqueue/lists"}