### Installation

Source: https://context7.com/lemire/constmap/llms.txt

Install the constmap package using Go modules.

```APIDOC
## Installation

Install the package using Go modules.

```bash
go get github.com/fastfilter/constmap
```
```

--------------------------------

### Install constmap Go Package

Source: https://github.com/lemire/constmap/blob/main/README.md

Installs the constmap library using the go get command. This is the standard way to add external Go packages to your project.

```bash
go get github.com/fastfilter/constmap
```

--------------------------------

### Create and Query a ConstMap

Source: https://context7.com/lemire/constmap/llms.txt

Demonstrates initializing a standard ConstMap with string keys and uint64 values, and performing O(1) lookups.

```go
package main

import (
	"fmt"
	"log"

	"github.com/fastfilter/constmap"
)

func main() {
	keys := []string{"apple", "banana", "cherry", "date", "elderberry"}
	values := []uint64{100, 200, 300, 400, 500}

	cm, err := constmap.New(keys, values)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(cm.Map("apple"))
	fmt.Println(cm.Map("banana"))
	fmt.Println(cm.Map("cherry"))

	emptyCm, err := constmap.New(nil, nil)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(emptyCm != nil)
}
```

--------------------------------

### Create and Query a VerifiedConstMap

Source: https://context7.com/lemire/constmap/llms.txt

Demonstrates initializing a VerifiedConstMap to detect missing keys. It returns a specific NotFound sentinel value for keys not present in the original set.

```go
package main

import (
	"fmt"
	"log"

	"github.com/fastfilter/constmap"
)

func main() {
	keys := []string{"apple", "banana", "cherry"}
	values := []uint64{100, 200, 300}

	vm, err := constmap.NewVerified(keys, values)
	if err != nil {
		log.Fatal(err)
	}

	result := vm.Map("grape")
	if result == constmap.NotFound {
		fmt.Println("Key 'grape' not found")
	}

	fmt.Printf("NotFound value: %d (0x%X)\n", constmap.NotFound, constmap.NotFound)
}
```

--------------------------------

### Running Tests and Benchmarks (Bash)

Source: https://context7.com/lemire/constmap/llms.txt

Instructions for running tests and benchmarks for the constmap package using Go's built-in tooling. This includes commands for running all tests, profiling benchmarks with memory allocation stats, and comparing performance against Go's native map.

```bash
# Run all tests
go test -v

# Run benchmarks with memory allocation stats
go test -bench=. -benchmem

# Run benchmarks with multiple iterations for stable results
go test -bench=. -benchmem -count=5 -benchtime=3s

# Run memory usage comparison test
go test -run TestMemoryUsage -v

# Example benchmark output (Apple M4 Max):
# BenchmarkConstMap-16          158383206    7.6 ns/op     0 B/op   0 allocs/op
# BenchmarkVerifiedConstMap-16   92341726   13.0 ns/op     0 B/op   0 allocs/op
# BenchmarkGoMap-16              52108428   23.0 ns/op     0 B/op   0 allocs/op
```

--------------------------------

### Create and Use Basic ConstMap in Go

Source: https://github.com/lemire/constmap/blob/main/README.md

Demonstrates how to create a new ConstMap with string keys and uint64 values, and perform lookups. The ConstMap is immutable after creation. Keys must be unique and present at construction time; lookups for non-existent keys yield undefined values.

```go
package main

import (
	"fmt"
	"log"

	"github.com/fastfilter/constmap"
)

func main() {
	keys := []string{"apple", "banana", "cherry"}
	values := []uint64{100, 200, 300}

	cm, err := constmap.New(keys, values)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(cm.Map("banana")) // 200
}
```

--------------------------------

### Configure Go Benchmarks for constmap

Source: https://github.com/lemire/constmap/blob/main/README.md

Provides commands to run Go benchmarks with specific configurations for stable and reproducible results. This includes setting the number of benchmark runs and the duration for each run.

```bash
go test -bench=. -benchmem -count=5 -benchtime=3s
```

--------------------------------

### Create and Use VerifiedConstMap in Go

Source: https://github.com/lemire/constmap/blob/main/README.md

