maps.go

// This implementation is inspired by Apache Commons Collections
// (licensed under the Apache License, Version 2.0).
package orderedmap

import "iter"

// MaxCapacity defines the maximum number of elements
// the map can hold. It is set to 2^30 to prevent excessive memory usage.
const MaxCapacity = 1 << 30

// DefaultCapacity is the initial capacity of the map
// when no specific size is provided. Typical default is 16.
const DefaultCapacity = 16

// DefaultLoadFactor determines when the map should grow
// (rehash). A load factor of 0.75 means the map will resize
// when 75% full.
const DefaultLoadFactor = 0.75

// Map is a generic interface for an ordered map that preserves
// the insertion order of keys. It supports basic map operations,
// iteration, and cloning.
//
// K - key type
// V - value type
type Map[K, V any] interface {
	// Size returns the number of elements in the map.
	Size() int

	// IsEmpty returns true if the map contains no elements.
	IsEmpty() bool

	// Clear removes all elements from the map.
	Clear()

	// Clone creates a shallow copy of the map.
	Clone() Map[K, V]

	// Get returns the value associated with the given key
	// and a boolean indicating if the key exists.
	Get(K) (V, bool)

	// Put inserts or updates the value for a key. It returns
	// the previous value and a boolean indicating if the key existed.
	Put(K, V) (V, bool)

	// Delete removes the key from the map. Returns the value
	// and a boolean indicating if the key existed.
	Delete(K) (V, bool)

	// Keys returns a sequence of keys in insertion order.
	Keys() iter.Seq[K]

	// Values returns a sequence of values in insertion order.
	Values() iter.Seq[V]

	// Items returns a sequence of key-value pairs in insertion order.
	Items() iter.Seq2[K, V]
}

// Integer is a type constraint for all built-in integer types.
// It includes both signed and unsigned integers of all sizes.
type Integer interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64
}