pub struct TextDecoder<'a> { /* private fields */ }text only.Expand description
Stateful textproto reader.
Drives a Tokenizer and interprets scalar tokens as the requested Rust
type. Recursion depth is enforced by the tokenizer’s fixed-size open-stack
(see RECURSION_LIMIT), and repeated and map
elements are charged against an element-memory budget defaulting to
DEFAULT_ELEMENT_MEMORY_LIMIT
(see with_element_memory_limit).
Implementations§
Source§impl<'a> TextDecoder<'a>
impl<'a> TextDecoder<'a>
Sourcepub fn with_element_memory_limit(self, bytes: usize) -> Self
pub fn with_element_memory_limit(self, bytes: usize) -> Self
Set the element-memory budget for this parse.
Bounds what the parse materializes rather than what it reads; see
ParseErrorKind::ElementMemoryLimitExceeded. Defaults to
DEFAULT_ELEMENT_MEMORY_LIMIT;
pass usize::MAX to disable.
The budget is shared across the whole parse, not per field, as
DecodeOptions::with_element_memory_limit
is on the binary side. The two are not charged identically: this
parser also charges repeated scalars, which the binary decoder
exempts because a packed 1-byte varint becoming a 4-byte i32 is not
an amplification vector. Text has no packed form, so a repeated
scalar costs at least two input bytes per element and cannot reach a
worse ratio than that exemption protects — but a textproto scalar
list above roughly limit / size_of::<T>() elements is refused where
the equivalent binary payload is not.
Sourcepub fn read_field_name(&mut self) -> Result<Option<&'a str>, ParseError>
pub fn read_field_name(&mut self) -> Result<Option<&'a str>, ParseError>
Read the next field name, or return None at end-of-message / EOF.
The returned slice is borrowed directly from the input. For bracketed
type names ([pkg.ext]) it includes the brackets — generated code
matches against "[pkg.ext]" literally.
The : after the name is optional before a message value or a list
of message values. This method returns the name either way; for a
scalar value, or a scalar list element, that follows a name without
one, the call that reads the value returns the error. An empty list
[] has no element to read, so it parses with or without the colon,
unless the caller reads it with
read_repeated_scalar_into, which
requires the colon.
§Errors
Any tokenizer error — malformed name, delimiter mismatch, etc.
Sourcepub fn unknown_field(&self) -> ParseError
pub fn unknown_field(&self) -> ParseError
Construct an unknown-field error pointing at the last name returned
by read_field_name.
Generated merge_text wildcard arms return this for any name that is
neither a declared field nor a declared reserved name; reserved names
are consumed with skip_value instead.
Sourcepub fn read_i32(&mut self) -> Result<i32, ParseError>
pub fn read_i32(&mut self) -> Result<i32, ParseError>
Read an i32 value.
Accepts decimal, 0x hex, 0 octal. Rejects floats and out-of-range.
§Errors
ParseErrorKind::InvalidNumber if not a valid in-range integer, or
ParseErrorKind::UnexpectedToken if the value is not a number at all.
Sourcepub fn read_u32(&mut self) -> Result<u32, ParseError>
pub fn read_u32(&mut self) -> Result<u32, ParseError>
Sourcepub fn read_u64(&mut self) -> Result<u64, ParseError>
pub fn read_u64(&mut self) -> Result<u64, ParseError>
Sourcepub fn read_f32(&mut self) -> Result<f32, ParseError>
pub fn read_f32(&mut self) -> Result<f32, ParseError>
Read an f32 value.
Accepts a decimal number, optionally with an f suffix, or one of the
case-insensitive literals nan, inf and infinity. Either can
follow a -, and whitespace or comments can separate the sign from
what it negates.
A number rounds once, to the nearest value of the type, ties to even. Overflow gives ±∞ and underflow gives ±0.
§Errors
ParseErrorKind::InvalidNumber if the token is a hex or octal
number, or an identifier other than nan, inf or infinity.
ParseErrorKind::UnexpectedToken if the token is a string or is not
a scalar.
Sourcepub fn read_f64(&mut self) -> Result<f64, ParseError>
pub fn read_f64(&mut self) -> Result<f64, ParseError>
Sourcepub fn read_bool(&mut self) -> Result<bool, ParseError>
pub fn read_bool(&mut self) -> Result<bool, ParseError>
Read a bool value.
Accepts true, True, t, false, False, f, and 0/1
(in any integer base). These are the exact literals the C++ text
parser accepts.
§Errors
ParseErrorKind::UnexpectedToken if the token is not a recognised
boolean form.
Sourcepub fn read_string(&mut self) -> Result<Cow<'a, str>, ParseError>
pub fn read_string(&mut self) -> Result<Cow<'a, str>, ParseError>
Read a string value. Unescapes and UTF-8-validates.
Borrows the input when the token is a single literal with no escapes.
§Errors
ParseErrorKind::InvalidString for malformed escapes,
ParseErrorKind::InvalidUtf8 if the unescaped bytes are not valid
UTF-8.
Sourcepub fn read_bytes(&mut self) -> Result<Vec<u8>, ParseError>
pub fn read_bytes(&mut self) -> Result<Vec<u8>, ParseError>
Read a bytes value. Unescapes but does not UTF-8-validate.
§Errors
ParseErrorKind::InvalidString for malformed escapes.
Sourcepub fn read_enum_by_name<E: Enumeration>(&mut self) -> Result<i32, ParseError>
pub fn read_enum_by_name<E: Enumeration>(&mut self) -> Result<i32, ParseError>
Read an enum value by variant name or by number (open-enum semantics).
Returns the i32 wire value. Any in-range integer is accepted — the
proto3 open-enum model preserves unknown numeric values.
§Errors
ParseErrorKind::UnknownEnumValue if the name is not a known
variant; ParseErrorKind::InvalidNumber if a numeric form is out
of i32 range.
Sourcepub fn read_closed_enum_by_name<E: Enumeration>(
&mut self,
) -> Result<E, ParseError>
pub fn read_closed_enum_by_name<E: Enumeration>( &mut self, ) -> Result<E, ParseError>
Read a closed-enum value by variant name or by number.
Returns the enum variant directly. Unknown numeric values are rejected — the proto2 closed-enum model does not accept values outside the defined set in text format. (Binary decode routes them to unknown fields; text format has no analogous mechanism, so it errors.)
§Errors
ParseErrorKind::UnknownEnumValue if the name is not a known
variant, or if a numeric form does not map to a defined variant.
Sourcepub fn merge_message<M: TextFormat>(
&mut self,
msg: &mut M,
) -> Result<(), ParseError>
pub fn merge_message<M: TextFormat>( &mut self, msg: &mut M, ) -> Result<(), ParseError>
Enter a { or <, merge into msg, then consume the matching close.
§Errors
Any tokenizer or merge_text error, including
ParseErrorKind::RecursionLimitExceeded if nesting exceeds
RECURSION_LIMIT.
Sourcepub fn read_repeated_into<T>(
&mut self,
out: &mut Vec<T>,
read_one: impl FnMut(&mut Self) -> Result<T, ParseError>,
) -> Result<(), ParseError>
pub fn read_repeated_into<T>( &mut self, out: &mut Vec<T>, read_one: impl FnMut(&mut Self) -> Result<T, ParseError>, ) -> Result<(), ParseError>
Read one or more values of a repeated field into out.
Handles both forms of a repeated value: the list f: [1, 2, 3]
(consumes [ and ]) and the single value f: 1 (reads exactly one
element). Generated code calls this once per f occurrence; the
f: 1 f: 2 form is handled by the outer read_field_name loop seeing
f twice.
An empty list [] is accepted with or without a : after the field
name, which is the rule for a list of messages. For a field whose
elements are scalars, use
read_repeated_scalar_into, which
requires the colon.
§Errors
Any error from read_one or the tokenizer.
Sourcepub fn read_repeated_scalar_into<T>(
&mut self,
out: &mut Vec<T>,
read_one: impl FnMut(&mut Self) -> Result<T, ParseError>,
) -> Result<(), ParseError>
pub fn read_repeated_scalar_into<T>( &mut self, out: &mut Vec<T>, read_one: impl FnMut(&mut Self) -> Result<T, ParseError>, ) -> Result<(), ParseError>
Read one or more values of a repeated scalar field into out,
requiring the : after the field name even before an empty list.
Reads the same two forms as
read_repeated_into. Use it when the
field’s elements are numbers, bools, enums, strings or bytes, as
generated code does. The tokenizer cannot infer the field type from
[], so this method applies the check for the empty list. For a
list with elements, or a single value, the tokenizer finds the
missing colon when this method reads the element.
§Errors
ParseErrorKind::UnexpectedTokenwithexpectedset to"':' before scalar value"when the field name has no:after it. The error is positioned at the[of an empty list, and at the element for a list with elements or a single value.- Any other error from
read_oneor the tokenizer.
Sourcepub fn read_repeated_into_storage<T, C: ProtoList<T>>(
&mut self,
out: &mut C,
read_one: impl FnMut(&mut Self) -> Result<T, ParseError>,
) -> Result<(), ParseError>
pub fn read_repeated_into_storage<T, C: ProtoList<T>>( &mut self, out: &mut C, read_one: impl FnMut(&mut Self) -> Result<T, ParseError>, ) -> Result<(), ParseError>
Decode repeated messages directly into a custom collection.
§Errors
Returns a tokenizer or element-decoding error, preserving earlier elements.
Sourcepub fn read_repeated_scalar_into_storage<T, C: ProtoList<T>>(
&mut self,
out: &mut C,
read_one: impl FnMut(&mut Self) -> Result<T, ParseError>,
) -> Result<(), ParseError>
pub fn read_repeated_scalar_into_storage<T, C: ProtoList<T>>( &mut self, out: &mut C, read_one: impl FnMut(&mut Self) -> Result<T, ParseError>, ) -> Result<(), ParseError>
Decode repeated scalars directly into a custom collection, requiring :.
§Errors
Returns a tokenizer or element-decoding error, preserving earlier elements.
Sourcepub fn read_repeated_with<T>(
&mut self,
push: impl FnMut(T),
read_one: impl FnMut(&mut Self) -> Result<T, ParseError>,
) -> Result<(), ParseError>
pub fn read_repeated_with<T>( &mut self, push: impl FnMut(T), read_one: impl FnMut(&mut Self) -> Result<T, ParseError>, ) -> Result<(), ParseError>
Decode repeated message values and pass each one directly to its owner.
§Errors
Returns a tokenizer or element-decoding error after committing earlier values.
Sourcepub fn read_any_expansion(
&mut self,
name: &'a str,
) -> Result<(Cow<'a, str>, Vec<u8>), ParseError>
pub fn read_any_expansion( &mut self, name: &'a str, ) -> Result<(Cow<'a, str>, Vec<u8>), ParseError>
Parse an Any-expansion body: the [type_url] { fields } form.
name is the bracketed name as returned by
read_field_name, e.g.
"[type.googleapis.com/pkg.Foo]". The brackets, and any whitespace or
# comments between them, are stripped here and the result is looked
up in the global text-format Any map (installed via
set_type_registry); the registered text_merge then consumes the
{ ... } body and re-encodes to wire bytes suitable for Any.value.
Returns (type_url, value_bytes), where type_url is the URL between
the brackets with whitespace and comments removed. It is the value for
Any.type_url, and is borrowed from name unless whitespace or
comments were removed. Its prefix can differ from the registered
URL’s, because the map matches an unregistered URL by the message full
name after its last /.
§Errors
ParseErrorKind::UnknownField if neither the URL nor its message
full name is registered — this matches AnyFieldWithInvalidType in
the conformance suite, which expects parse failure on an unknown URL.
Sourcepub fn read_extension(
&mut self,
name: &str,
extendee: &str,
) -> Result<Vec<UnknownField>, ParseError>
pub fn read_extension( &mut self, name: &str, extendee: &str, ) -> Result<Vec<UnknownField>, ParseError>
Parse an extension bracket body: the [pkg.ext] { ... } form.
name is the bracketed name as returned by
read_field_name. The brackets, and any
whitespace or # comments between them, are stripped and the result
is looked up by full_name in the global text-format
extension map (installed via set_type_registry); the registered
text_merge consumes the value and produces unknown-field records at
the extension’s field number.
Repeated message and group entries accept a message list or a single message value and produce one record per element.
§Errors
ParseErrorKind::UnknownField if the name is not registered or the
registered entry extends a different message. Strict by default —
protobuf-go’s prototext behaviour, and what the
GroupFieldExtensionGroupName conformance test expects.
Sourcepub fn skip_value(&mut self) -> Result<(), ParseError>
pub fn skip_value(&mut self) -> Result<(), ParseError>
Consume a field’s value without interpreting it.
Generated merge_text impls call this for declared reserved field
names; hand-written impls can call it for any name they want to accept
and discard rather than fail on. Handles scalars, messages ({} and
<>), and lists (recursively).
§Errors
Any tokenizer error in the skipped span.