179 lines
3.7 KiB
Markdown
179 lines
3.7 KiB
Markdown
# extypes
|
|
|
|
`extypes` is a small Go package with generic collection helpers built on top of native slices and maps.
|
|
|
|
It provides:
|
|
|
|
- `Slice[T]`: slice helpers such as `Push`, `Pop`, `Remove`, `Filter`, `Map`
|
|
- `Tuple[T]`: a read-oriented ordered collection with JSON support
|
|
- `Set[T]`: a uniqueness-enforcing collection backed by a slice
|
|
- `HashMap[K, V]`: a generic map wrapper with helper methods
|
|
- `Queue[T]`: a fixed-size, mutex-protected FIFO queue
|
|
|
|
## Requirements
|
|
|
|
- Go `1.25+`
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
go get git.nix13.pw/scuroneko/extypes
|
|
```
|
|
|
|
## Import
|
|
|
|
```go
|
|
import "git.nix13.pw/scuroneko/extypes"
|
|
```
|
|
|
|
## Design Notes
|
|
|
|
- The package stays close to Go built-ins instead of introducing a large abstraction layer.
|
|
- `Slice`, `Set`, and `HashMap` methods often return the receiver for chaining.
|
|
- Some methods mutate the underlying storage in place: `Slice.Map`, `Slice.Swap`, `Set.Map`, `Set.Swap`, `HashMap.Add`, `HashMap.Remove`, `HashMap.Map`.
|
|
- `Tuple` is read-oriented, but `NewTupleFrom` wraps the provided slice without copying it.
|
|
- `Set` preserves first-seen order. Its `Equal` method is order-sensitive.
|
|
- `Set.Map` does not restore uniqueness if the mapping function produces duplicates.
|
|
- `HashMap` iteration order is unspecified, so `Keys`, `Values`, `Items`, `IndexKey`, and `IndexValue` should not be used where stable ordering is required.
|
|
- Equality and search for `Slice`, `Tuple`, `Set`, and `HashMap.IndexValue` use `reflect.DeepEqual`, so element types do not need to be `comparable`.
|
|
|
|
## Quick Examples
|
|
|
|
### Slice
|
|
|
|
```go
|
|
nums := extypes.NewSliceFrom([]int{1, 2, 3})
|
|
|
|
nums = nums.Push(4)
|
|
nums = nums.Remove(2)
|
|
nums = nums.Map(func(v int) int { return v * 10 })
|
|
|
|
fmt.Println(nums.ToArray()) // [10 30 40]
|
|
```
|
|
|
|
### Tuple
|
|
|
|
```go
|
|
tuple := extypes.NewTupleFrom([]string{"api", "worker", "cron"})
|
|
|
|
filtered := tuple.Filter(func(v string) bool {
|
|
return v != "worker"
|
|
})
|
|
|
|
fmt.Println(filtered.Join(", ")) // api, cron
|
|
```
|
|
|
|
### Set
|
|
|
|
```go
|
|
set := extypes.NewSetFrom([]string{"go", "go", "docs", "tests"})
|
|
|
|
set = set.Add("bench")
|
|
set = set.Remove("docs")
|
|
|
|
fmt.Println(set.ToArray()) // [go tests bench]
|
|
```
|
|
|
|
### HashMap
|
|
|
|
```go
|
|
ports := extypes.NewMapFrom(map[string]int{
|
|
"http": 80,
|
|
"https": 443,
|
|
})
|
|
|
|
ports.Add("ssh", 22)
|
|
|
|
secure := ports.Filter(func(name string, port int) bool {
|
|
return port >= 100 || name == "https"
|
|
})
|
|
|
|
fmt.Println(secure.Contains("https")) // true
|
|
```
|
|
|
|
### Queue
|
|
|
|
```go
|
|
q := extypes.CreateQueue[string](2)
|
|
|
|
_ = q.Enqueue("first")
|
|
_ = q.Enqueue("second")
|
|
|
|
head, _ := q.Peak()
|
|
fmt.Println(head) // first
|
|
|
|
item, _ := q.Dequeue()
|
|
fmt.Println(item) // first
|
|
```
|
|
|
|
## API Overview
|
|
|
|
### `Slice[T]`
|
|
|
|
Useful methods:
|
|
|
|
- `Len`, `Cap`, `Get`, `First`, `Last`
|
|
- `Index`, `Equal`
|
|
- `Push`, `Pop`, `Remove`, `Swap`
|
|
- `Filter`, `ForEach`, `Map`, `Join`
|
|
- `ToArray`, `ToAnyArray`, `ToSet`, `ToTuple`
|
|
|
|
### `Tuple[T]`
|
|
|
|
Useful methods:
|
|
|
|
- `Len`, `Cap`, `Get`
|
|
- `Equal`
|
|
- `Filter`, `ForEach`, `Join`
|
|
- `ToArray`, `ToAnyArray`, `ToSet`, `ToSlice`
|
|
- `MarshalJSON`, `UnmarshalJSON`
|
|
|
|
### `Set[T]`
|
|
|
|
Useful methods:
|
|
|
|
- `Len`, `Cap`, `Get`, `First`, `Last`
|
|
- `Index`, `Equal`
|
|
- `Add`, `Pop`, `Remove`, `Swap`
|
|
- `Filter`, `ForEach`, `Map`, `Join`
|
|
- `ToArray`, `ToAnyArray`, `ToSlice`, `ToTuple`
|
|
|
|
### `HashMap[K, V]`
|
|
|
|
Useful methods:
|
|
|
|
- `Len`, `Get`, `GetOrDefault`, `Contains`
|
|
- `Add`, `Remove`
|
|
- `Keys`, `Values`, `Items`
|
|
- `IndexKey`, `IndexValue`
|
|
- `Filter`, `ForEach`, `Map`
|
|
|
|
### `Queue[T]`
|
|
|
|
Useful methods:
|
|
|
|
- `CreateQueue`
|
|
- `Len`, `Size`, `IsEmpty`, `IsFull`
|
|
- `Enqueue`, `Dequeue`, `Peak`
|
|
- `Raw`
|
|
|
|
Returned errors:
|
|
|
|
- `QueueFullErr`
|
|
- `QueueEmptyErr`
|
|
|
|
## Running Tests
|
|
|
|
```bash
|
|
go test ./...
|
|
```
|
|
|
|
## Godoc
|
|
|
|
The package includes doc comments for the public API, so local documentation can be viewed with standard Go tooling:
|
|
|
|
```bash
|
|
go doc
|
|
go doc git.nix13.pw/scuroneko/extypes
|
|
```
|