Shows how to create a VerifiedConstMap, which includes an additional fingerprint per key to detect missing keys. It returns a specific 'NotFound' sentinel value for keys not present in the original set, unlike the basic ConstMap. This increases memory usage but provides safety against lookups for unknown keys.

```go
package main

import (
	"fmt"
	"log"

	"github.com/fastfilter/constmap"
)

func main() {
	keys := []string{"apple", "banana", "cherry"}
	values := []uint64{100, 200, 300}

	vm, err := constmap.NewVerified(keys, values)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(vm.Map("banana")) // 200
	fmt.Println(vm.Map("grape"))  // constmap.NotFound (0xFFFFFFFFFFFFFFFF)
}
```

--------------------------------

### Run Go Tests for constmap

Source: https://github.com/lemire/constmap/blob/main/README.md

Commands to run the test suite for the constmap package. Includes running verbose tests and benchmarks.

```bash
go test -v
go test -bench=. -benchmem
go test -run TestMemoryUsage -v
```

--------------------------------

### Save and Load ConstMap to/from File in Go

Source: https://github.com/lemire/constmap/blob/main/README.md

Demonstrates serializing a ConstMap to a file using SaveToFile and loading it back using LoadFromFile. This avoids the reconstruction cost. A FNV-1a checksum is included for corruption detection.

```go
// Save to file.
err := cm.SaveToFile("mymap.cmap")

// Load from file.
cm, err := constmap.LoadFromFile("mymap.cmap")
```

--------------------------------

### NewVerified - Create VerifiedConstMap

Source: https://context7.com/lemire/constmap/llms.txt

Creates a `VerifiedConstMap` that stores an additional fingerprint per key to detect missing keys. Returns `NotFound` (0xFFFFFFFFFFFFFFFF) for keys not in the original set. Uses ~18 bytes/key instead of ~9.

```APIDOC
## NewVerified

Creates a `VerifiedConstMap` that stores an additional fingerprint per key to detect missing keys. Returns `NotFound` (0xFFFFFFFFFFFFFFFF) for keys not in the original set. Uses ~18 bytes/key instead of ~9.

### Request Example

```go
package main

import (
	"fmt"
	"log"

	"github.com/fastfilter/constmap"
)

func main() {
	keys := []string{"apple", "banana", "cherry"}
	values := []uint64{100, 200, 300}

	// Create verified map that can detect missing keys
	vm, err := constmap.NewVerified(keys, values)
	if err != nil {
		log.Fatal(err)
	}

	// Lookup existing keys
	fmt.Println(vm.Map("apple"))   // Output: 100
	fmt.Println(vm.Map("banana"))  // Output: 200
	fmt.Println(vm.Map("cherry"))  // Output: 300

	// Missing keys return NotFound sentinel value
	result := vm.Map("grape")
	if result == constmap.NotFound {
		fmt.Println("Key 'grape' not found") // Output: Key 'grape' not found
	}

	// NotFound constant for comparison
	fmt.Printf("NotFound value: %d (0x%X)\n", constmap.NotFound, constmap.NotFound)
	// Output: NotFound value: 18446744073709551615 (0xFFFFFFFFFFFFFFFF)
}
```
```

--------------------------------

### Stream ConstMap to/from io.Writer/io.Reader in Go

Source: https://github.com/lemire/constmap/blob/main/README.md

Illustrates using WriteTo and ReadFrom methods for streaming ConstMap data to any io.Writer or from any io.Reader, enabling flexible serialization and deserialization for network or other stream-based operations.

```go
// Write to any io.Writer.
n, err := cm.WriteTo(w)

// Read from any io.Reader.
var cm constmap.ConstMap
n, err := cm.ReadFrom(r)
```

--------------------------------

### Load ConstMap from File (Go)

Source: https://context7.com/lemire/constmap/llms.txt

Deserializes a ConstMap from a binary file. It verifies the integrity of the data using a trailing checksum, returning an error if corruption is detected. This is essential for ensuring data accuracy after loading.

