linker

linker

import "github.com/Compogo/types/linker"

Index

• func Copy[T comparable, I any](dst *Linker[T, I], src *Linker[T, I])
• type Linker
  • func NewLinker[T comparable, I any](options ...Option[T, I]) *Linker[T, I]
  • func (linker *Linker[T, I]) Add(key T, value I)
  • func (linker *Linker[T, I]) All() iter.Seq2[T, I]
  • func (linker *Linker[T, I]) Clone() *Linker[T, I]
  • func (linker *Linker[T, I]) Difference(l *Linker[T, I]) *Linker[T, I]
  • func (linker *Linker[T, I]) Get(key T) (I, error)
  • func (linker *Linker[T, I]) GetOrDefault(key T, d I) I
  • func (linker *Linker[T, I]) Has(key T) bool
  • func (linker *Linker[T, I]) HasAnd(items ...T) bool
  • func (linker *Linker[T, I]) HasOr(items ...T) bool
  • func (linker *Linker[T, I]) Intersection(l *Linker[T, I]) *Linker[T, I]
  • func (linker *Linker[T, I]) Keys() []T
  • func (linker *Linker[T, I]) Len() int
  • func (linker *Linker[T, I]) Remove(key T)
  • func (linker *Linker[T, I]) Replace(l *Linker[T, I])
  • func (linker *Linker[T, I]) Reset()
  • func (linker *Linker[T, I]) SymmetricDifference(l *Linker[T, I]) *Linker[T, I]
  • func (linker *Linker[T, I]) Union(l *Linker[T, I]) *Linker[T, I]
  • func (linker *Linker[T, I]) UnionByStrategy(l *Linker[T, I], strategy Strategy) *Linker[T, I]
• type Normalizer
• type Option
  • func KeyStringNormalizer[I any]() Option[string, I]
  • func Link[T comparable, I any](key T, val I) Option[T, I]
  • func WithNormalizer[T comparable, I any](normalizer Normalizer[T]) Option[T, I]
• type Strategy

func Copy

func Copy[T comparable, I any](dst *Linker[T, I], src *Linker[T, I])

Copy копирует все элементы из src в dst. Если ключ уже существует в dst, он будет перезаписан.

Пример:

dst := NewLinker[string, int]()
src := NewLinker[string, int](Link("one", 1))
Copy(dst, src) // dst содержит {"one": 1}

type Linker

Linker представляет собой обобщённое отображение (map) ключей типа T на значения типа I. Поддерживает:

• Нормализацию ключей (например, приведение к нижнему регистру)
• Функциональные опции для конфигурации
• Операции над множествами (Union, Intersection, Difference, SymmetricDifference)
• Итерацию через All()
• Клонирование и копирование

Тип T должен быть сравниваемым (comparable), тип I может быть любым.

type Linker[T comparable, I any] struct {
    // contains filtered or unexported fields
}

func NewLinker

func NewLinker[T comparable, I any](options ...Option[T, I]) *Linker[T, I]

NewLinker создаёт новый Linker с опциональными настройками. Применяются следующие опции по умолчанию:

• Стандартный нормализатор (ключ без изменений)
• Опции переданные в вызове

Пример:

type Key string
linker := NewLinker[Key, int](
    WithNormalizer[Key, int](func(k Key) Key { return Key(strings.ToLower(string(k))) }),
    Link(Key("one"), 1),
    Link(Key("two"), 2),
)

func (*Linker[T, I]) Add

func (linker *Linker[T, I]) Add(key T, value I)

Add добавляет пару (ключ, значение) в Linker. Ключ перед добавлением нормализуется с помощью normalizer. Если ключ уже существует, значение будет перезаписано.

Пример:

linker := NewLinker[string, int](KeyStringNormalizer[int]())
linker.Add("KEY", 42)
linker.Add("key", 100) // перезапишет значение для "key"

func (*Linker[T, I]) All

func (linker *Linker[T, I]) All() iter.Seq2[T, I]

All возвращает итератор для обхода всех элементов Linker. Реализует интерфейс iter.Seq2, позволяя использовать range в цикле. Возвращает пары (ключ, значение) в нормализованном виде.

Пример:

for key, value := range linker.All() {
    fmt.Printf("%v: %v\n", key, value)
}

Итерацию можно прервать досрочно:

for key, value := range linker.All() {
    if someCondition(value) {
        break
    }
}

func (*Linker[T, I]) Clone

func (linker *Linker[T, I]) Clone() *Linker[T, I]

Clone создаёт глубокую копию Linker. Нормализатор также копируется.

