musli_core/en/
mod.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//! Note that using derives directly from `musli_core` requires you to use the
10//! `#[musli(crate = musli_core)]` attribute.
11//!
12//! # Examples
13//!
14//! ```
15//! use musli_core::Encode;
16//!
17//! #[derive(Encode)]
18//! #[musli(crate = musli_core)]
19//! pub struct Person<'a> {
20//!     name: &'a str,
21//!     age: u32,
22//! }
23//! ```
24
25/// Derive which automatically implements the [`Encode` trait].
26///
27/// See the [`derives` module] for detailed documentation.
28///
29/// [`derives` module]: <https://docs.rs/musli/latest/musli/_help/derives/index.html>
30/// [`Encode` trait]: <https://docs.rs/musli/latest/musli/trait.Encode.html>
31///
32/// # Examples
33///
34/// ```
35/// use musli::Encode;
36///
37/// #[derive(Encode)]
38/// struct MyType {
39///     data: [u8; 128],
40/// }
41/// ```
42///
43/// When using through `musli_core`, the crate needs to be specified:
44///
45/// ```
46/// use musli_core::Encode;
47///
48/// #[derive(Encode)]
49/// #[musli(crate = musli_core)]
50/// struct MyType {
51///     data: [u8; 128],
52/// }
53/// ```
54#[doc(inline)]
55pub use musli_macros::Encode;
56
57/// This is an attribute macro that must be used when implementing a
58/// [`Encoder`].
59///
60/// It is required to use because a [`Encoder`] implementation might introduce
61/// new associated types in the future, and this [not yet supported] on a
62/// language level in Rust. So this attribute macro polyfills any missing types
63/// automatically.
64///
65/// [not yet supported]: https://rust-lang.github.io/rfcs/2532-associated-type-defaults.html
66///
67/// Note that if the `Cx` or `Mode` associated types are not specified, they
68/// will be defaulted to any type parameters which starts with the uppercase `C`
69/// or `M` respectively.
70///
71/// Note that using this macro directly from `musli_core` requires you to use
72/// the `#[musli_core::encoder(crate = musli_core)]` attribute.
73///
74/// # Examples
75///
76/// ```
77/// use std::fmt;
78/// use std::marker::PhantomData;
79///
80/// use musli_core::Context;
81/// use musli_core::en::{Encoder, Encode};
82///
83/// struct MyEncoder<'a, C, M> {
84///     value: &'a mut Option<u32>,
85///     cx: C,
86///     _marker: PhantomData<M>,
87/// }
88///
89/// #[musli_core::encoder(crate = musli_core)]
90/// impl<C, M> Encoder for MyEncoder<'_, C, M>
91/// where
92///     C: Context,
93///     M: 'static,
94/// {
95///     #[inline]
96///     fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
97///         write!(f, "32-bit unsigned integers")
98///     }
99///
100///     #[inline]
101///     fn encode<T>(self, value: T) -> Result<(), C::Error>
102///     where
103///         T: Encode<Self::Mode>,
104///     {
105///         value.encode(self)
106///     }
107///
108///     #[inline]
109///     fn encode_u32(self, value: u32) -> Result<(), Self::Error> {
110///         *self.value = Some(value);
111///         Ok(())
112///     }
113/// }
114/// ```
115#[doc(inline)]
116pub use musli_macros::encoder;
117
118#[doc(inline)]
119pub use self::__traits::*;
120
121mod encode;
122mod encode_bytes;
123mod encode_packed;
124mod encode_trace;
125mod encoder;
126mod entries_encoder;
127mod entry_encoder;
128mod map_encoder;
129mod sequence_encoder;
130mod variant_encoder;
131
132#[doc(hidden)]
133pub mod __traits {
134    pub use super::encode::Encode;
135    pub use super::encode_bytes::EncodeBytes;
136    pub use super::encode_packed::EncodePacked;
137    pub use super::encode_trace::EncodeTrace;
138    pub use super::encoder::{Encoder, TryFastEncode};
139    pub use super::entries_encoder::EntriesEncoder;
140    pub use super::entry_encoder::EntryEncoder;
141    pub use super::map_encoder::MapEncoder;
142    pub use super::sequence_encoder::SequenceEncoder;
143    pub use super::variant_encoder::VariantEncoder;
144}
145
146#[doc(hidden)]
147pub mod utils;
musli_core/en/mod.rs

musli_core/en/
mod.rs
