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}
108