| David K. Bainbridge | e05cf0c | 2021-08-19 03:16:50 +0000 | [diff] [blame] | 1 | // Copyright 2019 The Go 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 proto provides functions operating on protocol buffer messages. |
| 6 | // |
| 7 | // For documentation on protocol buffers in general, see: |
| 8 | // |
| 9 | // https://developers.google.com/protocol-buffers |
| 10 | // |
| 11 | // For a tutorial on using protocol buffers with Go, see: |
| 12 | // |
| 13 | // https://developers.google.com/protocol-buffers/docs/gotutorial |
| 14 | // |
| 15 | // For a guide to generated Go protocol buffer code, see: |
| 16 | // |
| 17 | // https://developers.google.com/protocol-buffers/docs/reference/go-generated |
| 18 | // |
| 19 | // |
| 20 | // Binary serialization |
| 21 | // |
| 22 | // This package contains functions to convert to and from the wire format, |
| 23 | // an efficient binary serialization of protocol buffers. |
| 24 | // |
| 25 | // • Size reports the size of a message in the wire format. |
| 26 | // |
| 27 | // • Marshal converts a message to the wire format. |
| 28 | // The MarshalOptions type provides more control over wire marshaling. |
| 29 | // |
| 30 | // • Unmarshal converts a message from the wire format. |
| 31 | // The UnmarshalOptions type provides more control over wire unmarshaling. |
| 32 | // |
| 33 | // |
| 34 | // Basic message operations |
| 35 | // |
| 36 | // • Clone makes a deep copy of a message. |
| 37 | // |
| 38 | // • Merge merges the content of a message into another. |
| 39 | // |
| 40 | // • Equal compares two messages. For more control over comparisons |
| 41 | // and detailed reporting of differences, see package |
| 42 | // "google.golang.org/protobuf/testing/protocmp". |
| 43 | // |
| 44 | // • Reset clears the content of a message. |
| 45 | // |
| 46 | // • CheckInitialized reports whether all required fields in a message are set. |
| 47 | // |
| 48 | // |
| 49 | // Optional scalar constructors |
| 50 | // |
| 51 | // The API for some generated messages represents optional scalar fields |
| 52 | // as pointers to a value. For example, an optional string field has the |
| 53 | // Go type *string. |
| 54 | // |
| 55 | // • Bool, Int32, Int64, Uint32, Uint64, Float32, Float64, and String |
| 56 | // take a value and return a pointer to a new instance of it, |
| 57 | // to simplify construction of optional field values. |
| 58 | // |
| 59 | // Generated enum types usually have an Enum method which performs the |
| 60 | // same operation. |
| 61 | // |
| 62 | // Optional scalar fields are only supported in proto2. |
| 63 | // |
| 64 | // |
| 65 | // Extension accessors |
| 66 | // |
| 67 | // • HasExtension, GetExtension, SetExtension, and ClearExtension |
| 68 | // access extension field values in a protocol buffer message. |
| 69 | // |
| 70 | // Extension fields are only supported in proto2. |
| 71 | // |
| 72 | // |
| 73 | // Related packages |
| 74 | // |
| 75 | // • Package "google.golang.org/protobuf/encoding/protojson" converts messages to |
| 76 | // and from JSON. |
| 77 | // |
| 78 | // • Package "google.golang.org/protobuf/encoding/prototext" converts messages to |
| 79 | // and from the text format. |
| 80 | // |
| 81 | // • Package "google.golang.org/protobuf/reflect/protoreflect" provides a |
| 82 | // reflection interface for protocol buffer data types. |
| 83 | // |
| 84 | // • Package "google.golang.org/protobuf/testing/protocmp" provides features |
| 85 | // to compare protocol buffer messages with the "github.com/google/go-cmp/cmp" |
| 86 | // package. |
| 87 | // |
| 88 | // • Package "google.golang.org/protobuf/types/dynamicpb" provides a dynamic |
| 89 | // message type, suitable for working with messages where the protocol buffer |
| 90 | // type is only known at runtime. |
| 91 | // |
| 92 | // This module contains additional packages for more specialized use cases. |
| 93 | // Consult the individual package documentation for details. |
| 94 | package proto |