byteconv

README

byteconv

byteconv is a high-performance, zero-allocation Go library for parsing basic data types directly from byte slices ([]byte).

This project is a heavily modified, zero-allocation, byte-slice-based derivative of the Go standard library's strconv package. Original strconv code is Copyright (c) 2009 The Go Authors.

Overview

Parsing data types from []byte payloads (such as those returned by network reads, database drivers, or file I/O) typically requires first casting the slice to a string before passing it to strconv. This cast results in memory allocations and overhead that can become a bottleneck in high-throughput applications.

byteconv solves this problem by providing a 1-to-1 equivalent of the standard strconv package that operates natively on []byte. It eliminates string allocations entirely while remaining highly optimized.

Note: byteconv only implements []byte -> x parsing functions (like ParseFloat, Atoi). It does not reimplement the x -> []byte formatting functions. The standard library's strconv already supplies zero-allocation byte-append functions (like strconv.AppendFloat, strconv.AppendInt). It is highly recommended to continue using those standard library functions for formatting to byte slices.

Installation

go get github.com/coalaura/byteconv

Usage

package main

import (
	"fmt"
	"github.com/coalaura/byteconv"
)

func main() {
	data := []byte("12345")
	
	// Parse integers directly from []byte
	num, err := byteconv.Atoi(data)
	if err != nil {
		panic(err)
	}
	fmt.Println(num)

	// Parse floats natively
	floatData := []byte("3.14159")
	f, err := byteconv.ParseFloat(floatData, 64)
	if err != nil {
		panic(err)
	}
	fmt.Println(f)
	
	// Parse booleans
	boolData := []byte("true")
	b, err := byteconv.ParseBool(boolData)
	if err != nil {
	    panic(err)
	}
	fmt.Println(b)
}

Performance

The entire parsing surface (e.g., Atoi, ParseInt, ParseFloat, ParseBool) achieves 0 allocs/op and executes in just a few nanoseconds, matching or outperforming standard library equivalents without requiring string conversions.

Because byteconv skips the string(bytes) cast, it effectively saves allocations on dynamically retrieved byte slices and avoids overhead. Below is a gnuplot showcasing the performance difference between standard lib casting and natively parsing bytes with byteconv.

Ran on AMD Ryzen 9 9950X3D 16-Core Processor

License

This source code is governed by a BSD-style license that can be found in the LICENSE file. Original logic derived from The Go Authors.

Documentation

Overview

Package byteconv implements conversions to and from byte representations of basic data types. It aims to be a zero-allocation, highly performant 1-to-1 equivalent of the standard library's strconv package, but operates directly on byte slices ([]byte) to avoid string conversions and memory allocations.

Index

• Constants
• func Atoi(s []byte) (int, error)
• func ParseBool(in []byte) (bool, error)
• func ParseComplex(s []byte, bitSize int) (complex128, error)
• func ParseFloat(s []byte, bitSize int) (float64, error)
• func ParseInt(s []byte, base int, bitSize int) (i int64, err error)
• func ParseUint(s []byte, base int, bitSize int) (uint64, error)
• type Error
  • func (e Error) Error() string

Constants

const IntSize = intSize

IntSize is the size in bits of an int or uint value.

Functions

func Atoi

func Atoi(s []byte) (int, error)

Atoi is equivalent to ParseInt(s, 10, 0), converted to type int.

func ParseBool

func ParseBool(in []byte) (bool, error)

ParseBool returns the boolean value represented by the []byte. It accepts 1, t, T, TRUE, true, True, 0, f, F, FALSE, false, False. Any other value returns an error.

func ParseComplex

func ParseComplex(s []byte, bitSize int) (complex128, error)

ParseComplex converts the []byte s to a complex number with the precision specified by bitSize: 64 for complex64, or 128 for complex128. When bitSize=64, the result still has type complex128, but it will be convertible to complex64 without changing its value.

func ParseFloat

func ParseFloat(s []byte, bitSize int) (float64, error)

func ParseInt

func ParseInt(s []byte, base int, bitSize int) (i int64, err error)

ParseInt interprets a byte slice s in the given base (0, 2 to 36) and bit size (0 to 64) and returns the corresponding value i.

func ParseUint

func ParseUint(s []byte, base int, bitSize int) (uint64, error)

ParseUint is like ParseInt but for unsigned numbers. A sign prefix is not permitted.

Types

type Error

type Error int

Error represents an error during a conversion.

const (

	// ErrRange indicates that a value is out of range for the target type.
	ErrRange Error
	// ErrSyntax indicates that a value does not have the right syntax for the target type.
	ErrSyntax
	// ErrBase indicates that a base is invalid.
	ErrBase
	// ErrBitSize indicates that a bit size is invalid.
	ErrBitSize
)

func (Error) Error

func (e Error) Error() string