value

Documentation

Overview

Package value provides runtime utilities for working with generic type parameters as payload values in bart data structures.

The package offers three main categories of utilities:

Zero-Sized Type (ZST) Detection

IsZST[V] detects whether a type parameter V is a zero-sized type (such as struct{} or [0]byte). This serves two purposes:

• Runtime validation: Fast[V] cannot work correctly with zero-sized types and must reject them. PanicOnZST enables a safety check that panics during Fast.Insert and Fast.InsertPersist operations.
• Debug output clarity: Zero-sized types carry no information in their values. Omitting them from dumps and prints reduces line noise and improves readability.

Value Equality

The Equaler[V] interface and Equal function enable custom equality logic for payload values. When V implements Equaler[V], the Equal function uses that implementation, avoiding the potentially expensive reflect.DeepEqual.

Value Cloning

The Cloner[V] interface and associated functions (CloneFnFactory, CloneVal, CopyVal) support deep copying of payload values for persistent operations. When V implements Cloner[V], bart methods like InsertPersist, DeletePersist, and UnionPersist use the Clone method to create independent copies.

This is an internal package used by the bart data structure implementation.

Index

• func CloneVal[V any](val V) V
• func CopyVal[V any](val V) V
• func Equal[V any](v1, v2 V) bool
• func IsZST[V any]() bool
• func PanicOnZST[V any]()
• type CloneFunc
  • func CloneFnFactory[V any]() CloneFunc[V]
• type Cloner
• type Equaler

Functions

func CloneVal

func CloneVal[V any](val V) V

CloneVal returns a deep clone of val by calling Clone when val implements Cloner[V]. If val does not implement Cloner[V] or the Cloner receiver is nil (val is a nil pointer), CloneVal returns val unchanged.

func CopyVal

func CopyVal[V any](val V) V

CopyVal just copies the value of any type V.

func Equal

func Equal[V any](v1, v2 V) bool

Equal compares two values of type V for equality. If V implements Equaler[V], that custom equality method is used, avoiding the potentially expensive reflect.DeepEqual. Otherwise, reflect.DeepEqual is used as a fallback.

func IsZST

func IsZST[V any]() bool

IsZST reports whether type V is a zero-sized type (ZST).

Zero-sized types such as struct{}, [0]byte, or structs/arrays with no fields occupy no memory. The Go runtime optimizes allocations of ZSTs by returning pointers to the same memory address (typically runtime.zerobase).

This function exploits that optimization: it allocates two instances of V and compares their addresses. If the addresses are equal, V must be a ZST, since distinct non-zero-sized allocations would have different addresses.

The helper escapeToHeap ensures both allocations reach the heap and prevents the compiler from proving address equality at compile time, which would invalidate the runtime check.

func PanicOnZST

func PanicOnZST[V any]()

PanicOnZST panics if V is a zero sized type. bart.Fast must reject zero-sized types as payload.

Types

type CloneFunc

type CloneFunc[V any] func(V) V

CloneFunc is a type definition for a function that takes a value of type V and returns the (possibly cloned) value of type V.

func CloneFnFactory

func CloneFnFactory[V any]() CloneFunc[V]

CloneFnFactory returns a CloneFunc. If V implements Cloner[V], the returned function should perform a deep copy using Clone(), otherwise it returns nil.

type Cloner

type Cloner[V any] interface {
	Clone() V
}

Cloner is an interface that enables deep cloning of values of type V. If a value implements Cloner[V], Table methods such as InsertPersist, ModifyPersist, DeletePersist, UnionPersist, Union and Clone will use its Clone method to perform deep copies.

type Equaler

type Equaler[V any] interface {
	Equal(other V) bool
}

Equaler is a generic interface for types that can decide their own equality logic. It can be used to override the potentially expensive default comparison with reflect.DeepEqual.