go version bump

docs: add godoc and README files in English and Russian
fix: align slice/set equality and harden queue API
2026-03-17 15:41:42 +03:00 · 2026-03-17 15:26:41 +03:00 · 2026-03-17 14:37:35 +03:00 · 2026-02-19 15:05:01 +03:00 · 2026-02-12 13:46:53 +03:00 · 2026-02-09 17:39:41 +03:00
14 changed files with 1232 additions and 192 deletions
@@ -0,0 +1,178 @@
+# 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
+```
@@ -0,0 +1,178 @@
+# extypes
+
+`extypes` - это небольшой Go-пакет с generic-коллекциями и вспомогательными методами поверх обычных `slice` и `map`.
+
+В пакет входят:
+
+- `Slice[T]`: методы для срезов, например `Push`, `Pop`, `Remove`, `Filter`, `Map`
+- `Tuple[T]`: упорядоченная read-oriented коллекция с поддержкой JSON
+- `Set[T]`: коллекция с уникальными значениями на базе среза
+- `HashMap[K, V]`: generic-обертка над `map`
+- `Queue[T]`: ограниченная по размеру FIFO-очередь с mutex-защитой
+
+## Требования
+
+- Go `1.25+`
+
+## Установка
+
+```bash
+go get git.nix13.pw/scuroneko/extypes
+```
+
+## Импорт
+
+```go
+import "git.nix13.pw/scuroneko/extypes"
+```
+
+## Особенности дизайна
+
+- Пакет остается близким к встроенным типам Go и не строит тяжелую абстракцию поверх них.
+- Методы `Slice`, `Set` и `HashMap` часто возвращают receiver, чтобы было удобно писать chain-вызовы.
+- Часть методов мутирует данные на месте: `Slice.Map`, `Slice.Swap`, `Set.Map`, `Set.Swap`, `HashMap.Add`, `HashMap.Remove`, `HashMap.Map`.
+- `Tuple` ориентирован на чтение, но `NewTupleFrom` не копирует входной срез, а оборачивает его.
+- `Set` сохраняет порядок первого появления элементов. Метод `Equal` чувствителен к порядку.
+- `Set.Map` не восстанавливает уникальность, если функция отображения порождает дубликаты.
+- Порядок обхода `HashMap` не определен, поэтому `Keys`, `Values`, `Items`, `IndexKey` и `IndexValue` не подходят там, где нужен стабильный порядок.
+- Для поиска и сравнения в `Slice`, `Tuple`, `Set` и `HashMap.IndexValue` используется `reflect.DeepEqual`, поэтому элементы не обязаны быть `comparable`.
+
+## Быстрые примеры
+
+### 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
+
+### `Slice[T]`
+
+Полезные методы:
+
+- `Len`, `Cap`, `Get`, `First`, `Last`
+- `Index`, `Equal`
+- `Push`, `Pop`, `Remove`, `Swap`
+- `Filter`, `ForEach`, `Map`, `Join`
+- `ToArray`, `ToAnyArray`, `ToSet`, `ToTuple`
+
+### `Tuple[T]`
+
+Полезные методы:
+
+- `Len`, `Cap`, `Get`
+- `Equal`
+- `Filter`, `ForEach`, `Join`
+- `ToArray`, `ToAnyArray`, `ToSet`, `ToSlice`
+- `MarshalJSON`, `UnmarshalJSON`
+
+### `Set[T]`
+
+Полезные методы:
+
+- `Len`, `Cap`, `Get`, `First`, `Last`
+- `Index`, `Equal`
+- `Add`, `Pop`, `Remove`, `Swap`
+- `Filter`, `ForEach`, `Map`, `Join`
+- `ToArray`, `ToAnyArray`, `ToSlice`, `ToTuple`
+
+### `HashMap[K, V]`
+
+Полезные методы:
+
+- `Len`, `Get`, `GetOrDefault`, `Contains`
+- `Add`, `Remove`
+- `Keys`, `Values`, `Items`
+- `IndexKey`, `IndexValue`
+- `Filter`, `ForEach`, `Map`
+
+### `Queue[T]`
+
+Полезные методы:
+
+- `CreateQueue`
+- `Len`, `Size`, `IsEmpty`, `IsFull`
+- `Enqueue`, `Dequeue`, `Peak`
+- `Raw`
+
+Возвращаемые ошибки:
+
+- `QueueFullErr`
+- `QueueEmptyErr`
+
+## Запуск тестов
+
+```bash
+go test ./...
+```
+
+## Godoc
+
+Для публичного API добавлены doc-комментарии, поэтому локальную документацию можно смотреть стандартными инструментами Go:
+
+```bash
+go doc
+go doc git.nix13.pw/scuroneko/extypes
+```
@@ -0,0 +1,6 @@
+// Package extypes provides small generic collection types for Go:
+// Slice, Tuple, Set, HashMap, and a fixed-size concurrent Queue.
+//
+// The package is intentionally lightweight and stays close to the
+// semantics of the underlying Go built-in types.
+package extypes
@@ -1,3 +1,3 @@
 module git.nix13.pw/scuroneko/extypes

-go 1.25
+go 1.26
@@ -1,7 +1,11 @@
 package extypes

+import "reflect"
+
+// HashMap is a generic wrapper around Go's built-in map type.
 type HashMap[K comparable, V any] map[K]V

+// NewMapFrom returns a shallow copy of m as a HashMap.
 func NewMapFrom[K comparable, V any](m map[K]V) HashMap[K, V] {
 	out := make(HashMap[K, V])
 	for k, v := range m {
@@ -9,20 +13,26 @@ func NewMapFrom[K comparable, V any](m map[K]V) HashMap[K, V] {
 	}
 	return out
 }
-func (m HashMap[K, V]) Len() int {
-	return len(m)
-}
+
+// Len returns the number of entries in m.
+func (m HashMap[K, V]) Len() int { return len(m) }
+
+// Add stores val under key and returns m.
 func (m HashMap[K, V]) Add(key K, val V) HashMap[K, V] {
 	m[key] = val
 	return m
 }
+
+// Remove deletes key and returns m.
 func (m HashMap[K, V]) Remove(key K) HashMap[K, V] {
 	delete(m, key)
 	return m
 }
-func (m HashMap[K, V]) Get(key K) V {
-	return m[key]
-}
+
+// Get returns the value stored under key.
+func (m HashMap[K, V]) Get(key K) V { return m[key] }
+
+// GetOrDefault returns the value stored under key or def if the key is absent.
 func (m HashMap[K, V]) GetOrDefault(key K, def V) V {
 	v, ok := m[key]
 	if !ok {
@@ -30,10 +40,70 @@ func (m HashMap[K, V]) GetOrDefault(key K, def V) V {
 	}
 	return v
 }
+
+// Contains reports whether key is present in m.
 func (m HashMap[K, V]) Contains(key K) bool {
 	_, ok := m[key]
 	return ok
 }
+
+// IndexKey returns the iteration index of key or -1 when absent.
+// The result depends on Go map iteration order and is therefore not stable.
+func (m HashMap[K, V]) IndexKey(key K) int {
+	index := 0
+	for k, _ := range m {
+		if k == key {
+			return index
+		}
+		index++
+	}
+	return -1
+}
+
+// IndexValue returns the iteration index of value or -1 when absent.
+// The result depends on Go map iteration order and comparison uses
+// reflect.DeepEqual.
+func (m HashMap[K, V]) IndexValue(value V) int {
+	index := 0
+	for _, v := range m {
+		if reflect.DeepEqual(value, v) {
+			return index
+		}
+		index++
+	}
+	return -1
+}
+
+// Keys returns the current keys in unspecified order.
+func (m HashMap[K, V]) Keys() []K {
+	keys := make([]K, 0, m.Len())
+	for k := range m {
+		keys = append(keys, k)
+	}
+	return keys
+}
+
+// Values returns the current values in unspecified order.
+func (m HashMap[K, V]) Values() []V {
+	values := make([]V, 0, m.Len())
+	for _, v := range m {
+		values = append(values, v)
+	}
+	return values
+}
+
+// Items returns keys and values collected in the same iteration order.
+func (m HashMap[K, V]) Items() ([]K, []V) {
+	keys := make(Slice[K], 0, m.Len())
+	values := make(Slice[V], 0, m.Len())
+	for k, v := range m {
+		keys = keys.Push(k)
+		values = values.Push(v)
+	}
+	return keys, values
+}
+
+// Filter returns a new HashMap containing only entries accepted by f.
 func (m HashMap[K, V]) Filter(f func(K, V) bool) HashMap[K, V] {
 	out := make(HashMap[K, V])
 	for k, v := range m {
@@ -44,3 +114,19 @@ func (m HashMap[K, V]) Filter(f func(K, V) bool) HashMap[K, V] {
 	}
 	return out
 }
+
+// ForEach calls f for every entry and returns m.
+func (m HashMap[K, V]) ForEach(f func(K, V)) HashMap[K, V] {
+	for k, v := range m {
+		f(k, v)
+	}
+	return m
+}
+
+// Map replaces every value with the result of f and returns m.
+func (m HashMap[K, V]) Map(f func(K, V) V) HashMap[K, V] {
+	for k, v := range m {
+		m[k] = f(k, v)
+	}
+	return m
+}
@@ -0,0 +1,23 @@
+package extypes
+
+import (
+	"fmt"
+	"testing"
+)
+
+func BenchmarkHashMap_Add(b *testing.B) {
+	b.StartTimer()
+	m := make(HashMap[string, string])
+	for i := 0; i < b.N; i++ {
+		m.Add(fmt.Sprint(i), fmt.Sprint(i))
+	}
+	b.StopTimer()
+}
+func BenchmarkGoMap_Add(b *testing.B) {
+	b.StartTimer()
+	m := make(map[string]string)
+	for i := 0; i < b.N; i++ {
+		m[fmt.Sprint(i)] = fmt.Sprint(i)
+	}
+	b.StopTimer()
+}
@@ -1,71 +1,92 @@
-package extypes 
+package extypes

 import (
 	"errors"
 	"sync"
 )

+// QueueFullErr is returned when Enqueue is called on a full queue.
 var QueueFullErr = errors.New("queue full")

+// QueueEmptyErr is returned when Peak or Dequeue is called on an empty queue.
+var QueueEmptyErr = errors.New("queue empty")
+
+// Queue is a fixed-size FIFO queue protected by a mutex.
 type Queue[T any] struct {
 	size  uint64
 	mu    sync.RWMutex
-	queue []T
+	queue Slice[T]
 }

+// CreateQueue creates a queue with the provided maximum size.
 func CreateQueue[T any](size uint64) *Queue[T] {
-	return &Queue[T]{
-		queue: make([]T, 0),
-		size:  size,
-	}
+	return &Queue[T]{queue: make(Slice[T], 0, size), size: size}
 }

+// Len returns the current number of queued elements.
+func (q *Queue[T]) Len() uint64 {
+	q.mu.RLock()
+	defer q.mu.RUnlock()
+	return uint64(q.queue.Len())
+}
+
+// IsEmpty reports whether the queue currently holds no elements.
+func (q *Queue[T]) IsEmpty() bool { return q.Len() == 0 }
+
+// IsFull reports whether the queue has reached its configured size.
+func (q *Queue[T]) IsFull() bool { return q.Len() == q.size }
+
+// Size returns the configured queue capacity.
+func (q *Queue[T]) Size() uint64 { return q.size }
+
+// Enqueue appends el to the queue or returns QueueFullErr.
 func (q *Queue[T]) Enqueue(el T) error {
-	if q.IsFull() {
+	q.mu.Lock()
+	defer q.mu.Unlock()
+
+	if uint64(len(q.queue)) == q.size {
 		return QueueFullErr
 	}
-	q.queue = append(q.queue, el)
+	q.queue = q.queue.Push(el)
 	return nil
 }

-func (q *Queue[T]) Peak() T {
-	q.mu.RLock()
-	defer q.mu.RUnlock()
-	return q.queue[0]
-}
+// Dequeue removes and returns the head element or QueueEmptyErr.
+func (q *Queue[T]) Dequeue() (T, error) {
+	q.mu.Lock()
+	defer q.mu.Unlock()

-func (q *Queue[T]) IsEmpty() bool {
-	return q.Length() == 0
-}
-
-func (q *Queue[T]) IsFull() bool {
-	return q.Length() == q.size
-}
-
-func (q *Queue[T]) Length() uint64 {
-	q.mu.RLock()
-	defer q.mu.RUnlock()
-	return uint64(len(q.queue))
-}
-
-func (q *Queue[T]) Dequeue() T {
-	q.mu.RLock()
-	el := q.queue[0]
-	q.mu.RUnlock()
-
-	if q.Length() == 1 {
-		q.mu.Lock()
-		q.queue = make([]T, 0)
-		q.mu.Unlock()
-		return el
+	var zero T
+	if len(q.queue) == 0 {
+		return zero, QueueEmptyErr
 	}

-	q.mu.Lock()
-	q.queue = q.queue[1:]
-	q.mu.Unlock()
-	return el
+	el := q.queue[0]
+	copy(q.queue, q.queue[1:])
+	q.queue[len(q.queue)-1] = zero
+	q.queue = q.queue[:len(q.queue)-1]
+
+	return el, nil
 }

-func (q *Queue[T]) Raw() []T {
-	return q.queue
+// Peak returns the head element without removing it or QueueEmptyErr when the
+// queue is empty.
+func (q *Queue[T]) Peak() (T, error) {
+	q.mu.RLock()
+	defer q.mu.RUnlock()
+
+	var zero T
+	if len(q.queue) == 0 {
+		return zero, QueueEmptyErr
+	}
+
+	return q.queue[0], nil
+}
+
+// Raw returns a copy of the queue contents from head to tail.
+func (q *Queue[T]) Raw() Slice[T] {
+	q.mu.RLock()
+	defer q.mu.RUnlock()
+
+	return NewSliceFrom(q.queue)
 }
@@ -0,0 +1,129 @@
+package extypes
+
+import (
+	"log"
+	"testing"
+)
+
+func ExampleCreateQueue() {
+	q := CreateQueue[int](16)
+	err := q.Enqueue(1)
+	if err != nil {
+		panic(err)
+	}
+	i, err := q.Dequeue() // <- Here we got 1
+	if err != nil {
+		panic(err)
+	}
+	log.Println(i)
+}
+func BenchmarkQueue_Enqueue(b *testing.B) {
+	b.StartTimer()
+	q := CreateQueue[int](uint64(b.N))
+	for i := 0; i < b.N; i++ {
+		if err := q.Enqueue(i); err != nil {
+			b.Fatal(err)
+		}
+	}
+	b.StopTimer()
+	b.ReportAllocs()
+}
+func BenchmarkQueue_Dequeue(b *testing.B) {
+	q := CreateQueue[int](uint64(b.N))
+	for i := 0; i < b.N; i++ {
+		if err := q.Enqueue(i); err != nil {
+			b.Fatal(err)
+		}
+	}
+	b.StartTimer()
+	for i := 0; i < b.N; i++ {
+		if _, err := q.Dequeue(); err != nil {
+			b.Fatal(err)
+		}
+	}
+	b.StopTimer()
+	b.ReportAllocs()
+}
+func BenchmarkQueue_EnqueueDequeue(b *testing.B) {
+	b.StartTimer()
+	q := CreateQueue[int](uint64(b.N))
+	for i := 0; i < b.N; i++ {
+		if err := q.Enqueue(i); err != nil {
+			b.Fatal(err)
+		}
+	}
+	for i := 0; i < b.N; i++ {
+		if _, err := q.Dequeue(); err != nil {
+			b.Fatal(err)
+		}
+	}
+	b.StopTimer()
+	b.ReportAllocs()
+}
+
+func TestQueue_Empty(t *testing.T) {
+	q := CreateQueue[int](1)
+
+	if _, err := q.Peak(); err != QueueEmptyErr {
+		t.Fatalf("Peak() error = %v, want %v", err, QueueEmptyErr)
+	}
+	if _, err := q.Dequeue(); err != QueueEmptyErr {
+		t.Fatalf("Dequeue() error = %v, want %v", err, QueueEmptyErr)
+	}
+}
+
+func TestQueue_BasicOperations(t *testing.T) {
+	q := CreateQueue[int](2)
+
+	if err := q.Enqueue(1); err != nil {
+		t.Fatal(err)
+	}
+	if err := q.Enqueue(2); err != nil {
+		t.Fatal(err)
+	}
+	if err := q.Enqueue(3); err != QueueFullErr {
+		t.Fatalf("Enqueue() error = %v, want %v", err, QueueFullErr)
+	}
+
+	head, err := q.Peak()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if head != 1 {
+		t.Fatalf("Peak() = %d, want 1", head)
+	}
+
+	first, err := q.Dequeue()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if first != 1 {
+		t.Fatalf("Dequeue() = %d, want 1", first)
+	}
+
+	second, err := q.Dequeue()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if second != 2 {
+		t.Fatalf("Dequeue() = %d, want 2", second)
+	}
+}
+
+func TestQueue_RawReturnsCopy(t *testing.T) {
+	q := CreateQueue[int](2)
+	if err := q.Enqueue(1); err != nil {
+		t.Fatal(err)
+	}
+
+	raw := q.Raw()
+	raw[0] = 99
+
+	head, err := q.Peak()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if head != 1 {
+		t.Fatalf("Peak() = %d, want 1", head)
+	}
+}
@@ -0,0 +1,160 @@
+package extypes
+
+import (
+	"fmt"
+	"reflect"
+	"strings"
+)
+
+// Set is a uniqueness-enforcing collection backed by a slice.
+//
+// Order is preserved based on first appearance. Equality is order-sensitive
+// because the underlying representation is a slice.
+type Set[T any] []T
+
+// NewSetFrom returns a new Set with duplicate values removed.
+func NewSetFrom[T any](slice []T) Set[T] {
+	s := make(Set[T], 0)
+	for _, v := range slice {
+		if s.Index(v) >= 0 {
+			continue
+		}
+		s = append(s, v)
+	}
+	return s
+}
+
+// Len returns the number of elements in s.
+func (s Set[T]) Len() int { return len(s) }
+
+// Cap returns the capacity of s.
+func (s Set[T]) Cap() int { return cap(s) }
+
+// Get returns the element at index.
+func (s Set[T]) Get(index int) T { return s[index] }
+
+// Last returns the last element.
+func (s Set[T]) Last() T { return s.Get(s.Len() - 1) }
+
+// First returns the first element.
+func (s Set[T]) First() T { return s.Get(0) }
+
+// Index returns the first index of el or -1 when el is not present.
+// Comparison uses reflect.DeepEqual.
+func (s Set[T]) Index(el T) int {
+	for i := range s {
+		if reflect.DeepEqual(s[i], el) {
+			return i
+		}
+	}
+	return -1
+}
+
+// Swap swaps two elements in place.
+func (s Set[T]) Swap(i, j int) {
+	s[i], s[j] = s[j], s[i]
+}
+
+// Add appends v if it is not already present.
+func (s Set[T]) Add(v T) Set[T] {
+	index := s.Index(v)
+	if index >= 0 {
+		return s
+	}
+	return append(s, v)
+}
+
+// Pop removes the element at index and returns the resulting set.
+func (s Set[T]) Pop(index int) Set[T] {
+	if index == 0 {
+		return s[1:]
+	}
+	out := make(Set[T], s.Len()-1)
+	copy(out, s[:index])
+	copy(out[index:], s[index+1:])
+	return out
+}
+
+// Remove removes the first matching element and returns the resulting set.
+func (s Set[T]) Remove(el T) Set[T] {
+	index := s.Index(el)
+	if index == -1 {
+		return s
+	}
+	return s.Pop(index)
+}
+
+// Equal reports whether both sets have the same length and pairwise equal
+// elements in the same order according to reflect.DeepEqual.
+func (s Set[T]) Equal(s2 Set[T]) bool {
+	if s.Len() != s2.Len() {
+		return false
+	}
+	for i := range s {
+		if !reflect.DeepEqual(s[i], s2[i]) {
+			return false
+		}
+	}
+	return true
+}
+
+// ToSlice returns a copy of s as a Slice.
+func (s Set[T]) ToSlice() Slice[T] { return NewSliceFrom(s) }
+
+// ToTuple returns a Tuple view of s without copying.
+func (s Set[T]) ToTuple() Tuple[T] { return NewTupleFrom(s) }
+
+// ToArray returns a copy of s as a built-in slice.
+func (s Set[T]) ToArray() []T {
+	out := make([]T, len(s))
+	copy(out, s)
+	return out
+}
+
+// ToAnyArray returns a copy of s converted to []any.
+func (s Set[T]) ToAnyArray() []any {
+	out := make([]any, len(s))
+	for i, v := range s {
+		out[i] = v
+	}
+	return out
+}
+
+// Filter returns a new Set containing only elements accepted by f.
+// The result preserves order and therefore remains duplicate-free.
+func (s Set[T]) Filter(f func(e T) bool) Set[T] {
+	out := make(Set[T], 0)
+	for _, v := range s {
+		if f(v) {
+			out = append(out, v)
+		}
+	}
+	return out
+}
+
+// ForEach calls f for every element and returns s.
+func (s Set[T]) ForEach(f func(int, T)) Set[T] {
+	for i, v := range s {
+		f(i, v)
+	}
+	return s
+}
+
+// Map applies f to each element in place and returns s.
+// It does not remove duplicates that may be produced by f.
+func (s Set[T]) Map(f func(e T) T) Set[T] {
+	for i, v := range s {
+		s[i] = f(v)
+	}
+	return s
+}
+
+// Join formats every element with fmt.Sprintf("%v", value) and joins them
+// using sep.
+func (s Set[T]) Join(sep string) string {
+	st := make([]string, len(s))
+	for i, v := range s {
+		st[i] = fmt.Sprintf("%v", v)
+	}
+	return strings.Join(st, sep)
+}
@@ -0,0 +1,31 @@
+package extypes
+
+import "testing"
+
+func TestSet(t *testing.T) {
+	s1 := make(Set[int], 0)
+	s2 := make(Set[int], 0)
+
+	s1 = s1.Add(1)
+	s1 = s1.Add(2)
+	s1 = s1.Add(2)
+
+	s2 = s2.Add(1)
+	s2 = s2.Add(2)
+
+	if !s1.Equal(s2) {
+		t.Error("s1 and s2 not equal")
+	}
+}
+
+func TestSet_EqualIgnoresCapacity(t *testing.T) {
+	s1 := make(Set[int], 2, 2)
+	s2 := make(Set[int], 2, 4)
+
+	s1[0], s1[1] = 1, 2
+	s2[0], s2[1] = 1, 2
+
+	if !s1.Equal(s2) {
+		t.Error("s1 and s2 not equal")
+	}
+}
@@ -1,35 +1,113 @@
 package extypes

-import "slices"
+import (
+	"fmt"
+	"reflect"
+	"strings"
+)

-type Slice[T comparable] []T
+// Slice is a generic slice wrapper with convenience methods.
+type Slice[T any] []T

-func NewSliceFrom[T comparable](slice []T) Slice[T] {
+// NewSliceFrom returns a copy of slice as a Slice.
+func NewSliceFrom[T any](slice []T) Slice[T] {
 	s := make(Slice[T], len(slice))
 	copy(s, slice)
 	return s
 }
-func (s Slice[T]) Len() int {
-	return len(s)
-}
-func (s Slice[T]) Cap() int {
-	return cap(s)
-}
-func (s Slice[T]) Get(index int) T {
-	return s[index]
-}
-func (s Slice[T]) Last() T {
-	return s.Get(s.Len() - 1)
-}
+
+// Len returns the number of elements in s.
+func (s Slice[T]) Len() int { return len(s) }
+
+// Cap returns the capacity of s.
+func (s Slice[T]) Cap() int { return cap(s) }
+
+// Get returns the element at index.
+func (s Slice[T]) Get(index int) T { return s[index] }
+
+// Last returns the last element.
+func (s Slice[T]) Last() T { return s.Get(s.Len() - 1) }
+
+// First returns the first element.
+func (s Slice[T]) First() T { return s.Get(0) }
+
+// Index returns the first index of el or -1 when el is not present.
+// Comparison uses reflect.DeepEqual.
 func (s Slice[T]) Index(el T) int {
-	return slices.Index(s, el)
+	for i := range s {
+		if reflect.DeepEqual(s[i], el) {
+			return i
+		}
+	}
+	return -1
 }

-// Swap is mutable func
+// Push appends e and returns the resulting slice.
+func (s Slice[T]) Push(e T) Slice[T] { return append(s, e) }
+
+// Pop removes the element at index and returns the resulting slice.
+func (s Slice[T]) Pop(index int) Slice[T] {
+	if index == 0 {
+		return s[1:]
+	}
+	out := make(Slice[T], s.Len()-1)
+	copy(out, s[:index])
+	copy(out[index:], s[index+1:])
+	return out
+}
+
+// Remove removes the first matching element and returns the resulting slice.
+func (s Slice[T]) Remove(el T) Slice[T] {
+	index := s.Index(el)
+	if index == -1 {
+		return s
+	}
+	return s.Pop(index)
+}
+
+// Swap swaps two elements in place and returns s.
 func (s Slice[T]) Swap(i, j int) Slice[T] {
 	s[i], s[j] = s[j], s[i]
 	return s
 }
+
+// Equal reports whether both slices have the same length and pairwise equal
+// elements according to reflect.DeepEqual.
+func (s Slice[T]) Equal(s2 Slice[T]) bool {
+	if s.Len() != s2.Len() {
+		return false
+	}
+	for i := range s {
+		if !reflect.DeepEqual(s[i], s2[i]) {
+			return false
+		}
+	}
+	return true
+}
+
+// ToArray returns a copy of s as a built-in slice.
+func (s Slice[T]) ToArray() []T {
+	out := make([]T, len(s))
+	copy(out, s)
+	return out
+}
+
+// ToAnyArray returns a copy of s converted to []any.
+func (s Slice[T]) ToAnyArray() []any {
+	out := make([]any, len(s))
+	for i, v := range s {
+		out[i] = v
+	}
+	return out
+}
+
+// ToSet returns a Set built from the slice values.
+func (s Slice[T]) ToSet() Set[T] { return NewSetFrom(s) }
+
+// ToTuple returns a Tuple view of s without copying.
+func (s Slice[T]) ToTuple() Tuple[T] { return NewTupleFrom(s) }
+
+// Filter returns a new Slice containing only elements accepted by f.
 func (s Slice[T]) Filter(f func(e T) bool) Slice[T] {
 	out := make(Slice[T], 0)
 	for _, v := range s {
@@ -39,138 +117,29 @@ func (s Slice[T]) Filter(f func(e T) bool) Slice[T] {
 	}
 	return out
 }
+
+// ForEach calls f for every element and returns s.
+func (s Slice[T]) ForEach(f func(int, T)) Slice[T] {
+	for i, v := range s {
+		f(i, v)
+	}
+	return s
+}
+
+// Map applies f to each element in place and returns s.
 func (s Slice[T]) Map(f func(e T) T) Slice[T] {
-	out := make(Slice[T], s.Len())
-	for i, v := range s {
-		out[i] = f(v)
-	}
-	return out
-}
-func (s Slice[T]) Pop(index int) Slice[T] {
-	if index == 0 {
-		return s[1:]
-	}
-	out := make(Slice[T], 0, s.Len()-1)
-	for i, e := range s {
-		if i == index {
-			continue
-		}
-		out = append(out, e)
-	}
-	return out
-}
-func (s Slice[T]) Remove(el T) Slice[T] {
-	index := s.Index(el)
-	if index == -1 {
-		return s
-	}
-	return s.Pop(index)
-}
-func (s Slice[T]) Push(e T) Slice[T] {
-	return append(s, e)
-}
-
-func (s Slice[T]) ToArray() []T {
-	out := make([]T, len(s))
-	copy(out, s)
-	return out
-}
-func (s Slice[T]) ToAnyArray() []any {
-	out := make([]any, len(s))
-	for i, v := range s {
-		out[i] = v
-	}
-	return out
-}
-
-// ForEach is mutable func
-func (s Slice[T]) ForEach(f func(e T) T) Slice[T] {
 	for i, v := range s {
 		s[i] = f(v)
 	}
 	return s
 }

-type Set[T comparable] []T
-
-func NewSetFrom[T comparable](slice []T) Set[T] {
-	s := make(Set[T], 0)
-	for _, v := range slice {
-		if s.Index(v) >= 0 {
-			continue
-		}
-		s = append(s, v)
-	}
-	return s
-}
-func (s Set[T]) Len() int {
-	return len(s)
-}
-func (s Set[T]) Cap() int {
-	return cap(s)
-}
-func (s Set[T]) Get(index int) T {
-	return s[index]
-}
-func (s Set[T]) Last() T {
-	return s[s.Len()-1]
-}
-func (s Set[T]) Index(el T) int {
-	return slices.Index(s, el)
-}
-func (s Set[T]) Swap(i, j int) {
-	s[i], s[j] = s[j], s[i]
-}
-func (s Set[T]) Add(v T) Set[T] {
-	index := s.Index(v)
-	if index >= 0 {
-		return s
-	}
-	return append(s, v)
-}
-func (s Set[T]) Pop(index int) Set[T] {
-	if index == 0 {
-		return s[1:]
-	}
-	out := make(Set[T], 0, s.Len()-1)
-	for i, e := range s {
-		if i == index {
-			continue
-		}
-		out = append(out, e)
-	}
-	return out
-}
-func (s Set[T]) Remove(el T) Set[T] {
-	index := s.Index(el)
-	if index == -1 {
-		return s
-	}
-	return s.Pop(index)
-}
-func (s Set[T]) Filter(f func(e T) bool) Set[T] {
-	out := make(Set[T], 0)
-	for _, v := range s {
-		if f(v) {
-			out = append(out, v)
-		}
-	}
-	return out
-}
-func (s Set[T]) ToSlice() Slice[T] {
-	out := make(Slice[T], s.Len())
-	copy(out, s)
-	return out
-}
-func (s Set[T]) ToArray() []T {
-	out := make([]T, len(s))
-	copy(out, s)
-	return out
-}
-func (s Set[T]) ToAnyArray() []any {
-	out := make([]any, len(s))
+// Join formats every element with fmt.Sprintf("%v", value) and joins them
+// using sep.
+func (s Slice[T]) Join(sep string) string {
+	st := make([]string, len(s))
 	for i, v := range s {
-		out[i] = v
+		st[i] = fmt.Sprintf("%v", v)
 	}
-	return out
+	return strings.Join(st, sep)
 }
@@ -0,0 +1,104 @@
+package extypes
+
+import (
+	"fmt"
+	"testing"
+)
+
+type A struct {
+	i int
+	b bool
+	s string
+}
+
+func TestSlice_Index(t *testing.T) {
+	s := make(Slice[int], 10)
+	for i := 0; i < 10; i++ {
+		s[i] = i + 1
+	}
+
+	if s.Index(0) != -1 {
+		t.Errorf("s.Index(0) != -1")
+	}
+	if s.Index(5) != 4 {
+		t.Errorf("s.Index(5) != 4")
+	}
+
+	s2 := make(Slice[A], 5)
+	for i := 0; i < 5; i++ {
+		s2[i] = A{i + 1, false, fmt.Sprint(i)}
+	}
+	if s2.Index(A{2, false, "1"}) != 1 {
+		t.Errorf("s2 wrong index")
+	}
+}
+func TestSlice_Equal(t *testing.T) {
+	a1 := make(Slice[int], 10)
+	a2 := make(Slice[int], 10)
+	a3 := make(Slice[int], 5)
+
+	for i := 0; i < 10; i++ {
+		a1[i] = i
+		a2[i] = i + 1
+	}
+	for i := 0; i < 5; i++ {
+		a3[i] = i
+	}
+
+	if a1.Equal(a2) {
+		t.Errorf("a1 == a2")
+	}
+	if a1.Equal(a3) {
+		t.Errorf("a1 == a3")
+	}
+	if a2.Equal(a3) {
+		t.Errorf("a2 == a3")
+	}
+}
+
+func TestSlice_EqualIgnoresCapacity(t *testing.T) {
+	a1 := make(Slice[int], 2, 2)
+	a2 := make(Slice[int], 2, 4)
+
+	a1[0], a1[1] = 1, 2
+	a2[0], a2[1] = 1, 2
+
+	if !a1.Equal(a2) {
+		t.Errorf("a1 != a2")
+	}
+}
+
+func TestSlice_Pop(t *testing.T) {
+	a1 := make(Slice[int], 10)
+	a2 := make(Slice[int], 9)
+
+	for i := 0; i < 10; i++ {
+		a1[i] = i
+	}
+	for i := 0; i < 9; i++ {
+		a2[i] = i
+	}
+
+	a1 = a1.Pop(a1.Len() - 1)
+
+	if a1.Len() != 9 {
+		t.Errorf("a1.Len() != 9")
+	}
+	if !a1.Equal(a2) {
+		t.Errorf("a1 != a2")
+	}
+}
+
+func TestSlice_PopFrontEqual(t *testing.T) {
+	a1 := make(Slice[int], 3, 5)
+	a2 := make(Slice[int], 2, 2)
+
+	a1[0], a1[1], a1[2] = 0, 1, 2
+	a2[0], a2[1] = 1, 2
+
+	a1 = a1.Pop(0)
+
+	if !a1.Equal(a2) {
+		t.Errorf("a1 != a2")
+	}
+}
@@ -0,0 +1,106 @@
+package extypes
+
+import (
+	"encoding/json"
+	"fmt"
+	"reflect"
+	"strings"
+)
+
+// Tuple is a read-oriented wrapper around Slice.
+//
+// It exposes indexed access and conversion helpers and is useful when an API
+// should return an ordered collection without slice-specific mutation helpers.
+type Tuple[T any] struct {
+	s Slice[T]
+}
+
+// NewTupleFrom wraps src as a Tuple without copying it.
+func NewTupleFrom[T any](src []T) Tuple[T] { return Tuple[T]{src} }
+
+// NewTuple returns an empty Tuple.
+func NewTuple[T any]() Tuple[T] { return Tuple[T]{make(Slice[T], 0)} }
+
+// Len returns the number of elements in the tuple.
+func (t Tuple[T]) Len() int { return t.s.Len() }
+
+// Cap returns the capacity of the underlying slice.
+func (t Tuple[T]) Cap() int { return t.s.Cap() }
+
+// Get returns the element at index.
+func (t Tuple[T]) Get(index int) T { return t.s.Get(index) }
+
+// Equal reports whether both tuples have the same length and pairwise equal
+// elements according to reflect.DeepEqual.
+func (t Tuple[T]) Equal(t2 Tuple[T]) bool {
+	if t.Len() != t2.Len() {
+		return false
+	}
+	for i := range t.s {
+		if !reflect.DeepEqual(t.s[i], t2.s[i]) {
+			return false
+		}
+	}
+	return true
+}
+
+// ToArray returns a copy of the tuple as a built-in slice.
+func (t Tuple[T]) ToArray() []T {
+	out := make([]T, t.Len())
+	copy(out, t.s)
+	return out
+}
+
+// ToAnyArray returns a copy of the tuple converted to []any.
+func (t Tuple[T]) ToAnyArray() []any {
+	out := make([]any, t.Len())
+	for i, v := range t.s {
+		out[i] = v
+	}
+	return out
+}
+
+// ToSet returns a Set built from the tuple values.
+func (t Tuple[T]) ToSet() Set[T] { return NewSetFrom(t.s) }
+
+// ToSlice returns a copy of the tuple as a Slice.
+func (t Tuple[T]) ToSlice() Slice[T] { return NewSliceFrom(t.s) }
+
+// Filter returns a new tuple containing only elements accepted by f.
+func (t Tuple[T]) Filter(f func(e T) bool) Tuple[T] {
+	out := make(Slice[T], 0)
+	for _, v := range t.s {
+		if f(v) {
+			out = append(out, v)
+		}
+	}
+	t.s = out
+	return t
+}
+
+// ForEach calls f for every element and returns the original tuple.
+func (t Tuple[T]) ForEach(f func(int, T)) Tuple[T] {
+	for i, v := range t.s {
+		f(i, v)
+	}
+	return t
+}
+
+// Join formats every element with fmt.Sprintf("%v", value) and joins them
+// using sep.
+func (t Tuple[T]) Join(sep string) string {
+	st := make([]string, len(t.s))
+	for i, v := range t.s {
+		st[i] = fmt.Sprintf("%v", v)
+	}
+	return strings.Join(st, sep)
+}
+
+// String returns the tuple formatted like its underlying slice.
+func (t Tuple[T]) String() string { return fmt.Sprint(t.s) }
+
+// UnmarshalJSON decodes the tuple from a JSON array.
+func (t *Tuple[T]) UnmarshalJSON(data []byte) error { return json.Unmarshal(data, &t.s) }
+
+// MarshalJSON encodes the tuple as a JSON array.
+func (t Tuple[T]) MarshalJSON() ([]byte, error) { return json.Marshal(t.s) }
@@ -0,0 +1,49 @@
+package extypes
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestTuple(t *testing.T) {
+	t1 := NewTupleFrom([]int{1, 2, 3})
+	t2 := NewTupleFrom([]int{1, 2, 3})
+
+	if !t1.Equal(t2) {
+		t.Error("t1 and t2 should be equal")
+	}
+}
+func TestTuple_MarshalJSON(t *testing.T) {
+	t1 := NewTupleFrom([]int{1, 2, 3})
+	data, err := json.Marshal(t1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := "[1,2,3]"
+	if string(data) != s {
+		t.Error("t1 and t2 should be equal")
+	}
+}
+func TestTuple_UnmarshalJSON(t *testing.T) {
+	s := "[1,2,3]"
+	t1 := NewTuple[int]()
+	err := json.Unmarshal([]byte(s), &t1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t2 := NewTupleFrom([]int{1, 2, 3})
+	t.Log(t1, t2)
+	if !t1.Equal(t2) {
+		t.Error("t1 and t2 should be equal")
+	}
+
+	st1 := struct {
+		A int        `json:"a"`
+		B Tuple[int] `json:"b"`
+	}{}
+	s2 := `{"a":1,"b":[1,2,3]}`
+	if err := json.Unmarshal([]byte(s2), &st1); err != nil {
+		t.Fatal(err)
+	}
+	t.Log(st1)
+}
Author	SHA1	Message	Date
ScuroNeko	b1dd8d55fc	go version bump	2026-03-17 15:41:42 +03:00
ScuroNeko	481677a208	docs: add godoc and README files in English and Russian	2026-03-17 15:26:41 +03:00
ScuroNeko	156fa3153c	fix: align slice/set equality and harden queue API	2026-03-17 14:37:35 +03:00
ScuroNeko	4232591fcc	join	2026-02-19 15:05:01 +03:00
ScuroNeko	6d2ef61432	tuple immutable	2026-02-12 13:46:53 +03:00
ScuroNeko	ce8c5b516e	some tests	2026-02-09 17:39:41 +03:00
ScuroNeko	8e203ed8d5	some tests	2026-02-09 16:44:16 +03:00
ScuroNeko	06327013fd	tuple and code cleanup	2026-02-09 16:31:39 +03:00
ScuroNeko	4ba746956a	some testing ang enchancments	2026-02-06 13:46:09 +03:00
ScuroNeko	948ac0a1b0	non comparable slices	2026-02-06 13:18:11 +03:00