city

README

city

CityHash in Go. Fork of tenfyzhong/cityhash.

Note that CityHash is not compatible to FarmHash, use go-farm for it.

go get github.com/go-faster/city

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

• Faster
• Supports ClickHouse hash

name            old time/op    new time/op    delta
CityHash32-32      298ns ± 1%     295ns ± 2%      ~     (p=0.421 n=5+5)
CityHash64-32      336ns ± 0%     145ns ± 2%   -56.92%  (p=0.008 n=5+5)
CityHash128-32     353ns ± 0%     149ns ± 2%   -57.81%  (p=0.008 n=5+5)

name            old speed      new speed      delta
CityHash32-32   3.44GB/s ± 1%  3.47GB/s ± 2%      ~     (p=0.421 n=5+5)
CityHash64-32   3.04GB/s ± 0%  7.07GB/s ± 2%  +132.16%  (p=0.008 n=5+5)
CityHash128-32  2.90GB/s ± 0%  6.87GB/s ± 2%  +137.06%  (p=0.008 n=5+5)

Benchmarks

goos: linux
goarch: amd64
pkg: github.com/go-faster/city
cpu: AMD Ryzen 9 5950X 16-Core Processor            
BenchmarkClickHouse128-32     137.7 ns/op  7437.19 MB/s  0 B/op  0 allocs/op
BenchmarkClickHouse64-32      131.5 ns/op  7786.84 MB/s  0 B/op  0 allocs/op
BenchmarkCityHash32-32        333.9 ns/op  3066.73 MB/s  0 B/op  0 allocs/op
BenchmarkCityHash64-32        141.9 ns/op  7216.10 MB/s  0 B/op  0 allocs/op
BenchmarkCityHash128-32       148.5 ns/op  6897.44 MB/s  0 B/op  0 allocs/op
BenchmarkCityHash64Small-32   3.659 ns/op  2732.82 MB/s  0 B/op  0 allocs/op
BenchmarkCityHash128Small-32  9.103 ns/op  1098.57 MB/s  0 B/op  0 allocs/op
PASS
ok      github.com/go-faster/city       12.018s

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
  • func (u U128) Append(buf []byte) []byte
  • func (u U128) Arr() (v [16]byte)
  • func (u U128) Bytes() []byte
  • func (u U128) Put(b []byte)
  • func (u *U128) Set(b []byte)
  • func (u U128) String() string

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: 0x%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: 0x%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 32 bits
	High uint64 // last 32 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:

6f72e4abb491a74a65148f580b45f347

func Hash128Seed

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

Hash128Seed return a 128-bit hash with a seed.

func (U128) Append

func (u U128) Append(buf []byte) []byte

Append appends uint128 big value to buf in big endian.

Append is much faster that appending Arr result.

func (U128) Arr

func (u U128) Arr() (v [16]byte)

Arr returns byte array that represents uint128 value of U128 in big endian.

func (U128) Bytes

func (u U128) Bytes() []byte

Bytes returns new byte slice for U128.

func (U128) Put

func (u U128) Put(b []byte)

Put U128 to buffer.

func (*U128) Set

func (u *U128) Set(b []byte)

Set U128 from byte slice.

func (U128) String

func (u U128) String() string