prost/
message.rs

1use alloc::boxed::Box;
2use core::fmt::Debug;
3use core::usize;
4
5use bytes::{Buf, BufMut};
6
7use crate::encoding::{
8    decode_key, encode_varint, encoded_len_varint, message, DecodeContext, WireType,
9};
10use crate::DecodeError;
11use crate::EncodeError;
12
13/// A Protocol Buffers message.
14pub trait Message: Debug + Send + Sync {
15    /// Encodes the message to a buffer.
16    ///
17    /// This method will panic if the buffer has insufficient capacity.
18    ///
19    /// Meant to be used only by `Message` implementations.
20    #[doc(hidden)]
21    fn encode_raw<B>(&self, buf: &mut B)
22    where
23        B: BufMut,
24        Self: Sized;
25
26    /// Decodes a field from a buffer, and merges it into `self`.
27    ///
28    /// Meant to be used only by `Message` implementations.
29    #[doc(hidden)]
30    fn merge_field<B>(
31        &mut self,
32        tag: u32,
33        wire_type: WireType,
34        buf: &mut B,
35        ctx: DecodeContext,
36    ) -> Result<(), DecodeError>
37    where
38        B: Buf,
39        Self: Sized;
40
41    /// Returns the encoded length of the message without a length delimiter.
42    fn encoded_len(&self) -> usize;
43
44    /// Encodes the message to a buffer.
45    ///
46    /// An error will be returned if the buffer does not have sufficient capacity.
47    fn encode<B>(&self, buf: &mut B) -> Result<(), EncodeError>
48    where
49        B: BufMut,
50        Self: Sized,
51    {
52        let required = self.encoded_len();
53        let remaining = buf.remaining_mut();
54        if required > buf.remaining_mut() {
55            return Err(EncodeError::new(required, remaining));
56        }
57
58        self.encode_raw(buf);
59        Ok(())
60    }
61
62    #[cfg(feature = "std")]
63    /// Encodes the message to a newly allocated buffer.
64    fn encode_to_vec(&self) -> Vec<u8>
65    where
66        Self: Sized,
67    {
68        let mut buf = Vec::with_capacity(self.encoded_len());
69
70        self.encode_raw(&mut buf);
71        buf
72    }
73
74    /// Encodes the message with a length-delimiter to a buffer.
75    ///
76    /// An error will be returned if the buffer does not have sufficient capacity.
77    fn encode_length_delimited<B>(&self, buf: &mut B) -> Result<(), EncodeError>
78    where
79        B: BufMut,
80        Self: Sized,
81    {
82        let len = self.encoded_len();
83        let required = len + encoded_len_varint(len as u64);
84        let remaining = buf.remaining_mut();
85        if required > remaining {
86            return Err(EncodeError::new(required, remaining));
87        }
88        encode_varint(len as u64, buf);
89        self.encode_raw(buf);
90        Ok(())
91    }
92
93    #[cfg(feature = "std")]
94    /// Encodes the message with a length-delimiter to a newly allocated buffer.
95    fn encode_length_delimited_to_vec(&self) -> Vec<u8>
96    where
97        Self: Sized,
98    {
99        let len = self.encoded_len();
100        let mut buf = Vec::with_capacity(len + encoded_len_varint(len as u64));
101
102        encode_varint(len as u64, &mut buf);
103        self.encode_raw(&mut buf);
104        buf
105    }
106
107    /// Decodes an instance of the message from a buffer.
108    ///
109    /// The entire buffer will be consumed.
110    fn decode<B>(mut buf: B) -> Result<Self, DecodeError>
111    where
112        B: Buf,
113        Self: Default,
114    {
115        let mut message = Self::default();
116        Self::merge(&mut message, &mut buf).map(|_| message)
117    }
118
119    /// Decodes a length-delimited instance of the message from the buffer.
120    fn decode_length_delimited<B>(buf: B) -> Result<Self, DecodeError>
121    where
122        B: Buf,
123        Self: Default,
124    {
125        let mut message = Self::default();
126        message.merge_length_delimited(buf)?;
127        Ok(message)
128    }
129
130    /// Decodes an instance of the message from a buffer, and merges it into `self`.
131    ///
132    /// The entire buffer will be consumed.
133    fn merge<B>(&mut self, mut buf: B) -> Result<(), DecodeError>
134    where
135        B: Buf,
136        Self: Sized,
137    {
138        let ctx = DecodeContext::default();
139        while buf.has_remaining() {
140            let (tag, wire_type) = decode_key(&mut buf)?;
141            self.merge_field(tag, wire_type, &mut buf, ctx.clone())?;
142        }
143        Ok(())
144    }
145
146    /// Decodes a length-delimited instance of the message from buffer, and
147    /// merges it into `self`.
148    fn merge_length_delimited<B>(&mut self, mut buf: B) -> Result<(), DecodeError>
149    where
150        B: Buf,
151        Self: Sized,
152    {
153        message::merge(
154            WireType::LengthDelimited,
155            self,
156            &mut buf,
157            DecodeContext::default(),
158        )
159    }
160
161    /// Clears the message, resetting all fields to their default.
162    fn clear(&mut self);
163}
164
165impl<M> Message for Box<M>
166where
167    M: Message,
168{
169    fn encode_raw<B>(&self, buf: &mut B)
170    where
171        B: BufMut,
172    {
173        (**self).encode_raw(buf)
174    }
175    fn merge_field<B>(
176        &mut self,
177        tag: u32,
178        wire_type: WireType,
179        buf: &mut B,
180        ctx: DecodeContext,
181    ) -> Result<(), DecodeError>
182    where
183        B: Buf,
184    {
185        (**self).merge_field(tag, wire_type, buf, ctx)
186    }
187    fn encoded_len(&self) -> usize {
188        (**self).encoded_len()
189    }
190    fn clear(&mut self) {
191        (**self).clear()
192    }
193}
194
195#[cfg(test)]
196mod tests {
197    use super::*;
198
199    const _MESSAGE_IS_OBJECT_SAFE: Option<&dyn Message> = None;
200}
prost/message.rs

prost/
message.rs
