musli/
en.rs

1//! Traits for generically dealing with an encoding framework.
2//!
3//! The central traits are [Encode] and [Encoder].
4//!
5//! A type implementing [Encode] can use an [Encoder] to encode itself. This
6//! also comes with a derive allowing you to derive high performance encoding
7//! associated with native Rust types.
8//!
9//! ```
10//! use musli::Encode;
11//!
12//! #[derive(Encode)]
13//! pub struct Person<'a> {
14//!     name: &'a str,
15//!     age: u32,
16//! }
17//! ```
18
19/// Derive which automatically implements the [`Encode` trait].
20///
21/// See the [`derives` module] for detailed documentation.
22///
23/// [`derives` module]: crate::_help::derives
24/// [`Encode` trait]: trait@Encode
25///
26/// # Examples
27///
28/// ```
29/// use musli::Encode;
30///
31/// #[derive(Encode)]
32/// struct MyType {
33///     data: [u8; 128],
34/// }
35/// ```
36///
37/// When using through `musli_core`, the crate needs to be specified:
38///
39/// ```
40/// use musli_core::Encode;
41///
42/// #[derive(Encode)]
43/// #[musli(crate = musli_core)]
44/// struct MyType {
45///     data: [u8; 128],
46/// }
47/// ```
48#[doc(inline)]
49pub use musli_core::__macros::Encode;
50
51/// This is an attribute macro that must be used when implementing a
52/// [`Encoder`].
53///
54/// It is required to use because a [`Encoder`] implementation might introduce
55/// new associated types in the future, and this [not yet supported] on a
56/// language level in Rust. So this attribute macro polyfills any missing types
57/// automatically.
58///
59/// [not yet supported]: https://rust-lang.github.io/rfcs/2532-associated-type-defaults.html
60///
61/// Note that if the `Cx` or `Mode` associated types are not specified, they
62/// will be defaulted to any type parameters which starts with the uppercase `C`
63/// or `M` respectively.
64///
65/// Note that using this macro directly from `musli_core` requires you to use
66/// the `#[musli_core::encoder(crate = musli_core)]` attribute.
67///
68/// # Examples
69///
70/// ```
71/// use std::fmt;
72/// use std::marker::PhantomData;
73///
74/// use musli::Context;
75/// use musli::en::{Encoder, Encode};
76///
77/// struct MyEncoder<'a, C, M> {
78///     value: &'a mut Option<u32>,
79///     cx: C,
80///     _marker: PhantomData<M>,
81/// }
82///
83/// #[musli::encoder]
84/// impl<C, M> Encoder for MyEncoder<'_, C, M>
85/// where
86///     C: Context,
87///     M: 'static,
88/// {
89///     #[inline]
90///     fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
91///         write!(f, "32-bit unsigned integers")
92///     }
93///
94///     #[inline]
95///     fn encode<T>(self, value: T) -> Result<(), C::Error>
96///     where
97///         T: Encode<Self::Mode>,
98///     {
99///         value.encode(self)
100///     }
101///
102///     #[inline]
103///     fn encode_u32(self, value: u32) -> Result<(), Self::Error> {
104///         *self.value = Some(value);
105///         Ok(())
106///     }
107/// }
108/// ```
109#[doc(inline)]
110pub use musli_core::__macros::encoder;
111
112#[doc(inline)]
113pub use musli_core::en::__traits::{
114    Encode, EncodeBytes, EncodePacked, EncodeTrace, Encoder, EntriesEncoder, EntryEncoder,
115    MapEncoder, SequenceEncoder, TryFastEncode, VariantEncoder,
116};
117
118#[cfg(any(
119    feature = "storage",
120    feature = "wire",
121    feature = "descriptive",
122    feature = "value"
123))]
124pub(crate) use musli_core::en::utils;
musli/en.rs

musli/
en.rs