```go
package main

import (
	"fmt"
	"log"
	"os"

	"github.com/fastfilter/constmap"
)

func main() {
	// Create and save a map
	keys := []string{"user-123", "user-456", "user-789"}
	values := []uint64{1000, 2000, 3000}

	original, err := constmap.New(keys, values)
	if err != nil {
		log.Fatal(err)
	}

	path := "/tmp/users.cmap"
	if err := original.SaveToFile(path); err != nil {
		log.Fatal(err)
	}

	// Load map from file (fast - avoids reconstruction cost)
	loaded, err := constmap.LoadFromFile(path)
	if err != nil {
		log.Fatal(err)
	}

	// Use the loaded map
	fmt.Println(loaded.Map("user-123")) // Output: 1000
	fmt.Println(loaded.Map("user-456")) // Output: 2000
	fmt.Println(loaded.Map("user-789")) // Output: 3000

	// Cleanup
	os.Remove(path)
}
```

--------------------------------

### New - Create ConstMap

Source: https://context7.com/lemire/constmap/llms.txt

Creates a new `ConstMap` from parallel slices of string keys and uint64 values. Keys must be unique and both slices must have equal length.

```APIDOC
## New

Creates a new `ConstMap` from parallel slices of string keys and uint64 values. Keys must be unique and both slices must have equal length.

### Request Example

```go
package main

import (
	"fmt"
	"log"

	"github.com/fastfilter/constmap"
)

func main() {
	// Define keys and their corresponding values
	keys := []string{"apple", "banana", "cherry", "date", "elderberry"}
	values := []uint64{100, 200, 300, 400, 500}

	// Create the immutable map
	cm, err := constmap.New(keys, values)
	if err != nil {
		log.Fatal(err)
	}

	// Lookup values by key
	fmt.Println(cm.Map("apple"))       // Output: 100
	fmt.Println(cm.Map("banana"))      // Output: 200
	fmt.Println(cm.Map("cherry"))      // Output: 300

	// Empty maps are supported
	emptyCm, err := constmap.New(nil, nil)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(emptyCm != nil) // Output: true
}
```
```

--------------------------------

### Save ConstMap to File (Go)

Source: https://context7.com/lemire/constmap/llms.txt

Serializes a ConstMap to a binary file with an appended FNV-1a checksum for integrity. This function takes a file path as input and saves the map's data to that location. It's useful for persistent storage of the map.

```go
package main

import (
	"fmt"
	"log"
	"os"

	"github.com/fastfilter/constmap"
)

func main() {
	keys := []string{"one", "two", "three", "four", "five"}
	values := []uint64{1, 2, 3, 4, 5}

	cm, err := constmap.New(keys, values)
	if err != nil {
		log.Fatal(err)
	}

	// Save to file
	path := "/tmp/mymap.cmap"
	if err := cm.SaveToFile(path); err != nil {
		log.Fatal(err)
	}

	// Verify file was created
	info, err := os.Stat(path)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Saved map to %s (%d bytes)\n", path, info.Size())
	// Output: Saved map to /tmp/mymap.cmap (104 bytes)

	// Cleanup
	os.Remove(path)
}
```

--------------------------------

### Write ConstMap to io.Writer (Go)

Source: https://context7.com/lemire/constmap/llms.txt

Serializes a ConstMap to any `io.Writer` implementation in a portable binary format. A FNV-1a checksum is appended to ensure data integrity. This method is flexible, allowing serialization to files, network connections, or in-memory buffers.

```go
package main

import (
	"bytes"
	"fmt"
	"log"

	"github.com/fastfilter/constmap"
)

func main() {
	keys := []string{"alpha", "beta", "gamma"}
	values := []uint64{10, 20, 30}

	cm, err := constmap.New(keys, values)
	if err != nil {
		log.Fatal(err)
	}

	// Serialize to a buffer (could be any io.Writer: file, network, etc.)
	var buf bytes.Buffer
	bytesWritten, err := cm.WriteTo(&buf)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Serialized %d bytes\n", bytesWritten)
	// Output: Serialized 104 bytes

	// The buffer now contains the binary representation
	fmt.Printf("Buffer size: %d bytes\n", buf.Len())
	// Output: Buffer size: 104 bytes
}
```

--------------------------------

### VerifiedConstMap.Map - Lookup Value with Verification

Source: https://context7.com/lemire/constmap/llms.txt

Retrieves the uint64 value associated with a given key from a `VerifiedConstMap`, or returns `NotFound` if the key was not in the original set. The false positive probability is approximately 2^-64.

