github.com/aristanetworks/gomap@v0.0.0-20240103001659-f6b0e31fb1a7/README.md (about)

     1  # gomap
     2  
     3  [![Go Reference](https://pkg.go.dev/badge/github.com/aristanetworks/gomap.svg)](https://pkg.go.dev/github.com/aristanetworks/gomap)
     4  ![Test workflow](https://github.com/aristanetworks/gomap/actions/workflows/test.yml/badge.svg)
     5  
     6  This package reimplements Go's built-in `map` as a library using
     7  generics. The major difference between `gomap.Map` and `map` is that
     8  users of `gomap.Map` must provide their own `equal` and `hash`
     9  functions.
    10  
    11  The use case for `gomap.Map` is when you want to use `map`, but can't
    12  because your key type is not
    13  [comparable](https://go.dev/ref/spec#Comparison_operators).
    14  
    15  `gomap.Map` has similar performance and most of the features of the
    16  built-in `map` including:
    17  
    18  - iteration that is not invalidated by modifications to the map
    19  
    20  - randomized hash seeds and randomized iteration order
    21  
    22  - incremental rehash
    23  
    24  - cheap best effort detection of unsafe concurrent accesses
    25  
    26  ## Requirements
    27  
    28  There is a reason that Go's built-in map uses compiler generated equal
    29  and hash functions that users don't have control over: there are
    30  subtle requirements of a hash table that when invalidated cause hard
    31  to diagnose bugs.
    32  
    33  The following requirements are the user's responsibility to follow:
    34  
    35  1. `equal(a, b)` => `hash(a) == hash(b)`
    36  
    37  1. `equal(a, a)` must be true for all values of `a`. Be careful around NaN
    38     float values. Go's built-in `map` has special cases for handling
    39     this, but `Map` does not.
    40  
    41  1. If a key in a `Map` contains references -- such as pointers, maps,
    42     or slices -- modifying the referenced data in a way that effects
    43     the result of the equal or hash functions will result in undefined
    44     behavior.
    45  
    46  1. For good performance hash functions should return uniformly
    47     distributed data across the entire 64-bits of the value.
    48  
    49  ## Stability
    50  
    51  The APIs of `Map` are subject to change at this early stage. In
    52  particular, `Iter` is likely to change depending on the outcome of
    53  this [discussion for a standard iterator
    54  interface](https://github.com/golang/go/discussions/54245).
    55  
    56  ## Implementation
    57  
    58  The implementation of `Map` is largely copy-pasted from Go's [map
    59  implementation](https://github.com/golang/go/blob/go1.18/src/runtime/map.go).
    60  It implements a chaining hash table with buckets that contain 8
    61  entries.