Пример:

original := NewLinker[string, int](Link("one", 1))
copy := original.Clone()
copy.Add("two", 2) // original не изменится

func (*Linker[T, I]) Difference

func (linker *Linker[T, I]) Difference(l *Linker[T, I]) *Linker[T, I]

Difference возвращает новый Linker, содержащий элементы текущего линкера, ключи которых отсутствуют в переданном линкере.

Пример:

a := NewLinker[string, int](Link("one", 1), Link("two", 2))
b := NewLinker[string, int](Link("two", 20), Link("three", 3))
c := a.Difference(b) // содержит {"one": 1}

func (*Linker[T, I]) Get

func (linker *Linker[T, I]) Get(key T) (I, error)

Get возвращает значение по ключу. Ключ нормализуется перед поиском.

Возвращает:

• I — найденное значение
• error — ошибку DoesNotExistError, если ключ не найден

Пример:

linker := NewLinker[string, int](Link("one", 1))
val, err := linker.Get("ONE")
if errors.Is(err, errors.DoesNotExistError) {
    // ключ не найден
}

func (*Linker[T, I]) GetOrDefault

func (linker *Linker[T, I]) GetOrDefault(key T, d I) I

GetOrDefault возвращает значение по ключу или значение по умолчанию d, если ключ не найден. Ключ нормализуется перед поиском.

Пример:

linker := NewLinker[string, int](Link("one", 1))
val := linker.GetOrDefault("TWO", 0) // возвращает 0

func (*Linker[T, I]) Has

func (linker *Linker[T, I]) Has(key T) bool

Has проверяет наличие ключа в Linker. Ключ нормализуется перед проверкой.

Пример:

linker := NewLinker[string, int](Link("one", 1))
if linker.Has("ONE") {
    // ключ существует
}

func (*Linker[T, I]) HasAnd

func (linker *Linker[T, I]) HasAnd(items ...T) bool

HasAnd проверяет, содержатся ли ВСЕ переданные ключи в Linker. Возвращает true, только если каждый ключ присутствует.

Пример:

linker := NewLinker[string, int](Link("one", 1), Link("two", 2))
linker.HasAnd("one", "two") // true
linker.HasAnd("one", "three") // false

func (*Linker[T, I]) HasOr

func (linker *Linker[T, I]) HasOr(items ...T) bool

HasOr проверяет, содержится ли ХОТЯ БЫ ОДИН из переданных ключей в Linker. Возвращает true при первом же найденном ключе.

Пример:

linker := NewLinker[string, int](Link("one", 1), Link("two", 2))
linker.HasOr("three", "one") // true
linker.HasOr("three", "four") // false

func (*Linker[T, I]) Intersection

func (linker *Linker[T, I]) Intersection(l *Linker[T, I]) *Linker[T, I]

Intersection возвращает новый Linker, содержащий только те пары (ключ, значение), ключи которых присутствуют в обоих линкерах. Значения берутся из линкера, который используется для итерации (того, который меньше по размеру).

Пример:

a := NewLinker[string, int](Link("one", 1), Link("two", 2))
b := NewLinker[string, int](Link("two", 20), Link("three", 3))
c := a.Intersection(b) // содержит {"two": 2} или {"two": 20} (зависит от размера)

func (*Linker[T, I]) Keys

func (linker *Linker[T, I]) Keys() []T

Keys возвращает срез всех ключей, хранящихся в Linker. Порядок ключей не гарантируется.

Пример:

for _, key := range linker.Keys() {
    fmt.Println(key)
}

func (*Linker[T, I]) Len

func (linker *Linker[T, I]) Len() int

Len возвращает количество элементов в Linker.

Пример:

linker := NewLinker[string, int](Link("one", 1), Link("two", 2))
fmt.Println(linker.Len()) // 2

func (*Linker[T, I]) Remove

func (linker *Linker[T, I]) Remove(key T)

Remove удаляет ключ и связанное с ним значение из Linker. Ключ нормализуется перед удалением. Если ключ не найден, метод ничего не делает.

Пример:

linker := NewLinker[string, int](Link("one", 1))
linker.Remove("ONE") // удаляет запись

func (*Linker[T, I]) Replace

func (linker *Linker[T, I]) Replace(l *Linker[T, I])

Replace заменяет содержимое текущего линкера на содержимое переданного. Текущий линкер очищается, после чего в него копируются все элементы из l. Нормализатор текущего линкера не изменяется.

Пример:

a := NewLinker[string, int](Link("one", 1))
b := NewLinker[string, int](Link("two", 2))
a.Replace(b) // a теперь содержит {"two": 2}

