kset

type KeySet[Key any] interface {
	Set[Key]

	// Append upserts multiple elements to the set.
	// It returns the number of elements that were actually added (i.e., were not already present).
	// Example:
	//  s := kset.HashMapKey(1)
	//  count := s.Append(1, 2, 3) // count is 2
	Append(values ...Key) int

	// Clone creates a shallow copy of the set.
	// Example:
	//  s1 := kset.HashMapKey(1, 2)
	//  s2 := s1.Clone() // s2 is {1, 2}, independent of s1
	//  s2.Add(3)
	//  // s1 is {1, 2}, s2 is {1, 2, 3}
	Clone() KeySet[Key]

	// Difference returns a new set containing elements that are in the current set but not in the other set.
	// Example:
	//  s1 := kset.HashMapKey(1, 2, 3)
	//  s2 := kset.HashMapKey(3, 4, 5)
	//  diff := s1.Difference(s2) // diff is {1, 2}
	Difference(other Set[Key]) KeySet[Key]

	// DifferenceKeys returns a new set, not containing the given keys.
	// Example:
	//  s1 := kset.HashMapKey(1, 2, 3)
	//  s2 := kset.HashMapKey(3, 4, 5)
	//  diff := s1.Difference(s2) // diff is {1, 2}
	DifferenceKeys(keys ...Key) KeySet[Key]

	// Intersect returns a new set containing elements that are common to both the current set and the other set.
	// Example:
	//  s1 := kset.HashMapKey(1, 2, 3)
	//  s2 := kset.HashMapKey(3, 4, 5)
	//  intersection := s1.Intersect(s2) // intersection is {3}
	Intersect(other Set[Key]) KeySet[Key]

	// RemoveKeys removes the specified elements from the set.
	// Example:
	//  s := kset.HashMapKey(1, 2, 3, 4)
	//  s.RemoveKeys(2, 4) // s is {1, 3}
	RemoveKeys(v ...Key)

	// SymmetricDifference returns a new set containing elements that are in either the current set or the other set, but not both.
	// Example:
	//  s1 := kset.HashMapKey(1, 2, 3)
	//  s2 := kset.HashMapKey(3, 4, 5)
	//  symDiff := s1.SymmetricDifference(s2) // symDiff is {1, 2, 4, 5}
	SymmetricDifference(other KeySet[Key]) KeySet[Key]

	// Union returns a new set containing all elements from both the current set and the other set.
	// Example:
	//  s1 := kset.HashMapKey(1, 2)
	//  s2 := kset.HashMapKey(2, 3)
	//  union := s1.Union(s2) // union is {1, 2, 3}
	Union(other KeySet[Key]) KeySet[Key]

	// Pop removes and returns an arbitrary element from the set.
	// It returns the removed element and true if the set was not empty, otherwise it returns the zero value of V and false.
	// Example:
	//  s := kset.HashMapKey(1, 2)
	//  v, ok := s.Pop() // v could be 1 or 2, ok is true
	//  v, ok = s.Pop() // v is the remaining element, ok is true
	//  v, ok = s.Pop() // v is 0, ok is false
	Pop() (Key, bool)

	// Slice returns a slice containing all elements of the set.
	// The order of elements in the slice is not guaranteed.
	// Example:
	//  s := kset.HashMapKey(3, 1, 2)
	//  slice := s.Slice() // slice could be []int{1, 2, 3}, []int{3, 1, 2}, etc.
	Slice() []Key
}

