xhex

README

xhex

xhex provides high-performance hexadecimal encoding/decoding for Go. On AVX2-capable x86_64 CPUs, it uses a SIMD fast path and falls back to a portable implementation otherwise.

Highlights

• API-compatible behavior with Go's encoding/hex for byte-slice encode/decode use cases.
• Runtime CPU feature detection; AVX2 acceleration is enabled automatically when available.
• Significant throughput gains in large-buffer workloads.

Usage

package main

import "github.com/templexxx/xhex"

func main() {
	src := []byte("xhex")
	enc := make([]byte, len(src)*2)
	xhex.Encode(enc, src)

	dec := make([]byte, len(enc)/2)
	_ = xhex.Decode(dec, enc)
}

Benchmark (vs encoding/hex)

Typical results:

Compare with standard lib:
benchmark                  old ns/op     new ns/op     delta
BenchmarkEncode/16-8       30.7          5.86          -80.91%
BenchmarkEncode/24-8       43.4          17.8          -58.99%
BenchmarkEncode/1024-8     1793          62.8          -96.50%

benchmark                  old MB/s     new MB/s     speedup
BenchmarkEncode/16-8       520.44       2732.67      5.25x
BenchmarkEncode/24-8       552.44       1349.15      2.44x
BenchmarkEncode/1024-8     571.10       16298.50     28.54x

benchmark                  old ns/op     new ns/op     delta
BenchmarkDecode/32-8       59.8          10.4          -82.61%
BenchmarkDecode/48-8       87.5          35.3          -59.66%
BenchmarkDecode/2048-8     3634          182           -94.99%

benchmark                  old MB/s     new MB/s     speedup
BenchmarkDecode/32-8       534.90       3074.74      5.75x
BenchmarkDecode/48-8       548.75       1359.05      2.48x
BenchmarkDecode/2048-8     563.56       11227.56     19.92x

Measured with project benchmarks under default settings. Actual speedup depends on CPU model, Go version, and input size distribution.

Documentation

Overview

Package xhex implements high-performance hexadecimal encoding and decoding. On AVX2-capable x86_64 CPUs, xhex enables SIMD acceleration at runtime.

Index

• Variables
• func Decode(dst, src []byte) error
• func Encode(dst, src []byte)
• type InvalidByteError
  • func (e InvalidByteError) Error() string

Variables

var ErrLength = errors.New("encoding/hex: odd length hex string")

ErrLength reports an attempt to decode an odd-length input using Decode or DecodeString. The stream-based Decoder returns io.ErrUnexpectedEOF instead of ErrLength.

Functions

func Decode

func Decode(dst, src []byte) error

Decode decodes src into len(src)/2 bytes.

Decode expects that src contains only hexadecimal characters and that src has even length.

func Encode

func Encode(dst, src []byte)

Encode encodes src into (2 * len(src)) bytes of dst.

Caller requirements:

• dst must have length >= 2*len(src)
• src may be empty

Types

type InvalidByteError

type InvalidByteError byte

InvalidByteError values describe errors resulting from an invalid byte in a hex string.

func (InvalidByteError) Error

func (e InvalidByteError) Error() string