Skip to main content

TextDecoder

Struct TextDecoder 

Source
pub struct TextDecoder<'a> { /* private fields */ }
Available on crate feature 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>

Source

pub fn new(input: &'a str) -> Self

Create a decoder over input.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn read_i64(&mut self) -> Result<i64, ParseError>

Read an i64 value.

§Errors

As read_i32.

Source

pub fn read_u32(&mut self) -> Result<u32, ParseError>

Read a u32 value. Rejects negatives.

§Errors

As read_i32.

Source

pub fn read_u64(&mut self) -> Result<u64, ParseError>

Read a u64 value. Rejects negatives.

§Errors

As read_i32.

Source

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.

Source

pub fn read_f64(&mut self) -> Result<f64, ParseError>

Read an f64 value. See read_f32.

§Errors

As read_f32.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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::UnexpectedToken with expected set 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_one or the tokenizer.
Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Auto Trait Implementations§

§

impl<'a> Forget for TextDecoder<'a>

§

impl<'a> Freeze for TextDecoder<'a>

§

impl<'a> Move for TextDecoder<'a>

§

impl<'a> RefUnwindSafe for TextDecoder<'a>

§

impl<'a> Send for TextDecoder<'a>

§

impl<'a> Sync for TextDecoder<'a>

§

impl<'a> Unpin for TextDecoder<'a>

§

impl<'a> UnsafeUnpin for TextDecoder<'a>

§

impl<'a> UnwindSafe for TextDecoder<'a>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.