package main

import "fmt"

// section: example
func main() {
	fmt.Println("This package contains benchmark tests for maps.")
	fmt.Println("Run benchmarks with: go test -bench=.")
	fmt.Println()
	fmt.Println("Example commands:")
	fmt.Println("  go test -bench=. -benchmem")
	fmt.Println("  go test -bench=BenchmarkMapWithSizeHint -benchmem")
	fmt.Println("  go test -bench=. -benchtime=10s")
	fmt.Println()
	fmt.Println("Key findings from benchmarks:")
	fmt.Println()
	fmt.Println("1. Pre-allocating maps with make(map[K]V, size) significantly improves")
	fmt.Println("   performance by reducing the number of rehashing operations as the")
	fmt.Println("   map grows.")
	fmt.Println()
	fmt.Println("2. The performance benefit of size hints increases with map size:")
	fmt.Println("   Small (100):    2.5x faster (4,048 → 1,599 ns/op), 48% less memory")
	fmt.Println("   Medium (1,000): 3.3x faster (56,187 → 17,288 ns/op), 50% less memory")
	fmt.Println("   Large (10,000): 2.7x faster (513,919 → 192,068 ns/op), 50% less memory")
	fmt.Println()
	fmt.Println("3. Map lookups are very fast (O(1) average case), with minimal difference")
	fmt.Println("   between existing and non-existing keys.")
	fmt.Println()
	fmt.Println("4. Integer keys have similar performance to string keys for pure map operations.")
	fmt.Println("   Representative benchmark (Go 1.25.x, Apple M1 Max):")
	fmt.Println("     BenchmarkMapIntKeys:     32,180 ns/op  36,944 B/op")
	fmt.Println("     BenchmarkMapStringKeys:  33,557 ns/op  54,608 B/op")
	fmt.Println("   Only ~4% faster for ints. The main advantage is 32% less memory usage.")
	fmt.Println("   Note: Previous dramatic differences were due to strconv.Itoa() overhead.")
	fmt.Println()
	fmt.Println("5. For clearing maps, the built-in clear() function (Go 1.21+) is the")
	fmt.Println("   most efficient approach, preserving allocated memory.")
	fmt.Println()
	fmt.Println("Best practices:")
	fmt.Println("- Use make(map[K]V, size) when you know approximate final size")
	fmt.Println("- Prefer integer keys over string keys when possible")
	fmt.Println("- Use clear() for reusing maps (Go 1.21+)")
	fmt.Println("- Consider map capacity during initialization for bulk operations")
	fmt.Println()
	fmt.Println("Note: Benchmark results vary by CPU architecture, Go version, and system")
	fmt.Println("load. Always benchmark your specific use case before optimizing.")
}

// section: example
