unsafe

README

⭐   the project to show your appreciation. :arrow_upper_right:

Unsafe

This package is for "safely" modifying unexported fields of a struct.

Safety Considerations

Contrary to popular belief, the unsafe package is actually safe to use - provided you know what you are doing.

1. You need to ensure the newValue is the same type as the field's type.
2. You need to make sure the field is not being modifed by multiple go-routines concurrently.
3. Read Safety and Numbers — Understanding unsafe in Go
4. Read Exploring ‘unsafe’ Features in Go 1.20: A Hands-On Demo and Modifying Private Variables of a Struct in Go Using unsafe and reflect.

Example 1 - Setting a field

type Example struct {
	private string // unexported string 
}

Let's modify the Example struct's e field.

import "github.com/rocketlaunchr/unsafe"

e := Example{}

// Option 1
ptr := unsafe.SetField[string](&e, unsafe.F("private"))
*(*string)(ptr) = "New Value" // Note: If the field type is string, then ptr must be cast to *string

// Option 2
unsafe.SetField(&e, unsafe.F("private"), "New Value 2")

Example 2 - Reading a field

val := unsafe.Value[string](&e, unsafe.F("private"))

Other useful packages

• awesome-svelte - Resources for killing react
• dataframe-go - Statistics and data manipulation
• dbq - Zero boilerplate database operations for Go
• electron-alert - SweetAlert2 for Electron Applications
• go-pool - A Generic pool
• igo - A Go transpiler with cool new syntax such as fordefer (defer for for-loops)
• mysql-go - Properly cancel slow MySQL queries
• react - Build front end applications using Go
• remember-go - Cache slow database queries
• testing-go - Testing framework for unit testing

Documentation

Index

• func Alignof[ArbitraryType _ArbitraryType](x ArbitraryType) uintptr
• func F[F interface{ ... }](f F, typ ...Type) field
• func Field[F interface{ ... }](f F, typ ...Type) field
• func FindPointerFields(t reflect.Type) []pointers
• func Malloc(size uintptr, zero bool, t ...reflect.Type) unsafe.Pointer
• func New[T any](fp ...[]pointers) *T
• func SetZeros(baseAddress unsafe.Pointer, offset, size uintptr)
• func Sizeof[ArbitraryType _ArbitraryType](x ArbitraryType) uintptr
• func Slice[ArbitraryType _ArbitraryType, IntegerType _IntegerType](ptr *ArbitraryType, len IntegerType) []ArbitraryType
• func SliceData[ArbitraryType _ArbitraryType](slice []ArbitraryType) *ArbitraryType
• func String[IntegerType _IntegerType](ptr *byte, len IntegerType) string
• func StringData(str string) *byte
• func Value[T any](strct any, f field) T
• type Pointer
  • func Add[IntegerType _IntegerType](ptr Pointer, len IntegerType) Pointer
  • func SetField[T any](strct any, f field, newValue ...T) Pointer
• type Type
  • func TypeFor[T any]() Type
  • func TypeOf(i any) Type

Functions

func Alignof

func Alignof[ArbitraryType _ArbitraryType](x ArbitraryType) uintptr

Alignof

See: https://pkg.go.dev/unsafe#Alignof

func F

func F[F interface{ int | []int | string | uintptr }](f F, typ ...Type) field

F is shorthand for the Field function.

func Field

func Field[F interface{ int | []int | string | uintptr }](f F, typ ...Type) field

Field selects a field in a struct. The field can be selected by passing an integer or a (name) string. An optional type constraint can be provided as a safety precaution to ensure that the field's type is what you expected.

func FindPointerFields

func FindPointerFields(t reflect.Type) []pointers

FindPointerFields finds the offsets of all fields in a struct that contain pointers and other reference types.

func Malloc

func Malloc(size uintptr, zero bool, t ...reflect.Type) unsafe.Pointer

Malloc allocates contiguous blocks of memory without zeroing the values. All allocated memory must immediately be filled by the developer, since the pre-existing data may contain garbage.

Warning: If the returned pointer will be cast to a struct with fields that contain pointers, then provide a reflect Type for that struct. See: https://github.com/golang/go/issues/76352#issuecomment-3549768452

Example:

type Person struct {
   name  string
   age   int
   phone *int
}

ptr := Malloc(unsafe.Sizeof(Person{}), false, reflect.TypeFor[Person]())
p := *(*Person)(ptr)

func New

func New[T any](fp ...[]pointers) *T

New allocates memory for a struct. The value returned is a pointer to a newly allocated value of that type. The returned struct is not guaranteed to be the zero value.

func SetZeros

func SetZeros(baseAddress unsafe.Pointer, offset, size uintptr)

SetZeros sets memory address located at (baseAddress + offset) to zero. Size (in bytes) dictates how many contiguous locations to set to zero. No bytes are set to zero if size is 0.

func Sizeof

func Sizeof[ArbitraryType _ArbitraryType](x ArbitraryType) uintptr

Sizeof

See: https://pkg.go.dev/unsafe#Sizeof

func Slice

func Slice[ArbitraryType _ArbitraryType, IntegerType _IntegerType](ptr *ArbitraryType, len IntegerType) []ArbitraryType

Slice

See: https://pkg.go.dev/unsafe#Slice

func SliceData

func SliceData[ArbitraryType _ArbitraryType](slice []ArbitraryType) *ArbitraryType

SliceData

See: https://pkg.go.dev/unsafe#SliceData

func String

func String[IntegerType _IntegerType](ptr *byte, len IntegerType) string

String

See: https://pkg.go.dev/unsafe#String

func StringData

func StringData(str string) *byte

StringData

See: https://pkg.go.dev/unsafe#StringData

func Value

func Value[T any](strct any, f field) T

Value returns the value of the unexported field of a struct.

NOTE: This function panics if strct is not actually a struct or the field could not be found.

Types

type Pointer

type Pointer = unsafe.Pointer

Pointer

See: https://pkg.go.dev/unsafe#Pointer

func Add

func Add[IntegerType _IntegerType](ptr Pointer, len IntegerType) Pointer

Add

See: https://pkg.go.dev/unsafe#Add

func SetField

func SetField[T any](strct any, f field, newValue ...T) Pointer

SetField allows unexported fields of a struct to be modified. It returns a Pointer to the field if you wish to change the value externally instead of by passing a new value.

NOTE: This function panics if strct is not actually a struct or the field could not be found.

type Type

type Type = reflect.Type

Type

See: https://pkg.go.dev/reflect#Type

func TypeFor

func TypeFor[T any]() Type

TypeFor returns the Type that represents the type argument T.

func TypeOf

func TypeOf(i any) Type

TypeOf returns the reflection Type that represents the dynamic type of i. If i is a nil interface value, TypeOf returns nil.