var Errorerror

funcBool¶

func Bool(vbool) *bool

Bool stores v in a new bool value and returns a pointer to it.

funcCheckInitialized¶

func CheckInitialized(mMessage)error

CheckInitialized returns an error if any required fields in m are not set.

funcClearExtension¶

func ClearExtension(mMessage, xtprotoreflect.ExtensionType)

ClearExtension clears an extension field such that subsequentHasExtension calls return false.It panics if m is invalid or if xt does not extend m.

funcCloneOf¶added inv1.36.6

func CloneOf[MMessage](m M) M

CloneOf returns a deep copy of m. If the top-level message is invalid,it returns an invalid message as well.

funcEqual¶

func Equal(x, yMessage)bool

Equal reports whether two messages are equal,by recursively comparing the fields of the message.

• Bytes fields are equal if they contain identical bytes.Empty bytes (regardless of nil-ness) are considered equal.

• Floating-point fields are equal if they contain the same value.Unlike the == operator, a NaN is equal to another NaN.

• Other scalar fields are equal if they contain the same value.

• Message fields are equal if they havethe same set of populated known and extension field values, andthe same set of unknown fields values.

• Lists are equal if they are the same length andeach corresponding element is equal.

• Maps are equal if they have the same set of keys andthe corresponding value for each key is equal.

An invalid message is not equal to a valid message.An invalid message is only equal to another invalid message of thesame type. An invalid message often corresponds to a nil pointerof the concrete message type. For example, (*pb.M)(nil) is not equalto &pb.M{}.If two valid messages marshal to the same bytes under deterministicserialization, then Equal is guaranteed to report true.

funcFloat32¶

func Float32(vfloat32) *float32

Float32 stores v in a new float32 value and returns a pointer to it.

funcFloat64¶

func Float64(vfloat64) *float64

Float64 stores v in a new float64 value and returns a pointer to it.

funcGetExtension¶

func GetExtension(mMessage, xtprotoreflect.ExtensionType)any

GetExtension retrieves the value for an extension field.If the field is unpopulated, it returns the default value forscalars and an immutable, empty value for lists or messages.It panics if xt does not extend m.

The type of the value is dependent on the field type of the extension.For extensions generated by protoc-gen-go, the Go type is as follows:

╔═══════════════════╤═════════════════════════╗║ Go type           │ Protobuf kind           ║╠═══════════════════╪═════════════════════════╣║ bool              │ bool                    ║║ int32             │ int32, sint32, sfixed32 ║║ int64             │ int64, sint64, sfixed64 ║║ uint32            │ uint32, fixed32         ║║ uint64            │ uint64, fixed64         ║║ float32           │ float                   ║║ float64           │ double                  ║║ string            │ string                  ║║ []byte            │ bytes                   ║║ protoreflect.Enum │ enum                    ║║ proto.Message     │ message, group          ║╚═══════════════════╧═════════════════════════╝

The protoreflect.Enum and proto.Message types are the concrete Go typeassociated with the named enum or message. Repeated fields are representedusing a Go slice of the base element type.

If a generated extension descriptor variable is directly passed toGetExtension, then the call should be followed immediately by atype assertion to the expected output value. For example:

mm := proto.GetExtension(m, foopb.E_MyExtension).(*foopb.MyMessage)

This pattern enables static analysis tools to verify that the asserted typematches the Go type associated with the extension field andalso enables a possible future migration to a type-safe extension API.

Since singular messages are the most common extension type, the pattern ofcalling HasExtension followed by GetExtension may be simplified to:

