blob: 87d17cfc067d0687bc2ea3d6899353c86a406b44 [file] [log] [blame]
// Copyright 2019 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
package protoreflect
// TODO: Remove this file.
type (
deprecatedMessage interface {
// Deprecated: Use methods on Message directly.
KnownFields() KnownFields
// Deprecated: Use methods on Message directly.
UnknownFields() UnknownFields
}
)
// KnownFields provides accessor and mutator methods for known fields.
//
// Each field Value can either be a scalar, Message, List, or Map.
// The field is a List or Map if FieldDescriptor.Cardinality is Repeated and
// a Map if and only if FieldDescriptor.IsMap is true. The scalar type or
// underlying repeated element type is determined by the FieldDescriptor.Kind.
// See Value for a list of Go types associated with each Kind.
//
// Field extensions are handled as known fields once the extension type has been
// registered with KnownFields.ExtensionTypes.
//
// Len, Has, Get, Range, and ExtensionTypes are safe for concurrent use.
//
// Deprecated: Use direct methods on Message instead.
type KnownFields interface {
// Len reports the number of fields that are populated.
Len() int
// Has reports whether a field is populated.
//
// Some fields have the property of nullability where it is possible to
// distinguish between the default value of a field and whether the field
// was explicitly populated with the default value. Only scalars in proto2,
// member fields of a oneof, and singular messages are nullable.
//
// A nullable field is populated only if explicitly set.
// A scalar field in proto3 is populated if it contains a non-zero value.
// A repeated field is populated only if it is non-empty.
Has(FieldNumber) bool
// Get retrieves the value for a field with the given field number.
// If the field is unpopulated, it returns the default value for scalars,
// a mutable empty List for empty repeated fields, a mutable empty Map for
// empty map fields, and an invalid value for message fields.
// If the field is unknown (does not appear in MessageDescriptor.Fields
// or ExtensionFieldTypes), it returns an invalid value.
Get(FieldNumber) Value
// Set stores the value for a field with the given field number.
// Setting a field belonging to a oneof implicitly clears any other field
// that may be currently set by the same oneof.
//
// When setting a composite type, it is unspecified whether the set
// value aliases the source's memory in any way.
//
// It panics if the field number does not correspond with a known field
// in MessageDescriptor.Fields or an extension field in ExtensionTypes.
Set(FieldNumber, Value)
// TODO: Document memory aliasing behavior when a field is cleared?
// For example, if Mutable is called later, can it reuse memory?
// Clear clears the field such that a subsequent call to Has reports false.
// The operation does nothing if the field number does not correspond with
// a known field or extension field.
Clear(FieldNumber)
// WhichOneof reports which field within the named oneof is populated.
// It returns 0 if the oneof does not exist or no fields are populated.
WhichOneof(Name) FieldNumber
// Range iterates over every populated field in an undefined order,
// calling f for each field number and value encountered.
// Range calls f Len times unless f returns false, which stops iteration.
// While iterating, mutating operations through Set, Clear, or Mutable
// may only be performed on the current field number.
Range(f func(FieldNumber, Value) bool)
// NewMessage returns a newly allocated empty message assignable to
// the field of the given number.
// It panics if the field is not a singular message.
NewMessage(FieldNumber) Message
// ExtensionTypes are extension field types that are known by this
// specific message instance.
ExtensionTypes() ExtensionFieldTypes
}
// UnknownFields are a list of unknown or unparsed fields and may contain
// field numbers corresponding with defined fields or extension fields.
// The ordering of fields is maintained for fields of the same field number.
// However, the relative ordering of fields with different field numbers
// is undefined.
//
// Len, Get, and Range are safe for concurrent use.
//
// Deprecated: Use direct methods on Message instead.
type UnknownFields interface {
// Len reports the number of fields that are populated.
Len() int
// Get retrieves the raw bytes of fields with the given field number.
// It returns an empty RawFields if there are no populated fields.
//
// The caller must not mutate the content of the retrieved RawFields.
Get(FieldNumber) RawFields
// Set stores the raw bytes of fields with the given field number.
// The RawFields must be valid and correspond with the given field number;
// an implementation may panic if the fields are invalid.
// An empty RawFields may be passed to clear the fields.
//
// The caller must not mutate the content of the RawFields being stored.
Set(FieldNumber, RawFields)
// Range iterates over every populated field in an undefined order,
// calling f for each field number and raw field value encountered.
// Range calls f Len times unless f returns false, which stops iteration.
// While iterating, mutating operations through Set may only be performed
// on the current field number.
//
// While the iteration order is undefined, it is deterministic.
// It is recommended, but not required, that fields be presented
// in the order that they were encountered in the wire data.
Range(f func(FieldNumber, RawFields) bool)
// TODO: Should IsSupported be renamed as ReadOnly?
// TODO: Should IsSupported panic on Set instead of silently ignore?
// IsSupported reports whether this message supports unknown fields.
// If false, UnknownFields ignores all Set operations.
IsSupported() bool
}
// ExtensionFieldTypes are the extension field types that this message instance
// has been extended with.
//
// Len, Get, and Range are safe for concurrent use.
//
// Deprecated: Use direct methods on Message instead.
type ExtensionFieldTypes interface {
// Len reports the number of field extensions.
Len() int
// Register stores an ExtensionType.
// The ExtensionType.ExtendedType must match the containing message type
// and the field number must be within the valid extension ranges
// (see MessageDescriptor.ExtensionRanges).
// It panics if the extension has already been registered (i.e.,
// a conflict by number or by full name).
Register(ExtensionType)
// Remove removes the ExtensionType.
// It panics if a value for this extension field is still populated.
// The operation does nothing if there is no associated type to remove.
Remove(ExtensionType)
// ByNumber looks up an extension by field number.
// It returns nil if not found.
ByNumber(FieldNumber) ExtensionType
// ByName looks up an extension field by full name.
// It returns nil if not found.
ByName(FullName) ExtensionType
// Range iterates over every registered field in an undefined order,
// calling f for each extension descriptor encountered.
// Range calls f Len times unless f returns false, which stops iteration.
// While iterating, mutating operations through Remove may only
// be performed on the current descriptor.
Range(f func(ExtensionType) bool)
}