```APIDOC
## VerifiedConstMap.Map

Retrieves the uint64 value associated with a given key, or returns `NotFound` if the key was not in the original set. The false positive probability is approximately 2^-64.

### Request Example

```go
package main

import (
	"fmt"
	"log"

	"github.com/fastfilter/constmap"
)

func main() {
	// Build verified map with large dataset
	n := 100000
	keys := make([]string, n)
	values := make([]uint64, n)
	for i := 0; i < n; i++ {
		keys[i] = fmt.Sprintf("key-%d", i)
		values[i] = uint64(i * 7)
	}

	vm, err := constmap.NewVerified(keys, values)
	if err != nil {
		log.Fatal(err)
	}

	// Check existing keys
	fmt.Println(vm.Map("key-50000")) // Output: 350000

	// Check multiple missing keys - all return NotFound
	missingKeys := []string{"missing-1", "missing-2", "not-here"}
	for _, k := range missingKeys {
		if vm.Map(k) == constmap.NotFound {
			fmt.Printf("Key %q not in map\n", k)
		}
	}
	// Output:
	// Key "missing-1" not in map
	// Key "missing-2" not in map
	// Key "not-here" not in map

	// Empty verified maps return NotFound for any key
	emptyVm, _ := constmap.NewVerified(nil, nil)
	fmt.Println(emptyVm.Map("anything") == constmap.NotFound) // Output: true
}
```
```

--------------------------------

### Read ConstMap from io.Reader (Go)

Source: https://context7.com/lemire/constmap/llms.txt

Deserializes a ConstMap from any `io.Reader`. It verifies the data integrity using a trailing checksum, returning an error if corruption is detected. This method is versatile for reading from various sources like files or network streams.

```go
package main

import (
	"bytes"
	"fmt"
	"log"

	"github.com/fastfilter/constmap"
)

func main() {
	// Create and serialize a map
	keys := []string{"config-a", "config-b", "config-c"}
	values := []uint64{111, 222, 333}

	original, _ := constmap.New(keys, values)

	var buf bytes.Buffer
	original.WriteTo(&buf)

	// Deserialize from any io.Reader
	var restored constmap.ConstMap
	bytesRead, err := restored.ReadFrom(bytes.NewReader(buf.Bytes()))
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Read %d bytes\n", bytesRead)
	// Output: Read 104 bytes

	// Verify data integrity
	fmt.Println(restored.Map("config-a")) // Output: 111
	fmt.Println(restored.Map("config-b")) // Output: 222
	fmt.Println(restored.Map("config-c")) // Output: 333

	// Corrupted data is detected via checksum
	corruptedData := buf.Bytes()
	corruptedData[len(corruptedData)/2] ^= 0xff // Flip a byte

	var badMap constmap.ConstMap
	_, err = badMap.ReadFrom(bytes.NewReader(corruptedData))
	if err != nil {
		fmt.Println("Corruption detected:", err != nil) // Output: Corruption detected: true
	}
}
```

--------------------------------

### ConstMap.Map - Lookup Value

Source: https://context7.com/lemire/constmap/llms.txt

Retrieves the uint64 value associated with a given key from a `ConstMap`. The key must have been present in the original set passed to `New`. If the key was not in the original set, the return value is undefined.

```APIDOC
## ConstMap.Map

Retrieves the uint64 value associated with a given key. The key must have been present in the original set passed to `New`. If the key was not in the original set, the return value is undefined.

### Request Example

```go
package main

import (
	"fmt"
	"log"

	"github.com/fastfilter/constmap"
)

func main() {
	// Build a large map with 100,000 entries
	n := 100000
	keys := make([]string, n)
	values := make([]uint64, n)
	for i := 0; i < n; i++ {
		keys[i] = fmt.Sprintf("key-%d", i)
		values[i] = uint64(i * 7)
	}

	cm, err := constmap.New(keys, values)
	if err != nil {
		log.Fatal(err)
	}

	// Fast O(1) lookups - ~7.6 ns/op
	fmt.Println(cm.Map("key-0"))      // Output: 0
	fmt.Println(cm.Map("key-1000"))   // Output: 7000
	fmt.Println(cm.Map("key-99999"))  // Output: 699993
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.