if mm := proto.GetExtension(m, foopb.E_MyExtension).(*foopb.MyMessage); mm != nil {    ... // make use of mm}

The mm variable is non-nil if and only if HasExtension reports true.

package mainimport ("fmt""google.golang.org/protobuf/proto"extpb "google.golang.org/protobuf/internal/testprotos/examples/ext")func concertDetails() *extpb.Concert {concert := &extpb.Concert{}concert.SetHeadlinerName("Go Protobuf Acapella Band")proto.SetExtension(concert, extpb.E_PromoId, int32(2342))return concert}func main() {concert := concertDetails( /* req.ConcertID */ )fmt.Printf("finding backend server for live stream %q\n", concert.GetHeadlinerName())if proto.HasExtension(concert, extpb.E_PromoId) {promoId := proto.GetExtension(concert, extpb.E_PromoId).(int32)fmt.Printf("routing stream to high-priority backend (concert is part of promo %v)\n", promoId)} else {fmt.Printf("routing stream to default backend\n")}}

Output:finding backend server for live stream "Go Protobuf Acapella Band"routing stream to high-priority backend (concert is part of promo 2342)

funcHasExtension¶

func HasExtension(mMessage, xtprotoreflect.ExtensionType)bool

HasExtension reports whether an extension field is populated.It returns false if m is invalid or if xt does not extend m.

funcInt32¶

func Int32(vint32) *int32

Int32 stores v in a new int32 value and returns a pointer to it.

funcInt64¶

func Int64(vint64) *int64

Int64 stores v in a new int64 value and returns a pointer to it.

funcMarshal¶

func Marshal(mMessage) ([]byte,error)

Marshal returns the wire-format encoding of m.

This is the most common entry point for encoding a Protobuf message.

See theMarshalOptions type if you need more control.

package mainimport ("fmt""google.golang.org/protobuf/proto""google.golang.org/protobuf/types/known/durationpb")func main() {b, err := proto.Marshal(&durationpb.Duration{Nanos: 125,})if err != nil {panic(err)}fmt.Printf("125ns encoded into %d bytes of Protobuf wire format:\n% x\n", len(b), b)// You can use protoscope to explore the wire format:// https://github.com/protocolbuffers/protoscope//// echo -n '10 7d' | xxd -r -ps | protoscope// 2: 125}

Output:125ns encoded into 2 bytes of Protobuf wire format:10 7d

funcMerge¶

func Merge(dst, srcMessage)

Merge merges src into dst, which must be a message with the same descriptor.

Populated scalar fields in src are copied to dst, while populatedsingular messages in src are merged into dst by recursively calling Merge.The elements of every list field in src is appended to the correspondedlist fields in dst. The entries of every map field in src is copied intothe corresponding map field in dst, possibly replacing existing entries.The unknown fields of src are appended to the unknown fields of dst.

It is semantically equivalent to unmarshaling the encoded form of srcinto dst with the [UnmarshalOptions.Merge] option specified.

funcMessageName¶added inv1.26.0

func MessageName(mMessage)protoreflect.FullName

MessageName returns the full name of m.If m is nil, it returns an empty string.

funcRangeExtensions¶added inv1.22.0

func RangeExtensions(mMessage, f func(protoreflect.ExtensionType,any)bool)

RangeExtensions iterates over every populated extension field in m in anundefined order, calling f for each extension type and value encountered.It returns immediately if f returns false.While iterating, mutating operations may only be performedon the current extension field.

funcReset¶

func Reset(mMessage)

Reset clears every field in the message.The resulting message shares no observable memory with its previous stateother than the memory for the message itself.

funcSetExtension¶

func SetExtension(mMessage, xtprotoreflect.ExtensionType, vany)

SetExtension stores the value of an extension field.It panics if m is invalid, xt does not extend m, or if type of vis invalid for the specified extension field.

The type of the value is dependent on the field type of the extension.For extensions generated by protoc-gen-go, the Go type is as follows:

╔═══════════════════╤═════════════════════════╗║ Go type           │ Protobuf kind           ║╠═══════════════════╪═════════════════════════╣║ bool              │ bool                    ║║ int32             │ int32, sint32, sfixed32 ║║ int64             │ int64, sint64, sfixed64 ║║ uint32            │ uint32, fixed32         ║║ uint64            │ uint64, fixed64         ║║ float32           │ float                   ║║ float64           │ double                  ║║ string            │ string                  ║║ []byte            │ bytes                   ║║ protoreflect.Enum │ enum                    ║║ proto.Message     │ message, group          ║╚═══════════════════╧═════════════════════════╝

The protoreflect.Enum and proto.Message types are the concrete Go typeassociated with the named enum or message. Repeated fields are representedusing a Go slice of the base element type.

If a generated extension descriptor variable is directly passed toSetExtension (e.g., foopb.E_MyExtension), then the value should be aconcrete type that matches the expected Go type for the extension descriptorso that static analysis tools can verify type correctness.This also enables a possible future migration to a type-safe extension API.

package mainimport ("fmt""google.golang.org/protobuf/proto"extpb "google.golang.org/protobuf/internal/testprotos/examples/ext")func main() {concert := extpb.Concert_builder{HeadlinerName: proto.String("Go Protobuf Acapella Band"),}.Build()fmt.Printf("Has PromoId? %v\n", proto.HasExtension(concert, extpb.E_PromoId))proto.SetExtension(concert, extpb.E_PromoId, int32(2342))fmt.Printf("Has PromoId? %v\n", proto.HasExtension(concert, extpb.E_PromoId))}

Output:Has PromoId? falseHas PromoId? true

funcSize¶

func Size(mMessage)int

Size returns the size in bytes of the wire-format encoding of m.

Note that Size might return more bytes than Marshal will write in the case oflazily decoded messages that arrive in non-minimal wire format: seehttps://protobuf.dev/reference/go/size/ for more details.

package mainimport ("google.golang.org/protobuf/proto")func main() {var m proto.Messageif proto.Size(m) == 0 {// No fields set (or, in proto3, all fields matching the default);// skip processing this message, or return an error, or similar.}}

funcString¶

func String(vstring) *string

String stores v in a new string value and returns a pointer to it.

funcUint32¶

func Uint32(vuint32) *uint32

Uint32 stores v in a new uint32 value and returns a pointer to it.

funcUint64¶

func Uint64(vuint64) *uint64

Uint64 stores v in a new uint64 value and returns a pointer to it.

funcUnmarshal¶

func Unmarshal(b []byte, mMessage)error

Unmarshal parses the wire-format message in b and places the result in m.The provided message must be mutable (e.g., a non-nil pointer to a message).

See theUnmarshalOptions type if you need more control.

package mainimport ("fmt""google.golang.org/protobuf/proto""google.golang.org/protobuf/types/known/durationpb")func main() {// This is the wire format encoding produced by the Marshal example.// Typically you would read from the network, from disk, etc.b := []byte{0x10, 0x7d}var dur durationpb.Durationif err := proto.Unmarshal(b, &dur); err != nil {panic(err)}fmt.Printf("Protobuf wire format decoded to duration %v\n", dur.AsDuration())}

Output:Protobuf wire format decoded to duration 125ns

funcValueOrDefault¶added inv1.36.0

func ValueOrDefault[T interface {*PMessage}, Pany](val T) T

ValueOrDefault returns the protobuf message val if val is not nil, otherwiseit returns a pointer to an empty val message.

This function allows for translating code from the old Open Struct API to thenew Opaque API.

The old Open Struct API represented oneof fields with a wrapper struct:

var signedImg *accountpb.SignedImageprofile := &accountpb.Profile{// The Avatar oneof will be set, with an empty SignedImage.Avatar: &accountpb.Profile_SignedImage{signedImg},}

The new Opaque API treats oneof fields like regular fields, there are no morewrapper structs:

var signedImg *accountpb.SignedImageprofile := &accountpb.Profile{}profile.SetSignedImage(signedImg)

For convenience, the Opaque API also offers Builders, which allow for adirect translation of struct initialization. However, because Builders usenilness to represent field presence (but there is no non-nil wrapper structanymore), Builders cannot distinguish between an unset oneof and a set oneofwith nil message. The above code would need to be translated with help of theValueOrDefault function to retain the same behavior:

var signedImg *accountpb.SignedImagereturn &accountpb.Profile_builder{SignedImage: proto.ValueOrDefault(signedImg),}.Build()

funcValueOrDefaultBytes¶added inv1.36.0

func ValueOrDefaultBytes(val []byte) []byte

ValueOrDefaultBytes is like ValueOrDefault but for working with fields oftype []byte.

funcValueOrNil¶added inv1.36.0

func ValueOrNil[Tany](hasbool, getter func() T) *T

ValueOrNil returns nil if has is false, or a pointer to a new variablecontaining the value returned by the specified getter.

This function is similar to the wrappers (proto.Int32(), proto.String(),etc.), but is generic (works for any field type) and works with the hasserand getter of a field, as opposed to a value.

This is convenient when populating builder fields.

Example:

hop := attr.GetDirectHop()injectedRoute := ripb.InjectedRoute_builder{  Prefixes: route.GetPrefixes(),  NextHop:  proto.ValueOrNil(hop.HasAddress(), hop.GetAddress),}

typeMarshalOptions¶

type MarshalOptions struct {pragma.NoUnkeyedLiterals// AllowPartial allows messages that have missing required fields to marshal// without returning an error. If AllowPartial is false (the default),// Marshal will return an error if there are any missing required fields.AllowPartialbool// Deterministic controls whether the same message will always be// serialized to the same bytes within the same binary.//// Setting this option guarantees that repeated serialization of// the same message will return the same bytes, and that different// processes of the same binary (which may be executing on different// machines) will serialize equal messages to the same bytes.// It has no effect on the resulting size of the encoded message compared// to a non-deterministic marshal.//// Note that the deterministic serialization is NOT canonical across// languages. It is not guaranteed to remain stable over time. It is// unstable across different builds with schema changes due to unknown// fields. Users who need canonical serialization (e.g., persistent// storage in a canonical form, fingerprinting, etc.) must define// their own canonicalization specification and implement their own// serializer rather than relying on this API.//// If deterministic serialization is requested, map entries will be// sorted by keys in lexographical order. This is an implementation// detail and subject to change.Deterministicbool// UseCachedSize indicates that the result of a previous Size call// may be reused.//// Setting this option asserts that://// 1. Size has previously been called on this message with identical// options (except for UseCachedSize itself).//// 2. The message and all its submessages have not changed in any// way since the Size call. For lazily decoded messages, accessing// a message results in decoding the message, which is a change.//// If either of these invariants is violated,// the results are undefined and may include panics or corrupted output.//// Implementations MAY take this option into account to provide// better performance, but there is no guarantee that they will do so.// There is absolutely no guarantee that Size followed by Marshal with// UseCachedSize set will perform equivalently to Marshal alone.UseCachedSizebool}

MarshalOptions configures the marshaler.

Example usage:

b, err := MarshalOptions{Deterministic: true}.Marshal(m)

func (oMarshalOptions) Marshal(mMessage) ([]byte,error)

func (oMarshalOptions) MarshalAppend(b []byte, mMessage) ([]byte,error)

package mainimport ("google.golang.org/protobuf/proto")func main() {var m proto.Messageopts := proto.MarshalOptions{// set e.g. Deterministic: true, if needed}var buf []bytefor i := 0; i < 100000; i++ {var err errorbuf, err = opts.MarshalAppend(buf[:0], m)if err != nil {panic(err)}// cap(buf) will grow to hold the largest m.// write buf to disk, network, etc.}}

func (oMarshalOptions) MarshalState(inprotoiface.MarshalInput) (protoiface.MarshalOutput,error)

func (oMarshalOptions) Size(mMessage)int

typeMessage¶

type Message =protoreflect.ProtoMessage

Message is the top-level interface that all messages must implement.It provides access to a reflective view of a message.Any implementation of this interface may be used with all functions in theprotobuf module that accept a Message, except where otherwise specified.

This is the v2 interface definition for protobuf messages.The v1 interface definition isgithub.com/golang/protobuf/proto.Message.

• To convert a v1 message to a v2 message,usegoogle.golang.org/protobuf/protoadapt.MessageV2Of.
• To convert a v2 message to a v1 message,usegoogle.golang.org/protobuf/protoadapt.MessageV1Of.

func Clone(mMessage)Message

typeUnmarshalOptions¶

type UnmarshalOptions struct {pragma.NoUnkeyedLiterals// Merge merges the input into the destination message.// The default behavior is to always reset the message before unmarshaling,// unless Merge is specified.Mergebool// AllowPartial accepts input for messages that will result in missing// required fields. If AllowPartial is false (the default), Unmarshal will// return an error if there are any missing required fields.AllowPartialbool// If DiscardUnknown is set, unknown fields are ignored.DiscardUnknownbool// Resolver is used for looking up types when unmarshaling extension fields.// If nil, this defaults to using protoregistry.GlobalTypes.Resolver interface {FindExtensionByName(fieldprotoreflect.FullName) (protoreflect.ExtensionType,error)FindExtensionByNumber(messageprotoreflect.FullName, fieldprotoreflect.FieldNumber) (protoreflect.ExtensionType,error)}// RecursionLimit limits how deeply messages may be nested.// If zero, a default limit is applied.RecursionLimitint//// NoLazyDecoding turns off lazy decoding, which otherwise is enabled by// default. Lazy decoding only affects submessages (annotated with [lazy =// true] in the .proto file) within messages that use the Opaque API.NoLazyDecodingbool}

UnmarshalOptions configures the unmarshaler.

Example usage:

err := UnmarshalOptions{DiscardUnknown: true}.Unmarshal(b, m)

func (oUnmarshalOptions) Unmarshal(b []byte, mMessage)error

func (oUnmarshalOptions) UnmarshalState(inprotoiface.UnmarshalInput) (protoiface.UnmarshalOutput,error)