type KeyValueSet[Key comparable, Value any] interface {
	Set[Key]

	// Append upserts multiple elements to the set.
	// It returns the number of elements that were actually added (i.e., were not already present).
	// Example:
	//  s := kset.HashMapKeyValue(func(v int) int { return v }, 1)
	//  count := s.Append(1, 2, 3) // count is 2
	Append(values ...Value) int

	// Clone creates a shallow copy of the set.
	// Example:
	//  s1 := kset.HashMapKeyValue(func(v int) int { return v }, 1, 2)
	//  s2 := s1.Clone() // s2 is {1, 2}, independent of s1
	//  s2.Add(3)
	//  // s1 is {1, 2}, s2 is {1, 2, 3}
	Clone() KeyValueSet[Key, Value]

	// Contains checks if all specified elements are present in the set.
	// It returns true if all elements v are in the set, false otherwise.
	// Example:
	//  s := kset.HashMapKeyValue(func(v int) int { return v }, 1, 2, 3)
	//  hasAll := s.Contains(1, 2) // hasAll is true
	//  hasAll = s.Contains(1, 4) // hasAll is false
	Contains(values ...Value) bool

	// ContainsAny checks if any of the specified elements are present in the set.
	// It returns true if at least one element v is in the set, false otherwise.
	// Example:
	//  s := kset.HashMapKeyValue(func(v int) int { return v }, 1, 2)
	//  hasAny := s.ContainsAny(2, 4) // hasAny is true
	//  hasAny = s.ContainsAny(4, 5) // hasAny is false
	ContainsAny(values ...Value) bool

	// Difference returns a new set containing elements that are in the current set but not in the other set.
	// Example:
	//  s1 := kset.HashMapKeyValue(func(v int) int { return v }, 1, 2, 3)
	//  s2 := kset.HashMapKeyValue(func(v int) int { return v }, 3, 4, 5)
	//  diff := s1.Difference(s2) // diff is {1, 2}
	Difference(other Set[Key]) KeyValueSet[Key, Value]

	// DifferenceKeys returns a copy of the current set, excluding the given keys.
	// Example:
	//  s1 := kset.HashMapKeyValue(func(v int) int { return v }, 1, 2, 3)
	//  diff := s1.DifferenceKeys(3) // diff is {1, 2}
	DifferenceKeys(keys ...Key) KeyValueSet[Key, Value]

	// Intersect returns a new set containing elements that are common to both the current set and the other set.
	// Example:
	//  s1 := kset.HashMapKeyValue(func(v int) int { return v }, 1, 2, 3)
	//  s2 := kset.HashMapKeyValue(func(v int) int { return v }, 3, 4, 5)
	//  intersection := s1.Intersect(s2) // intersection is {3}
	Intersect(other Set[Key]) KeyValueSet[Key, Value]

	// KeyValues returns an iterator (iter.Seq) over the elements of the set.
	// The order of iteration is not guaranteed.
	// Example:
	//  s := kset.HashMapKeyValue(func(v int) int { return v }, 1, 2, 3)
	//  for v := range s.KeyValues() {
	//      fmt.Println(v) // Prints 1, 2, 3 in some order
	//  }
	KeyValues() iter.Seq2[Key, Value]

	// Remove removes the specified elements from the set.
	// Example:
	//  s := kset.HashMapKeyValue(func(v int) int { return v }, 1, 2, 3, 4)
	//  s.Remove(2, 4) // s is {1, 3}
	Remove(v ...Value)

	// RemoveKeys removes the specified keys from the set.
	// Example:
	//  s := kset.HashMapKeyValue(func(v int) int { return v }, 1, 2, 3, 4)
	//  s.RemoveKeys(2, 4) // s is {1, 3}
	RemoveKeys(v ...Key)

	// SymmetricDifference returns a new set containing elements that are in either the current set or the other set, but not both.
	// Example:
	//  s1 := kset.HashMapKeyValue(func(v int) int { return v }, 1, 2, 3)
	//  s2 := kset.HashMapKeyValue(func(v int) int { return v }, 3, 4, 5)
	//  symDiff := s1.SymmetricDifference(s2) // symDiff is {1, 2, 4, 5}
	SymmetricDifference(other KeyValueSet[Key, Value]) KeyValueSet[Key, Value]

	// Union returns a new set containing all elements from both the current set and the other set.
	// Example:
	//  s1 := kset.HashMapKeyValue(func(v int) int { return v }, 1, 2)
	//  s2 := kset.HashMapKeyValue(func(v int) int { return v }, 2, 3)
	//  union := s1.Union(s2) // union is {1, 2, 3}
	Union(other KeyValueSet[Key, Value]) KeyValueSet[Key, Value]

	// Pop removes and returns an arbitrary element from the set.
	// It returns the removed element and true if the set was not empty, otherwise it returns the zero value of V and false.
	// Example:
	//  s := kset.HashMapKeyValue(func(v int) int { return v }, 1, 2)
	//  v, ok := s.Pop() // v could be 1 or 2, ok is true
	//  v, ok = s.Pop() // v is the remaining element, ok is true
	//  v, ok = s.Pop() // v is 0, ok is false
	Pop() (Value, bool)

	// Slice returns a slice containing all elements of the set.
	// The order of elements in the slice is not guaranteed.
	// Example:
	//  s := kset.HashMapKeyValue(func(v int) int { return v }, 3, 1, 2)
	//  slice := s.Slice() // slice could be []int{1, 2, 3}, []int{3, 1, 2}, etc.
	Slice() []Value

	// Map returns a map representation of the set.
	// Example:
	//  s := kset.HashMapKeyValue(func(v int) int { return v }, 3, 1, 2)
	//  m := s.Map() // m returns map[int]int{ 1:1, 2:2, 3:3 }
	Map() map[Key]Value
}

