raw

README

== Disclaimer ==
The RAW package circumvents and subverts Go's type system. As such it should be used with extreme caution and only
when absolutely necessary. Incautious use can and will lead to memory corruption. As such no warranty can be provided
as to its suitability or fitness for purpose.

Just to reiterate: MISUSE WILL RESULT IN MEMORY CORRUPTION.


== License ==

RAW is dual-licensed.

The library can be included in your project as "Random Access Woe" under the BSD-derived license in LICENSE.

"Read it And Weep" is the closed-source variant of the library. It is in all particulars identical to the open-source
version but requires a commercial usage license and in the process hides your shame for abusing Go in this manner.
Further details of commercial license costs are available from the author on request.


== About ==

RAW is a high-level interface to Go's unsafe and reflection packages, designed to ease both generic programming and
low-level memory access.

RAW allows any type with identifiable contiguous memory allocation to be converted to a byte slice which can then
be manipulated using many of the standard IO interfaces provided by the core library. This is very unsafe but for
certain system programming tasks can be very useful. In particular it facilitates the sharing of memory buffers with
language runtimes and any number of related tricks such as polymorphic variables, mixed-content arrays and binary
data marshalling.

Documentation is currently sparse but will improve over time. I have tried to keep nomenclature clear to assist with
figuring our how the library should be used and there are also extensive tests which demonstrate all of the library
types and their methods in use.


== History ==

The RAW package began life as a research spike of the GoLightly virtual machine project and was originally to be called
either "Dangerous" or "Deadly" to reflect the unpleasant consequences of misuse. A friend suggested "Random Access Woe"
and the name stuck.

Documentation

Index

• Variables
• func BoolSlice(i interface{}) []bool
• func ByteCopy(d interface{}, s interface{})
• func ByteSlice(i interface{}) []byte
• func Complex64Slice(i interface{}) (r []complex64)
• func Complex128Slice(i interface{}) []complex128
• func DataAddress(b []byte) (p unsafe.Pointer)
• func DereferenceAll(v interface{}) interface{}
• func FailIfNotCopyable(f Fatal, v interface{})
• func FailOnAddressMismatch(f Fatal, slice unsafe.Pointer, buf []byte)
• func FailOnBadBufferSize(f Fatal, good_length, good_capacity bool)
• func FailOnHeaderMismatch(f Fatal, slice unsafe.Pointer, buf []byte)
• func Float32Slice(i interface{}) (r []float32)
• func Float64Slice(i interface{}) (r []float64)
• func Int8Slice(i interface{}) []int8
• func Int16Slice(i interface{}) []int16
• func Int32Slice(i interface{}) (r []int32)
• func Int64Slice(i interface{}) (r []int64)
• func IntSlice(i interface{}) []int
• func InterfaceSlice(i interface{}) []interface{}
• func MakeAddressable(v reflect.Value) reflect.Value
• func NewPoint(x, y, z int32) *point
• func PointerSlice(i interface{}) []unsafe.Pointer
• func Reslice(slice interface{}, sliceType reflect.Type) interface{}
• func ResliceOf(t reflect.Type, i interface{}) interface{}
• func Scale(oldHeader *reflect.SliceHeader, oldElementSize, newElementSize uintptr) (h *reflect.SliceHeader)
• func ShallowCopy(v interface{}) (r interface{})
• func SliceHeader(i interface{}) (Header *reflect.SliceHeader, ElementSize, ElementAlignment int)
• func Uint8Slice(i interface{}) []uint8
• func Uint16Slice(i interface{}) []uint16
• func Uint32Slice(i interface{}) (r []uint32)
• func Uint64Slice(i interface{}) (r []uint64)
• func UintSlice(i interface{}) []uint
• func UintptrSlice(i interface{}) []uintptr
• func ValidateNumericByteSlice(f Fatal, value interface{})
• type Fatal
• type MemoryBlock

Variables

var BOOLEAN = reflect.TypeOf(true)

var BYTE = reflect.TypeOf(byte(0))

var COMPLEX128 = reflect.TypeOf(complex128(0))

var COMPLEX64 = reflect.TypeOf(complex64(0))

var FLOAT32 = reflect.TypeOf(float32(0.0))

var FLOAT64 = reflect.TypeOf(float64(0.0))

