zvariant/
encoding_context.rs

Help
1use std::marker::PhantomData;
2
3use static_assertions::assert_impl_all;
4
5/// The encoding format.
6#[derive(Debug, Default, PartialEq, Eq, Copy, Clone)]
7pub enum EncodingFormat {
8    /// [D-Bus](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-marshaling)
9    /// format.
10    #[default]
11    DBus,
12    /// [GVariant](https://developer.gnome.org/glib/stable/glib-GVariant.html) format.
13    #[cfg(feature = "gvariant")]
14    GVariant,
15}
16
17assert_impl_all!(EncodingFormat: Send, Sync, Unpin);
18
19impl std::fmt::Display for EncodingFormat {
20    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
21        match self {
22            EncodingFormat::DBus => write!(f, "D-Bus"),
23            #[cfg(feature = "gvariant")]
24            EncodingFormat::GVariant => write!(f, "GVariant"),
25        }
26    }
27}
28
29/// The encoding context to use with the [serialization and deserialization] API.
30///
31/// This type is generic over the [ByteOrder] trait. Moreover, the encoding is dependent on the
32/// position of the encoding in the entire message and hence the need to [specify] the byte
33/// position of the data being serialized or deserialized. Simply pass `0` if serializing or
34/// deserializing to or from the beginning of message, or the preceding bytes end on an 8-byte
35/// boundary.
36///
37/// # Examples
38///
39/// ```
40/// use byteorder::LE;
41///
42/// use zvariant::EncodingContext as Context;
43/// use zvariant::{from_slice, to_bytes};
44///
45/// let str_vec = vec!["Hello", "World"];
46/// let ctxt = Context::<LE>::new_dbus(0);
47/// let encoded = to_bytes(ctxt, &str_vec).unwrap();
48///
49/// // Let's decode the 2nd element of the array only
50/// let ctxt = Context::<LE>::new_dbus(14);
51/// let decoded: &str = from_slice(&encoded[14..], ctxt).unwrap();
52/// assert_eq!(decoded, "World");
53/// ```
54///
55/// [serialization and deserialization]: index.html#functions
56/// [ByteOrder]: https://docs.rs/byteorder/1.3.4/byteorder/trait.ByteOrder.html
57/// [specify]: #method.new
58#[derive(Debug, PartialEq, Eq, Copy, Clone)]
59pub struct EncodingContext<B> {
60    format: EncodingFormat,
61    position: usize,
62
63    b: PhantomData<B>,
64}
65
66assert_impl_all!(EncodingContext<byteorder::NativeEndian>: Send, Sync, Unpin);
67
68impl<B> EncodingContext<B>
69where
70    B: byteorder::ByteOrder,
71{
72    /// Create a new encoding context.
73    pub fn new(format: EncodingFormat, position: usize) -> Self {
74        Self {
75            format,
76            position,
77            b: PhantomData,
78        }
79    }
80
81    /// Convenient wrapper for [`new`] to create a context for D-Bus format.
82    ///
83    /// [`new`]: #method.new
84    pub fn new_dbus(position: usize) -> Self {
85        Self::new(EncodingFormat::DBus, position)
86    }
87
88    /// Convenient wrapper for [`new`] to create a context for GVariant format.
89    ///
90    /// [`new`]: #method.new
91    #[cfg(feature = "gvariant")]
92    pub fn new_gvariant(position: usize) -> Self {
93        Self::new(EncodingFormat::GVariant, position)
94    }
95
96    /// The [`EncodingFormat`] of this context.
97    ///
98    /// [`EncodingFormat`]: enum.EncodingFormat.html
99    pub fn format(self) -> EncodingFormat {
100        self.format
101    }
102
103    /// The byte position of the value to be encoded or decoded, in the entire message.
104    pub fn position(self) -> usize {
105        self.position
106    }
107}
zvariant/encoding_context.rs

zvariant/
encoding_context.rs
