maps

type Map[K comparable, V any] interface {
	// Insert adds a key-value pair to the map. If the key already
	// exists, the value is updated and the result (false, nil) is
	// returned.
	//
	// Parameters:
	//   - key: The key of the pair.
	//   - value: The value of the pair.
	//
	// Returns:
	//   - bool: A boolean indicating if the key already exists in the
	//     map.
	//   - error: An error if the key cannot be added to the map.
	//
	// Errors:
	//   - common.ErrNilReceiver: If the receiver is nil.
	//   - any other error: Implementation-dependent.
	Insert(key K, value V) (bool, error)

	// ByKey returns the value associated with the given key.
	//
	// Parameters:
	//   - key: The key of the pair.
	//
	// Returns:
	//   - V: The value associated with the key.
	//   - bool: A boolean indicating if the key exists in the map.
	ByKey(key K) (V, bool)

	// Key returns a sequence of keys in the map. The order of the
	// returned keys is undefined.
	//
	// Returns:
	//   - iter.Seq[K]: A sequence of keys in the map. Never returns nil.
	Key() iter.Seq[K]

	// Value returns a sequence of values in the map. The order of the
	// returned values is undefined.
	//
	// Returns:
	//   - iter.Seq[V]: A sequence of values in the map. Never returns
	// 	nil.
	Value() iter.Seq[V]

	// Entry returns a sequence of key-value pairs in the map. The order
	// of the returned pairs is undefined.
	//
	// Returns:
	//   - iter.Seq2[K, V]: A sequence of key-value pairs in the map.
	//     Never returns nil.
	Entry() iter.Seq2[K, V]

	// Reset resets the map for reuse.
	//
	// Returns:
	//   - error: An error if the map could not be reset.
	//
	// Errors:
	//   - common.ErrNilReceiver: If the receiver is nil.
	//   - any other error: Implementation-dependent.
	Reset() error

	// Delete removes the key-value pair with the given key from the
	// map.
	//
	// Parameters:
	//   - key: The key of the pair to remove.
	//
	// Returns:
	//   - bool: A boolean indicating if the key was found in the map.
	//   - error: An error if the key cannot be removed from the map.
	//
	// Errors:
	//   - common.ErrNilReceiver: If the receiver is nil.
	//   - any other error: Implementation-dependent.
	Delete(key K) (bool, error)
}

type OrderMap[K comparable, V any] struct {
	// contains filtered or unexported fields
}

type SortMap[K cmp.Ordered, V any] struct {
	// contains filtered or unexported fields
}