var INT = reflect.TypeOf(int(0))

var INT16 = reflect.TypeOf(int16(0))

var INT32 = reflect.TypeOf(int32(0))

var INT64 = reflect.TypeOf(int64(0))

var INT8 = reflect.TypeOf(int8(0))

var INTERFACE = reflect.TypeOf(_a)

var POINTER = reflect.TypeOf(unsafe.Pointer(&_a))

var UINT = reflect.TypeOf(uint(0))

var UINT16 = reflect.TypeOf(uint16(0))

var UINT32 = reflect.TypeOf(uint32(0))

var UINT64 = reflect.TypeOf(uint64(0))

var UINT8 = reflect.TypeOf(uint8(0))

var UINTPTR = reflect.TypeOf(uintptr(0))

Functions

func BoolSlice

func BoolSlice(i interface{}) []bool

func ByteCopy

func ByteCopy(d interface{}, s interface{})

func ByteSlice

func ByteSlice(i interface{}) []byte

func Complex64Slice

func Complex64Slice(i interface{}) (r []complex64)

func Complex128Slice

func Complex128Slice(i interface{}) []complex128

func DataAddress

func DataAddress(b []byte) (p unsafe.Pointer)

func DereferenceAll

func DereferenceAll(v interface{}) interface{}

Repeatedly uses *reflect.Indirect* to step through a series of *reflect.Ptr* values and arrive at the concrete value they point to.

func FailIfNotCopyable

func FailIfNotCopyable(f Fatal, v interface{})

func FailOnAddressMismatch

func FailOnAddressMismatch(f Fatal, slice unsafe.Pointer, buf []byte)

func FailOnBadBufferSize

func FailOnBadBufferSize(f Fatal, good_length, good_capacity bool)

func FailOnHeaderMismatch

func FailOnHeaderMismatch(f Fatal, slice unsafe.Pointer, buf []byte)

func Float32Slice

func Float32Slice(i interface{}) (r []float32)

func Float64Slice

func Float64Slice(i interface{}) (r []float64)

func Int8Slice

func Int8Slice(i interface{}) []int8

func Int16Slice

func Int16Slice(i interface{}) []int16

func Int32Slice

func Int32Slice(i interface{}) (r []int32)

func Int64Slice

func Int64Slice(i interface{}) (r []int64)

func IntSlice

func IntSlice(i interface{}) []int

func InterfaceSlice

func InterfaceSlice(i interface{}) []interface{}

func MakeAddressable

func MakeAddressable(v reflect.Value) reflect.Value

func NewPoint

func NewPoint(x, y, z int32) *point

func PointerSlice

func PointerSlice(i interface{}) []unsafe.Pointer

func Reslice

func Reslice(slice interface{}, sliceType reflect.Type) interface{}

func ResliceOf

func ResliceOf(t reflect.Type, i interface{}) interface{}

func Scale

func Scale(oldHeader *reflect.SliceHeader, oldElementSize, newElementSize uintptr) (h *reflect.SliceHeader)

func ShallowCopy

func ShallowCopy(v interface{}) (r interface{})

Uses reflection to create a *shallow* copy of an existing value. This will only work if the Type of value being copied is *settable* according to the language specification.

func SliceHeader

func SliceHeader(i interface{}) (Header *reflect.SliceHeader, ElementSize, ElementAlignment int)

func Uint8Slice

func Uint8Slice(i interface{}) []uint8

func Uint16Slice

func Uint16Slice(i interface{}) []uint16

func Uint32Slice

func Uint32Slice(i interface{}) (r []uint32)

func Uint64Slice

func Uint64Slice(i interface{}) (r []uint64)

func UintSlice

func UintSlice(i interface{}) []uint

func UintptrSlice

func UintptrSlice(i interface{}) []uintptr

func ValidateNumericByteSlice

func ValidateNumericByteSlice(f Fatal, value interface{})

Types

type Fatal

type Fatal interface {
	Fatal(...interface{})
	Fatalf(string, ...interface{})
}

type MemoryBlock

type MemoryBlock interface {
	ByteSlice() []byte
}

A Buffered object can present itself as a byteslice. This byteslice can then be manipulated directly to modify the contents of memory. Use with extreme caution.