raw

README

raw

Package raw implements binary serialization of Go types.

Documentation

Overview

Package raw implements binary serialization of Go types.

Basics

Create a variable to serve as a placeholder to the typed data you want to serialize, and use New to bind an Encoder to it.

To serialize data, use WriteTo or Read.

To recover the typed value of a byte sequence previously generated by WriteTo or Read, use ReadFrom or Write.

Suported Types

Types of the following kinds are supported by Raw: bool, int8, int16, int32, int64, uint8, uint16, uint32, uint64, float32, float64, complex64, complex128, string, array of any supported type, map of any supported type, pointer to any supported type, slice of any supported type, struct with fields of any supported type.

Unsupported Types

Types of the following kinds are not supported: int, uint, uintptr (their size is platform dependent); unsafe pointer (not meaningful across systems); chan, func, interface (language plumbing).

Remarks

The placeholder variable (see New) is the access point to typed data for a given Encoder. The Encoder is eternally bound to its placeholder variable.

Structs must have all fields exported.

Recovery of array, map, ptr or slice always creates new values (there is no reuse of allocated resources).

A nil map or slice is serialized as if it was an empty map or slice.

Length of slices and maps is silently assumed to fit in uint32 during serialization.

Caveats

Serialized data does not contain type information. It's up to the programmer to ensure that recovery is performed by an Encoder created after the same type kind of the Encoder that generated the serialized data. One way of achieving this is to compare Encoder's signatures (see Signature).

Whish List

Document syntax of serialized data.

Example

package main

import (
	"bytes"
	"fmt"
	"github.com/coolparadox/go/encoding/raw"
	"math/rand"
	"time"
)

func init() {
	rand.Seed(time.Now().UnixNano())
}

func main() {

	// Let's say we want to serialize a slice of strings
	var myData []string

	// Bind an encoder to the placeholder variable
	encoder, err := raw.New(&myData)
	if err != nil {
		panic("failed to create encoder: " + err.Error())
	}
	fmt.Printf("encoder signature: %s\n", encoder.Signature())

	// Let's populate placeholder for demonstration
	myData = make([]string, 2)
	myData[0] = "hello"
	myData[1] = "world"
	fmt.Printf("original data: %v\n", myData)

	// Serialize placeholder contents
	var buf bytes.Buffer
	_, err = encoder.WriteTo(&buf)
	if err != nil {
		panic("failed to marshal: " + err.Error())
	}

	// Mess up with placeholder for demonstrating recovery
	myData = make([]string, 3)
	myData[0] = "goodbye"
	myData[1] = "cruel"
	myData[2] = "world"

	// Recover data from serial representation
	_, err = encoder.ReadFrom(&buf)
	if err != nil {
		panic("failed to unmarshal: " + err.Error())
	}
	fmt.Printf("recovered data: %v\n", myData)

}

Output:

encoder signature: []string
original data: [hello world]
recovered data: [hello world]

Index

• type Encoder
  • func New(placeholder interface{}) (Encoder, error)

Examples

• Package

Types

type Encoder

type Encoder interface {
	Signature() string
	io.WriterTo
	io.ReaderFrom
	io.ReadWriter
}

Encoder is the interface that can transform typed data to a sequence of bytes and vice-versa.

Signature answers a textual representation of the type kind of the placeholder variable (see New).

WriteTo writes to an io.Writer a sequence of bytes representing the contents of the placeholder variable. Returns the number of bytes written.

ReadFrom reads from an io.Reader a sequence of bytes previously generated by WriteTo or Read, and populates the placeholder variable with recovered data. Returns the number of bytes read.

Read writes to a byte slice a sequence of bytes representing the contents of the placeholder variable. If the sequence does not fit into the slice, io.ErrShortBuffer is returned. Returns the number of bytes written.

Write reads from a byte slice a sequence of bytes previously generated by Read or WriteTo, ans populates the placeholder variable with recovered data. Returns the number of bytes read.

func New

func New(placeholder interface{}) (Encoder, error)

New creates an Encoder for a type.

It requires a pointer to a variable of any supported type (see Supported Types). The resulting Encoder uses this variable as a placeholder of typed data.

Returns an Encoder bound to the placeholder variable.