extypes/README_ru.md

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+

Установка

go get git.nix13.pw/scuroneko/extypes

Импорт

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

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

tuple := extypes.NewTupleFrom([]string{"api", "worker", "cron"})

filtered := tuple.Filter(func(v string) bool {
	return v != "worker"
})

fmt.Println(filtered.Join(", ")) // api, cron

Set

set := extypes.NewSetFrom([]string{"go", "go", "docs", "tests"})

set = set.Add("bench")
set = set.Remove("docs")

fmt.Println(set.ToArray()) // [go tests bench]

HashMap

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

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

Запуск тестов

go test ./...

Godoc

Для публичного API добавлены doc-комментарии, поэтому локальную документацию можно смотреть стандартными инструментами Go:

go doc
go doc git.nix13.pw/scuroneko/extypes