README
¶
box
Box is a Go package for wrapping value types.
Works similar to an interface{} and is optimized for primitives, strings, and byte slices.
Features
- Zero new allocations for wrapping primitives, strings, and []byte slices.
- Uses a 128 bit structure. Same as
interface{}on 64-bit architectures. - Allows for auto convertions between value types. No panics on assertions.
- Pretty decent performance.
Examples
// A boxed value can hold various types, just like an interface{}.
var v box.Value
// box an int
v = box.Int(123)
// unbox the value
println(v.Int())
println(v.String())
println(v.Bool())
// box a string
v = box.String("hello")
println(v.String())
// Auto conversions between types
println(box.String("123.45").Float64())
println(box.Bool(false).String())
println(box.String("hello").IsString())
// output
// 123
// 123
// true
// hello
// +1.234500e+002
// false
// true
Performance
Below are some benchmarks comparing interface{} to box.Value.
Iface*/to: Convert a value to aninterface{}.Iface*/from: Convert aninterface{}back to its original value.Box*/to: Convert a value tobox.Value.Box*/from: Convert abox.Valueback to its original value.
goos: darwin
goarch: arm64
pkg: github.com/tidwall/box
BenchmarkIfaceInt/to-10 10000000 8.921 ns/op 7 B/op 0 allocs/op
BenchmarkIfaceInt/from-10 10000000 0.6289 ns/op 0 B/op 0 allocs/op
BenchmarkBoxInt/to-10 10000000 1.334 ns/op 0 B/op 0 allocs/op
BenchmarkBoxInt/from-10 10000000 0.6823 ns/op 0 B/op 0 allocs/op
BenchmarkIfaceString/to-10 10000000 18.17 ns/op 16 B/op 1 allocs/op
BenchmarkIfaceString/from-10 10000000 0.8010 ns/op 0 B/op 0 allocs/op
BenchmarkBoxString/to-10 10000000 3.705 ns/op 0 B/op 0 allocs/op
BenchmarkBoxString/from-10 10000000 2.421 ns/op 0 B/op 0 allocs/op
BenchmarkIfaceBytes/to-10 10000000 21.62 ns/op 24 B/op 1 allocs/op
BenchmarkIfaceBytes/from-10 10000000 0.8104 ns/op 0 B/op 0 allocs/op
BenchmarkBoxBytes/to-10 10000000 2.881 ns/op 0 B/op 0 allocs/op
BenchmarkBoxBytes/from-10 10000000 2.366 ns/op 0 B/op 0 allocs/op
Documentation
¶
Index ¶
- type Value
- func Any(v any) Value
- func Bool(t bool) Value
- func Byte(x byte) Value
- func Bytes(b []byte) Value
- func CustomBits(x uint64) Value
- func Float32(x float32) Value
- func Float64(f float64) Value
- func Int(x int) Value
- func Int16(x int16) Value
- func Int32(x int32) Value
- func Int64(x int64) Value
- func Int8(x int8) Value
- func Nil() Value
- func String(s string) Value
- func StringWithTag(s string, tag uint16) Value
- func Uint(x uint) Value
- func Uint16(x uint16) Value
- func Uint32(x uint32) Value
- func Uint64(x uint64) Value
- func Uint8(x uint8) Value
- func (v Value) Any() any
- func (v Value) Bool() bool
- func (v Value) Byte() byte
- func (v Value) Bytes() []byte
- func (v Value) Float32() float32
- func (v Value) Float64() float64
- func (v Value) Int() int
- func (v Value) Int16() int16
- func (v Value) Int32() int32
- func (v Value) Int64() int64
- func (v Value) Int8() int8
- func (v Value) IsBool() bool
- func (v Value) IsBytes() bool
- func (v Value) IsCustomBits() bool
- func (v Value) IsFloat() bool
- func (v Value) IsInt() bool
- func (v Value) IsNil() bool
- func (v Value) IsNumber() bool
- func (v Value) IsString() bool
- func (v Value) IsUint() bool
- func (v Value) String() string
- func (v Value) Tag() uint16
- func (v Value) Uint() uint
- func (v Value) Uint16() uint16
- func (v Value) Uint32() uint32
- func (v Value) Uint64() uint64
- func (v Value) Uint8() uint8
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Value ¶
type Value struct {
// contains filtered or unexported fields
}
Value is a boxed value
func StringWithTag ¶
StringWithTag boxes a string value and adds a custom tag.
func (Value) Bytes ¶
Bytes returns the value as a byte slice. When the boxed value is a `[]byte` then those original bytes are returned. Otherwise, the string representation of the value is returned, which will be equivalent to `[]byte(value.String())`.
func (Value) IsCustomBits ¶
IsCustomBits returns true if the boxed value was created using box.CustomBits.
func (Value) IsFloat ¶
IsFloat returns true if the boxed value is an float-like primitive: float32, float64
func (Value) IsInt ¶
IsInt returns true if the boxed value is an int-like primitive: int, int8, int16, int32, int64, byte
func (Value) IsNumber ¶
IsNumber returns true if the boxed value is an numeric-like primitive: int, int8, int16, int32, int64, byte, uint, uint8, uint16, uint32, uint64, float32, float64
func (Value) IsUint ¶
IsUint returns true if the boxed value is an uint-like primitive: uint, uint8, uint16, uint32, uint64
Source Files