func (*Linker[T, I]) Reset

func (linker *Linker[T, I]) Reset()

Reset очищает Linker, удаляя все элементы.

Пример:

linker.Reset()
fmt.Println(linker.Len()) // 0

func (*Linker[T, I]) SymmetricDifference

func (linker *Linker[T, I]) SymmetricDifference(l *Linker[T, I]) *Linker[T, I]

SymmetricDifference возвращает новый Linker, содержащий элементы, которые присутствуют либо в текущем линкере, либо в переданном, но не в обоих одновременно.

Пример:

a := NewLinker[string, int](Link("one", 1), Link("two", 2))
b := NewLinker[string, int](Link("two", 20), Link("three", 3))
c := a.SymmetricDifference(b) // содержит {"one": 1, "three": 3}

func (*Linker[T, I]) Union

func (linker *Linker[T, I]) Union(l *Linker[T, I]) *Linker[T, I]

Union возвращает объединение текущего линкера и переданного. Использует стратегию Optimization (см. UnionByStrategy).

Пример:

a := NewLinker[string, int](Link("one", 1))
b := NewLinker[string, int](Link("two", 2))
c := a.Union(b) // содержит {"one": 1, "two": 2}

При конфликте ключей значение берётся из линкера, который был клонирован (зависит от стратегии).

func (*Linker[T, I]) UnionByStrategy

func (linker *Linker[T, I]) UnionByStrategy(l *Linker[T, I], strategy Strategy) *Linker[T, I]

UnionByStrategy возвращает объединение линкеров с использованием указанной стратегии. Доступные стратегии:

• Optimization (умный выбор — клонируется больший линкер)
• CurrentLinker (клонируется текущий линкер, добавляются элементы из l)
• IncomingLinker (клонируется линкер l, добавляются элементы из текущего)

При конфликте ключей значение берётся из клонируемого линкера.

Пример:

a := NewLinker[string, int](Link("one", 1))
b := NewLinker[string, int](Link("one", 100))
c := a.UnionByStrategy(b, CurrentLinker) // c["one"] == 1
d := a.UnionByStrategy(b, IncomingLinker) // d["one"] == 100

type Normalizer

Normalizer определяет функцию нормализации ключей. Принимает ключ и возвращает его нормализованную версию. По умолчанию используется функция, возвращающая ключ без изменений.

type Normalizer[T comparable] func(key T) T

type Option

Option представляет функцию настройки (functional option) для Linker. Используется для конфигурирования поведения Linker при создании.

type Option[T comparable, I any] func(l *Linker[T, I])

func KeyStringNormalizer

func KeyStringNormalizer[I any]() Option[string, I]

KeyStringNormalizer возвращает опцию для регистронезависимой нормализации строковых ключей. Применяется только для Linker с типом ключа string. Все ключи будут приведены к нижнему регистру.

Пример:

linker := NewLinker[string, int](
    KeyStringNormalizer[int](),
)
linker.Add("KEY", 42)
linker.Has("key") // true

func Link

func Link[T comparable, I any](key T, val I) Option[T, I]

Link создаёт опцию для добавления пары (ключ, значение) в Linker. Полезно для начальной инициализации Linker при вызове NewLinker.

Пример:

linker := NewLinker[string, int](
    Link("one", 1),
    Link("two", 2),
)

func WithNormalizer

func WithNormalizer[T comparable, I any](normalizer Normalizer[T]) Option[T, I]

WithNormalizer устанавливает пользовательскую функцию нормализации ключей. Нормализатор применяется ко всем операциям с ключами (Add, Get, Has, Remove).

Пример:

linker := NewLinker[string, int](
    WithNormalizer(strings.ToUpper),
)

type Strategy

Strategy представляет стратегию слияния двух Linker'ов.

type Strategy uint8

Strategy определяет стратегию поведения при объединении (Union) двух Linker'ов. Используется в функции UnionByStrategy.

const (
    // Optimization (значение по умолчанию) выбирает наиболее эффективную стратегию
    // в зависимости от размера линкеров (клонируется меньший).
    Optimization Strategy = iota

    // CurrentLinker при объединении клонирует текущий Linker (CurrentLinker)
    // и добавляет в него элементы входящего линкера (IncomingLinker).
    CurrentLinker

    // IncomingLinker при объединении клонирует входящий Linker (IncomingLinker)
    // и добавляет в него элементы текущего линкера (CurrentLinker).
    IncomingLinker
)

Generated by gomarkdoc