tinymap

README

tinymap

tinymap is a Go package providing a slice-based map implementation that stores key-value pairs as a slice of structs. It is inspired by and based on the userData type from github.com/valyala/fasthttp.

This package is particularly useful in scenarios where you need a lightweight and straightforward map-like structure with a predictable memory layout.

Features

• Slice-based Map: Keys and values are stored as slices of key-value pairs.
• Custom Key Types: Supports string and []byte keys.
• Memory-Efficient Reset: Resets the map while ensuring proper cleanup of resources implementing the io.Closer interface.

Installation

Install the package using go get:

$ go get github.com/axkit/tinymap

Usage

Here is how you can use the tinymap package:

Basic Operations

package main

import (
    "fmt"
    "github.com/axkit/tinymap"
)

func main() {
    var tm tinymap.TinyMap

    // Set key-value pairs
    tm.Set("foo", 42)
    tm.Set("bar", "hello")

    // Retrieve values by key
    fmt.Println(tm.Get("foo"))  // Output: 42
    fmt.Println(tm.Get("bar"))  // Output: hello

    // Use byte slice keys
    tm.SetBytes([]byte("baz"), 3.14)
    fmt.Println(tm.GetBytes([]byte("baz")))  // Output: 3.14

    // Visit all key-value pairs
    tm.VisitValues(func(key []byte, value interface{}) {
        fmt.Printf("Key: %s, Value: %v\n", key, value)
    })

    // Reset the map
    tm.Reset()
    fmt.Println(tm.Get("foo")) // Output: <nil>
}

Benchmarking

You can compare the performance of tinymap against standard Go maps by running the provided benchmarks:

$ go test -bench . -benchmem
goos: linux
goarch: amd64
pkg: github.com/axkit/tinymap
cpu: Intel(R) Core(TM) i7-6700HQ CPU @ 2.60GHz
BenchmarkTinyMapCustom-8        53070952                20.79 ns/op            0 B/op          0 allocs/op
BenchmarkTinyMapStdMap-8        30541206                37.11 ns/op            0 B/op          0 allocs/op
PASS
ok      github.com/axkit/tinymap        2.306s

API Reference

TinyMap

Methods

• Set(key string, value interface{}): Adds or updates a key-value pair.
• SetBytes(key []byte, value interface{}): Adds or updates a key-value pair using a byte slice as the key.
• Get(key string) interface{}: Retrieves the value for a given key. Returns nil if the key does not exist.
• GetBytes(key []byte) interface{}: Retrieves the value for a byte slice key.
• Reset(): Clears all key-value pairs, calling Close on any values that implement the io.Closer interface.
• VisitValues(visitor func([]byte, interface{})): Iterates through all key-value pairs, calling the visitor function with each pair.

Testing

Run the tests to ensure the package works as expected:

$ go test ./...

Examples

Advanced Example

package main

import (
    "fmt"
    "io"
    "github.com/axkit/tinymap"
)

type resource struct {
    name string
}

func (r *resource) Close() error {
    fmt.Printf("Closing resource: %s\n", r.name)
    return nil
}

func main() {
    var tm tinymap.TinyMap

    // Add resources that implement io.Closer
    tm.Set("res1", &resource{name: "Resource1"})
    tm.Set("res2", &resource{name: "Resource2"})

    // Reset and observe resource cleanup
    tm.Reset() // Output: Closing resource: Resource1
               //         Closing resource: Resource2
}

License

This package is open-sourced under the MIT license. See the LICENSE file for details.

Documentation

Overview

The package tinymap provides functionality of map as slice of key-value pair.

The type TinyMap is copy of "userData" type from github.com/valyala/fasthttp

All credits go to Aliaksandr Valialkin, VertaMedia, Kirill Danshin, Erik Dubbelboer, FastHTTP Authors

Index

• type TinyMap
  • func (tm *TinyMap) Get(key string) interface{}
  • func (tm *TinyMap) GetBytes(key []byte) interface{}
  • func (tm *TinyMap) Reset()
  • func (tm *TinyMap) Set(key string, value interface{})
  • func (tm *TinyMap) SetBytes(key []byte, value interface{})
  • func (tm *TinyMap) VisitValues(visitor func([]byte, interface{}))

Types

type TinyMap

type TinyMap []item

TinyMap is a slice of items, acting as a map.

func (*TinyMap) Get

func (tm *TinyMap) Get(key string) interface{}

Get retrieves the value associated with a key. Returns nil if the key does not exist.

func (*TinyMap) GetBytes

func (tm *TinyMap) GetBytes(key []byte) interface{}

GetBytes retrieves the value associated with a byte slice key. It internally converts the byte slice to a string before getting the value.

func (*TinyMap) Reset

func (tm *TinyMap) Reset()

Reset clears the TinyMap by truncating it to zero length. If any value implements io.Closer, it will call the Close method before clearing.

func (*TinyMap) Set

func (tm *TinyMap) Set(key string, value interface{})

Set adds or updates a key-value pair in the TinyMap. If the key exists, its value is updated. If not, the key-value pair is added.

func (*TinyMap) SetBytes

func (tm *TinyMap) SetBytes(key []byte, value interface{})

SetBytes adds or updates a key-value pair using a byte slice as the key. It internally converts the byte slice to a string before setting the value.

func (*TinyMap) VisitValues

func (tm *TinyMap) VisitValues(visitor func([]byte, interface{}))

VisitValues applies a visitor function to all key-value pairs in the TinyMap. The visitor function receives the key as a byte slice and the value.