city

README

city

CityHash in Go. Fork of tenfyzhong/cityhash.

Note: prefer xxhash as non-cryptographic hash algorithm, this package is intended for places where CityHash is already used.

CityHash is not compatible to FarmHash, use go-farm.

go get github.com/go-faster/city

city.Hash128([]byte("hello"))

• Faster
• Supports ClickHouse hash

name            old time/op    new time/op    delta
CityHash64-32      333ns ± 2%     108ns ± 3%   -67.57%  (p=0.000 n=10+10)
CityHash128-32     347ns ± 2%     112ns ± 2%   -67.74%  (p=0.000 n=9+10)

name            old speed      new speed      delta
CityHash64-32   3.08GB/s ± 2%  9.49GB/s ± 3%  +208.40%  (p=0.000 n=10+10)
CityHash128-32  2.95GB/s ± 2%  9.14GB/s ± 2%  +209.98%  (p=0.000 n=9+10)

Benchmarks

goos: linux
goarch: amd64
pkg: github.com/go-faster/city
cpu: AMD Ryzen 9 5950X 16-Core Processor
BenchmarkClickHouse128/16     2213.98 MB/s
BenchmarkClickHouse128/64     4712.24 MB/s
BenchmarkClickHouse128/256    7561.58 MB/s
BenchmarkClickHouse128/1024  10158.98 MB/s
BenchmarkClickHouse64        10379.89 MB/s
BenchmarkCityHash32           3140.54 MB/s
BenchmarkCityHash64           9508.45 MB/s
BenchmarkCityHash128          9304.27 MB/s
BenchmarkCityHash64Small      2700.84 MB/s
BenchmarkCityHash128Small     1175.65 MB/s

Documentation

Overview

Package city implements CityHash in go.

Index

• func CH64(s []byte) uint64
• func Hash32(s []byte) uint32
• func Hash64(s []byte) uint64
• func Hash64WithSeed(s []byte, seed uint64) uint64
• func Hash64WithSeeds(s []byte, seed0, seed1 uint64) uint64
• type U128
  • func CH128(s []byte) U128
  • func CH128Seed(s []byte, seed U128) U128
  • func Hash128(s []byte) U128
  • func Hash128Seed(s []byte, seed U128) U128

Examples

• CH64
• Hash128
• Hash32
• Hash64

Functions

func CH64

func CH64(s []byte) uint64

CH64 returns ClickHouse version of Hash64.

Example

package main

import (
	"fmt"

	"github.com/go-faster/city"
)

func main() {
	// See https://github.com/ClickHouse/ClickHouse/issues/8354
	/*
		SELECT cityHash64('Moscow')
		┌─cityHash64('Moscow')─┐
		│ 12507901496292878638 │
		└──────────────────────┘
		SELECT farmHash64('Moscow')
		┌─farmHash64('Moscow')─┐
		│  5992710078453357409 │
		└──────────────────────┘
	*/
	s := []byte("Moscow")
	fmt.Print("ClickHouse: ")
	fmt.Println(city.CH64(s))
	fmt.Print("CityHash:   ")
	fmt.Println(city.Hash64(s))
}

Output:

ClickHouse: 12507901496292878638
CityHash:   5992710078453357409

func Hash32

func Hash32(s []byte) uint32

Hash32 return 32-bit hash.

Example

package main

import (
	"fmt"

	"github.com/go-faster/city"
)

func main() {
	s := []byte("hello")
	hash32 := city.Hash32(s)
	fmt.Printf("the 32-bit hash of 'hello' is: %#x\n", hash32)

}

Output:

the 32-bit hash of 'hello' is: 0x79969366

func Hash64

func Hash64(s []byte) uint64

Hash64 return a 64-bit hash.

Example

package main

import (
	"fmt"

	"github.com/go-faster/city"
)

func main() {
	s := []byte("hello")
	hash64 := city.Hash64(s)
	fmt.Printf("the 64-bit hash of 'hello' is: %#x\n", hash64)

}

Output:

the 64-bit hash of 'hello' is: 0xb48be5a931380ce8

func Hash64WithSeed

func Hash64WithSeed(s []byte, seed uint64) uint64

Hash64WithSeed return a 64-bit hash with a seed.

func Hash64WithSeeds

func Hash64WithSeeds(s []byte, seed0, seed1 uint64) uint64

Hash64WithSeeds return a 64-bit hash with two seeds.

Types

type U128

type U128 struct {
	Low  uint64 // first 64 bits
	High uint64 // last 64 bits
}

U128 is uint128.

func CH128

func CH128(s []byte) U128

CH128 returns 128-bit ClickHouse CityHash.

func CH128Seed

func CH128Seed(s []byte, seed U128) U128

CH128Seed returns 128-bit seeded ClickHouse CityHash.

func Hash128

func Hash128(s []byte) U128

Hash128 returns a 128-bit hash and are tuned for strings of at least a few hundred bytes. Depending on your compiler and hardware, it's likely faster than Hash64() on sufficiently long strings. It's slower than necessary on shorter strings, but we expect that case to be relatively unimportant.

Example

package main

import (
	"fmt"

	"github.com/go-faster/city"
)

func main() {
	fmt.Println(city.Hash128([]byte("hello")))

}

Output:

{8030732511675000650 7283604105673962311}

func Hash128Seed

func Hash128Seed(s []byte, seed U128) U128

Hash128Seed return a 128-bit hash with a seed.