dts

README

dts-go

dts-go provides DTM support for the mus-go serializer (DTS stands for Data Type Metadata Support).

dts-go is particularly useful when deserializing data with an unpredictable type. This could include completely different types, such as Foo and Bar, or different versions of the same data, such as FooV1 and FooV2.

It encodes a DTM (which is simply a number) along with the data itself, allowing one type to be easily distinguished from another. Let’s see how:

package main

import (
  "math/rand"

  com "github.com/mus-format/common-go"
  dts "github.com/mus-format/dts-go"
  "github.com/mus-format/mus-go"
)
  
type Foo struct{...}
type Bar struct{..}

// DTM (Data Type Metadata) definitions.
const (
  FooDTM com.DTM = iota + 1
  BarDTM
)

// Serializers.
var (
  FooMUS = ...
  BarMUS = ...
)

// DTS (Data Type metadata Support) definitions.
var (
  FooDTS = dts.New[Foo](FooDTM, FooMUS)
  BarDTS = dts.New[Bar](BarDTM, BarMUS)
)

func main() {
  // Make a random data and Unmarshal DTM.
  bs := randomData()
  dtm, n, err := dts.DTMSer.Unmarshal(bs)
  if err != nil {
    panic(err)
  }

  // Deserialize and process data depending on the DTM.
  switch dtm {
  case FooDTM:
    foo, _, err := FooDTS.UnmarshalData(bs[n:])
    if err != nil {
      panic(err)
    }
    // process foo ...
    fmt.Println(foo)
  case BarDTM:
    bar, _, err := BarDTS.UnmarshalData(bs[n:])
    if err != nil {
      panic(err)
    }
    // process bar ...
    fmt.Println(bar)
  default:
    panic(fmt.Sprintf("unexpected %v DTM", dtm))
  }
}
}

func randomData() (bs []byte) {...}

A full example can be found at mus-examples-go

Documentation

Index

• Variables
• type DTS
  • func New[T any](dtm com.DTM, ser mus.Serializer[T]) DTS[T]
  • func (d DTS[T]) DTM() com.DTM
  • func (d DTS[T]) Marshal(t T, bs []byte) (n int)
  • func (d DTS[T]) Size(t T) (size int)
  • func (d DTS[T]) Skip(bs []byte) (n int, err error)
  • func (d DTS[T]) SkipData(bs []byte) (n int, err error)
  • func (d DTS[T]) Unmarshal(bs []byte) (t T, n int, err error)
  • func (d DTS[T]) UnmarshalData(bs []byte) (t T, n int, err error)

Variables

var DTMSer = dtmSer{}

var ErrWrongDTM = errors.New("wrong data type metadata")

ErrWrongDTM happens when DTS tries to unmarshal data with wrong DTM.

Types

type DTS

type DTS[T any] struct {
	// contains filtered or unexported fields
}

DTM implements the mus.Serializer interface and provides DTM support for the mus-go serializer. It helps to serializer DTM + data.

func New

func New[T any](dtm com.DTM, ser mus.Serializer[T]) DTS[T]

New creates a new DTS.

func (DTS[T]) DTM

func (d DTS[T]) DTM() com.DTM

DTM returns the initialization value.

func (DTS[T]) Marshal

func (d DTS[T]) Marshal(t T, bs []byte) (n int)

Marshal marshals DTM + data.

func (DTS[T]) Size

func (d DTS[T]) Size(t T) (size int)

Size calculates the size of the DTM + data.

func (DTS[T]) Skip

func (d DTS[T]) Skip(bs []byte) (n int, err error)

Skip skips DTM + data.

Returns ErrWrongDTM if the unmarshalled DTM differs from the d.DTM().

func (DTS[T]) SkipData

func (d DTS[T]) SkipData(bs []byte) (n int, err error)

SkipData skips only data.

func (DTS[T]) Unmarshal

func (d DTS[T]) Unmarshal(bs []byte) (t T, n int, err error)

Unmarshal unmarshals DTM + data.

Returns ErrWrongDTM if the unmarshalled DTM differs from the d.DTM().

func (DTS[T]) UnmarshalData

func (d DTS[T]) UnmarshalData(bs []byte) (t T, n int, err error)

UnmarshalData unmarshals only data.