type Set[Key any] interface {
	// Len returns the number of elements in the set.
	// Example:
	//  s := kset.HashMapKey(1, 2)
	//  length := s.Len() // length is 2
	Len() int

	// Clear removes all elements from the set.
	// Example:
	//  s := kset.HashMapKey(1, 2)
	//  s.Clear() // s is {}
	//  length := s.Len() // length is 0
	Clear()

	// Contains checks if all specified elements are present in the set.
	// It returns true if all elements v are in the set, false otherwise.
	// Example:
	//  s := kset.HashMapKey(1, 2, 3)
	//  hasAll := s.ContainsKeys(1, 2) // hasAll is true
	//  hasAll = s.ContainsKeys(1, 4) // hasAll is false
	ContainsKeys(keys ...Key) bool

	// ContainsAny checks if any of the specified elements are present in the set.
	// It returns true if at least one element v is in the set, false otherwise.
	// Example:
	//  s := kset.HashMapKey(1, 2)
	//  hasAny := s.ContainsAnyKey(2, 4) // hasAny is true
	//  hasAny = s.ContainsAnyKey(4, 5) // hasAny is false
	ContainsAnyKey(keys ...Key) bool

	// IsEmpty checks if the set contains no elements.
	// Example:
	//  s := kset.HashMapKey[int]()
	//  s.IsEmpty() // empty is true
	//  s.Add(1)
	//  empty = s.IsEmpty() // empty is false
	IsEmpty() bool

	// IsProperSubset checks if the set is a proper subset of another set.
	// A proper subset is a subset that is not equal to the other set.
	// Example:
	//  s1 := kset.HashMapKey(1, 2)
	//  s2 := kset.HashMapKey(1, 2, 3)
	//  s3 := kset.HashMapKey(1, 2)
	//  isProper := s1.IsProperSubset(s2) // isProper is true
	//  isProper = s1.IsProperSubset(s3) // isProper is false
	IsProperSubset(other Set[Key]) bool

	// IsProperSuperset checks if the set is a proper superset of another set.
	// A proper superset is a superset that is not equal to the other set.
	// Example:
	//  s1 := kset.HashMapKey(1, 2, 3)
	//  s2 := kset.HashMapKey(1, 2)
	//  s3 := kset.HashMapKey(1, 2, 3)
	//  isProper := s1.IsProperSuperset(s2) // isProper is true
	//  isProper = s1.IsProperSuperset(s3) // isProper is false
	IsProperSuperset(other Set[Key]) bool

	// IsSubset checks if the set is a subset of another set (i.e., all elements of the current set are also in the other set).
	// Example:
	//  s1 := kset.HashMapKey(1, 2)
	//  s2 := kset.HashMapKey(1, 2, 3)
	//  s3 := kset.HashMapKey(1, 3)
	//  isSub := s1.IsSubset(s2) // isSub is true
	//  isSub = s1.IsSubset(s3) // isSub is false
	IsSubset(other Set[Key]) bool

	// IsSuperset checks if the set is a superset of another set (i.e., all elements of the other set are also in the current set).
	// Example:
	//  s1 := kset.HashMapKey(1, 2, 3)
	//  s2 := kset.HashMapKey(1, 2)
	//  s3 := kset.HashMapKey(1, 4)
	//  isSuper := s1.IsSuperset(s2) // isSuper is true
	//  isSuper = s1.IsSuperset(s3) // isSuper is false
	IsSuperset(other Set[Key]) bool

	// Intersects checks if the set has at least one element in common with another set.
	// Example:
	//  s1 := kset.HashMapKey(1, 2)
	//  s2 := kset.HashMapKey(2, 3)
	//  s3 := kset.HashMapKey(4, 5)
	//  intersects := s1.Intersects(s2) // intersects is true
	//  intersects = s1.Intersects(s3) // intersects is false
	Intersects(other Set[Key]) bool

	// Equal checks if the set is equal to another set (i.e., contains the same elements).
	// Example:
	//  s1 := kset.HashMapKey(1, 2)
	//  s2 := kset.HashMapKey(2, 1)
	//  s3 := kset.HashMapKey(1, 3)
	//  isEqual := s1.Equal(s2) // isEqual is true
	//  isEqual = s1.Equal(s3) // isEqual is false
	Equal(other Set[Key]) bool

	// Keys iterates through all keys stored in the set.
	// Example:
	//	set := kset.HashMapKey(1, 2, 3)
	//	set.Keys() // returns iter[1, 2, 3]
	Keys() iter.Seq[Key]
}

type Storage[Key, Value any] interface {
	Len() int
	Clear()
	Delete(...Key)
	Contains(Key) bool
	Get(Key) (Value, bool)
	Upsert(Key, Value)
	Iter() iter.Seq2[Key, Value]
	Clone() Storage[Key, Value]
}