value.go 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285
  1. // Copyright 2018 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. package protoreflect
  5. import "google.golang.org/protobuf/encoding/protowire"
  6. // Enum is a reflection interface for a concrete enum value,
  7. // which provides type information and a getter for the enum number.
  8. // Enum does not provide a mutable API since enums are commonly backed by
  9. // Go constants, which are not addressable.
  10. type Enum interface {
  11. // Descriptor returns enum descriptor, which contains only the protobuf
  12. // type information for the enum.
  13. Descriptor() EnumDescriptor
  14. // Type returns the enum type, which encapsulates both Go and protobuf
  15. // type information. If the Go type information is not needed,
  16. // it is recommended that the enum descriptor be used instead.
  17. Type() EnumType
  18. // Number returns the enum value as an integer.
  19. Number() EnumNumber
  20. }
  21. // Message is a reflective interface for a concrete message value,
  22. // encapsulating both type and value information for the message.
  23. //
  24. // Accessor/mutators for individual fields are keyed by FieldDescriptor.
  25. // For non-extension fields, the descriptor must exactly match the
  26. // field known by the parent message.
  27. // For extension fields, the descriptor must implement ExtensionTypeDescriptor,
  28. // extend the parent message (i.e., have the same message FullName), and
  29. // be within the parent's extension range.
  30. //
  31. // Each field Value can be a scalar or a composite type (Message, List, or Map).
  32. // See Value for the Go types associated with a FieldDescriptor.
  33. // Providing a Value that is invalid or of an incorrect type panics.
  34. type Message interface {
  35. // Descriptor returns message descriptor, which contains only the protobuf
  36. // type information for the message.
  37. Descriptor() MessageDescriptor
  38. // Type returns the message type, which encapsulates both Go and protobuf
  39. // type information. If the Go type information is not needed,
  40. // it is recommended that the message descriptor be used instead.
  41. Type() MessageType
  42. // New returns a newly allocated and mutable empty message.
  43. New() Message
  44. // Interface unwraps the message reflection interface and
  45. // returns the underlying ProtoMessage interface.
  46. Interface() ProtoMessage
  47. // Range iterates over every populated field in an undefined order,
  48. // calling f for each field descriptor and value encountered.
  49. // Range returns immediately if f returns false.
  50. // While iterating, mutating operations may only be performed
  51. // on the current field descriptor.
  52. Range(f func(FieldDescriptor, Value) bool)
  53. // Has reports whether a field is populated.
  54. //
  55. // Some fields have the property of nullability where it is possible to
  56. // distinguish between the default value of a field and whether the field
  57. // was explicitly populated with the default value. Singular message fields,
  58. // member fields of a oneof, and proto2 scalar fields are nullable. Such
  59. // fields are populated only if explicitly set.
  60. //
  61. // In other cases (aside from the nullable cases above),
  62. // a proto3 scalar field is populated if it contains a non-zero value, and
  63. // a repeated field is populated if it is non-empty.
  64. Has(FieldDescriptor) bool
  65. // Clear clears the field such that a subsequent Has call reports false.
  66. //
  67. // Clearing an extension field clears both the extension type and value
  68. // associated with the given field number.
  69. //
  70. // Clear is a mutating operation and unsafe for concurrent use.
  71. Clear(FieldDescriptor)
  72. // Get retrieves the value for a field.
  73. //
  74. // For unpopulated scalars, it returns the default value, where
  75. // the default value of a bytes scalar is guaranteed to be a copy.
  76. // For unpopulated composite types, it returns an empty, read-only view
  77. // of the value; to obtain a mutable reference, use Mutable.
  78. Get(FieldDescriptor) Value
  79. // Set stores the value for a field.
  80. //
  81. // For a field belonging to a oneof, it implicitly clears any other field
  82. // that may be currently set within the same oneof.
  83. // For extension fields, it implicitly stores the provided ExtensionType.
  84. // When setting a composite type, it is unspecified whether the stored value
  85. // aliases the source's memory in any way. If the composite value is an
  86. // empty, read-only value, then it panics.
  87. //
  88. // Set is a mutating operation and unsafe for concurrent use.
  89. Set(FieldDescriptor, Value)
  90. // Mutable returns a mutable reference to a composite type.
  91. //
  92. // If the field is unpopulated, it may allocate a composite value.
  93. // For a field belonging to a oneof, it implicitly clears any other field
  94. // that may be currently set within the same oneof.
  95. // For extension fields, it implicitly stores the provided ExtensionType
  96. // if not already stored.
  97. // It panics if the field does not contain a composite type.
  98. //
  99. // Mutable is a mutating operation and unsafe for concurrent use.
  100. Mutable(FieldDescriptor) Value
  101. // NewField returns a new value that is assignable to the field
  102. // for the given descriptor. For scalars, this returns the default value.
  103. // For lists, maps, and messages, this returns a new, empty, mutable value.
  104. NewField(FieldDescriptor) Value
  105. // WhichOneof reports which field within the oneof is populated,
  106. // returning nil if none are populated.
  107. // It panics if the oneof descriptor does not belong to this message.
  108. WhichOneof(OneofDescriptor) FieldDescriptor
  109. // GetUnknown retrieves the entire list of unknown fields.
  110. // The caller may only mutate the contents of the RawFields
  111. // if the mutated bytes are stored back into the message with SetUnknown.
  112. GetUnknown() RawFields
  113. // SetUnknown stores an entire list of unknown fields.
  114. // The raw fields must be syntactically valid according to the wire format.
  115. // An implementation may panic if this is not the case.
  116. // Once stored, the caller must not mutate the content of the RawFields.
  117. // An empty RawFields may be passed to clear the fields.
  118. //
  119. // SetUnknown is a mutating operation and unsafe for concurrent use.
  120. SetUnknown(RawFields)
  121. // IsValid reports whether the message is valid.
  122. //
  123. // An invalid message is an empty, read-only value.
  124. //
  125. // An invalid message often corresponds to a nil pointer of the concrete
  126. // message type, but the details are implementation dependent.
  127. // Validity is not part of the protobuf data model, and may not
  128. // be preserved in marshaling or other operations.
  129. IsValid() bool
  130. // ProtoMethods returns optional fast-path implementions of various operations.
  131. // This method may return nil.
  132. //
  133. // The returned methods type is identical to
  134. // "google.golang.org/protobuf/runtime/protoiface".Methods.
  135. // Consult the protoiface package documentation for details.
  136. ProtoMethods() *methods
  137. }
  138. // RawFields is the raw bytes for an ordered sequence of fields.
  139. // Each field contains both the tag (representing field number and wire type),
  140. // and also the wire data itself.
  141. type RawFields []byte
  142. // IsValid reports whether b is syntactically correct wire format.
  143. func (b RawFields) IsValid() bool {
  144. for len(b) > 0 {
  145. _, _, n := protowire.ConsumeField(b)
  146. if n < 0 {
  147. return false
  148. }
  149. b = b[n:]
  150. }
  151. return true
  152. }
  153. // List is a zero-indexed, ordered list.
  154. // The element Value type is determined by FieldDescriptor.Kind.
  155. // Providing a Value that is invalid or of an incorrect type panics.
  156. type List interface {
  157. // Len reports the number of entries in the List.
  158. // Get, Set, and Truncate panic with out of bound indexes.
  159. Len() int
  160. // Get retrieves the value at the given index.
  161. // It never returns an invalid value.
  162. Get(int) Value
  163. // Set stores a value for the given index.
  164. // When setting a composite type, it is unspecified whether the set
  165. // value aliases the source's memory in any way.
  166. //
  167. // Set is a mutating operation and unsafe for concurrent use.
  168. Set(int, Value)
  169. // Append appends the provided value to the end of the list.
  170. // When appending a composite type, it is unspecified whether the appended
  171. // value aliases the source's memory in any way.
  172. //
  173. // Append is a mutating operation and unsafe for concurrent use.
  174. Append(Value)
  175. // AppendMutable appends a new, empty, mutable message value to the end
  176. // of the list and returns it.
  177. // It panics if the list does not contain a message type.
  178. AppendMutable() Value
  179. // Truncate truncates the list to a smaller length.
  180. //
  181. // Truncate is a mutating operation and unsafe for concurrent use.
  182. Truncate(int)
  183. // NewElement returns a new value for a list element.
  184. // For enums, this returns the first enum value.
  185. // For other scalars, this returns the zero value.
  186. // For messages, this returns a new, empty, mutable value.
  187. NewElement() Value
  188. // IsValid reports whether the list is valid.
  189. //
  190. // An invalid list is an empty, read-only value.
  191. //
  192. // Validity is not part of the protobuf data model, and may not
  193. // be preserved in marshaling or other operations.
  194. IsValid() bool
  195. }
  196. // Map is an unordered, associative map.
  197. // The entry MapKey type is determined by FieldDescriptor.MapKey.Kind.
  198. // The entry Value type is determined by FieldDescriptor.MapValue.Kind.
  199. // Providing a MapKey or Value that is invalid or of an incorrect type panics.
  200. type Map interface {
  201. // Len reports the number of elements in the map.
  202. Len() int
  203. // Range iterates over every map entry in an undefined order,
  204. // calling f for each key and value encountered.
  205. // Range calls f Len times unless f returns false, which stops iteration.
  206. // While iterating, mutating operations may only be performed
  207. // on the current map key.
  208. Range(f func(MapKey, Value) bool)
  209. // Has reports whether an entry with the given key is in the map.
  210. Has(MapKey) bool
  211. // Clear clears the entry associated with they given key.
  212. // The operation does nothing if there is no entry associated with the key.
  213. //
  214. // Clear is a mutating operation and unsafe for concurrent use.
  215. Clear(MapKey)
  216. // Get retrieves the value for an entry with the given key.
  217. // It returns an invalid value for non-existent entries.
  218. Get(MapKey) Value
  219. // Set stores the value for an entry with the given key.
  220. // It panics when given a key or value that is invalid or the wrong type.
  221. // When setting a composite type, it is unspecified whether the set
  222. // value aliases the source's memory in any way.
  223. //
  224. // Set is a mutating operation and unsafe for concurrent use.
  225. Set(MapKey, Value)
  226. // Mutable retrieves a mutable reference to the entry for the given key.
  227. // If no entry exists for the key, it creates a new, empty, mutable value
  228. // and stores it as the entry for the key.
  229. // It panics if the map value is not a message.
  230. Mutable(MapKey) Value
  231. // NewValue returns a new value assignable as a map value.
  232. // For enums, this returns the first enum value.
  233. // For other scalars, this returns the zero value.
  234. // For messages, this returns a new, empty, mutable value.
  235. NewValue() Value
  236. // IsValid reports whether the map is valid.
  237. //
  238. // An invalid map is an empty, read-only value.
  239. //
  240. // An invalid message often corresponds to a nil Go map value,
  241. // but the details are implementation dependent.
  242. // Validity is not part of the protobuf data model, and may not
  243. // be preserved in marshaling or other operations.
  244. IsValid() bool
  245. }