go-hep.org/x/hep@v0.38.1/groot/rbytes/rbytes.go (about)

     1  // Copyright ©2017 The go-hep Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package rbytes contains the definitions of types useful for
     6  // serializing and deserializing ROOT data buffers.
     7  //
     8  // rbytes also defines the interfaces to interact with ROOT's metadata classes
     9  // such as StreamerInfo and StreamerElements.
    10  package rbytes // import "go-hep.org/x/hep/groot/rbytes"
    11  
    12  import (
    13  	"fmt"
    14  
    15  	"go-hep.org/x/hep/groot/rmeta"
    16  	"go-hep.org/x/hep/groot/root"
    17  )
    18  
    19  // Header represents a type header in a ROOT buffer.
    20  type Header struct {
    21  	Name string // name of the type being guarded by this header.
    22  	Vers int16  // version of the type being guarded by this header.
    23  	Pos  int64  // position of the type in the ROOT buffer.
    24  	Len  int32  // length of the value in the ROOT buffer.
    25  
    26  	MemberWise bool // whether the value has been written member-wise.
    27  }
    28  
    29  // RVersioner is the interface implemented by an object that
    30  // can tell the ROOT system what is its current version.
    31  type RVersioner interface {
    32  	RVersion() int16
    33  }
    34  
    35  // StreamerInfo describes a ROOT Streamer.
    36  type StreamerInfo interface {
    37  	root.Named
    38  
    39  	CheckSum() int
    40  	ClassVersion() int
    41  	Elements() []StreamerElement
    42  
    43  	// BuildStreamers builds the r/w streamers.
    44  	BuildStreamers() error
    45  
    46  	NewDecoder(kind StreamKind, r *RBuffer) (Decoder, error)
    47  	NewEncoder(kind StreamKind, w *WBuffer) (Encoder, error)
    48  
    49  	NewRStreamer(kind StreamKind) (RStreamer, error)
    50  	NewWStreamer(kind StreamKind) (WStreamer, error)
    51  }
    52  
    53  // StreamKind describes whether a composite ROOT value was encoded
    54  // member-wise or object-wise.
    55  type StreamKind byte
    56  
    57  func (k StreamKind) String() string {
    58  	switch k {
    59  	case ObjectWise:
    60  		return "object-wise"
    61  	case MemberWise:
    62  		return "member-wise"
    63  	}
    64  	return fmt.Sprintf("0x%x", byte(k))
    65  }
    66  
    67  const (
    68  	ObjectWise StreamKind = iota
    69  	MemberWise
    70  )
    71  
    72  // StreamerElement describes a ROOT StreamerElement
    73  type StreamerElement interface {
    74  	root.Named
    75  
    76  	ArrayDim() int
    77  	ArrayDims() []int32
    78  	ArrayLen() int
    79  	Type() rmeta.Enum
    80  	Offset() uintptr
    81  	Size() uintptr
    82  	TypeName() string
    83  	XMin() float64
    84  	XMax() float64
    85  	Factor() float64
    86  }
    87  
    88  // Decoder is the interface that wraps the basic DecodeROOT method.
    89  type Decoder interface {
    90  	DecodeROOT(ptr any) error
    91  }
    92  
    93  // Encoder is the interface that wraps the basic EncodeROOT method.
    94  type Encoder interface {
    95  	EncodeROOT(ptr any) error
    96  }
    97  
    98  // StreamerInfoContext defines the protocol to retrieve a ROOT StreamerInfo
    99  // metadata type by name.
   100  //
   101  // Implementations should make sure the protocol is goroutine safe.
   102  type StreamerInfoContext interface {
   103  	// StreamerInfo returns the named StreamerInfo.
   104  	// If version is negative, the latest version should be returned.
   105  	StreamerInfo(name string, version int) (StreamerInfo, error)
   106  }
   107  
   108  // Unmarshaler is the interface implemented by an object that can
   109  // unmarshal itself from a ROOT buffer
   110  type Unmarshaler interface {
   111  	UnmarshalROOT(r *RBuffer) error
   112  }
   113  
   114  // Marshaler is the interface implemented by an object that can
   115  // marshal itself into a ROOT buffer
   116  type Marshaler interface {
   117  	MarshalROOT(w *WBuffer) (int, error)
   118  }
   119  
   120  // WStreamer is the interface implemented by types that can stream themselves
   121  // to a ROOT buffer.
   122  type WStreamer interface {
   123  	WStreamROOT(*WBuffer) error
   124  }
   125  
   126  // RStreamer is the interface implemented by types that can stream themselves
   127  // from a ROOT buffer.
   128  type RStreamer interface {
   129  	RStreamROOT(*RBuffer) error
   130  }
   131  
   132  // Streamer is the interface implemented by types that can stream themselves
   133  // to and from a ROOT buffer.
   134  type Streamer interface {
   135  	WStreamer
   136  	RStreamer
   137  }
   138  
   139  // Binder wraps the Bind method.
   140  type Binder interface {
   141  	Bind(ptr any) error
   142  }
   143  
   144  // Counter wraps the Count method.
   145  type Counter interface {
   146  	Count(f func() int) error
   147  }
   148  
   149  const (
   150  	BypassStreamer                  uint32 = 1 << 12
   151  	CannotHandleMemberWiseStreaming uint32 = 1 << 17
   152  )
   153  
   154  // Member is a ROOT member of a ROOT class.
   155  type Member struct {
   156  	Name  string
   157  	Value any
   158  }
   159  
   160  // RSlicer wraps the RMembers method.
   161  type RSlicer interface {
   162  	// RMembers returns the list of (pointers to) members of a given ROOT value.
   163  	RMembers() []Member
   164  }