musli 0.2.1

Müsli is a flexible and efficient serialization framework.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

//! [`Context`] implementations.
//!
//! [`Context`]: crate::Context

mod access;
use self::access::{Access, Shared};

mod trace;
#[doc(inline)]
pub use self::trace::{Error, Errors, Location, NoTrace, Report, Trace, TraceImpl, TraceMode};

mod capture;
#[doc(inline)]
pub use self::capture::{Capture, Emit, ErrorMode, Ignore};

mod error_marker;
#[doc(inline)]
pub use self::error_marker::ErrorMarker;

mod default_context;
#[doc(inline)]
pub use self::default_context::{DEFAULT_NESTING_LIMIT, DefaultContext};

mod context_error;
#[doc(inline)]
pub use self::context_error::ContextError;

use crate::Allocator;
#[cfg(feature = "alloc")]
use crate::alloc::Global;

/// Construct a new default context using the [`Global`] allocator.
///
/// # Examples
///
/// ```
/// use musli::context;
///
/// musli::alloc::default(|alloc| {
///     let cx = context::new();
///     let encoding = musli::json::Encoding::new();
///     let string = encoding.to_string_with(&cx, &42)?;
///     assert_eq!(string, "42");
///     Ok(())
/// })?;
/// # Ok::<_, musli::context::ErrorMarker>(())
/// ```
#[cfg(feature = "alloc")]
#[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))]
#[inline]
pub fn new() -> DefaultContext<Global, NoTrace, Ignore> {
    DefaultContext::new()
}

/// Construct a new default context using the provided allocator.
///
/// # Examples
///
/// The `default` macro provides access to the default allocator. This is how it
/// can be used with this method:
///
/// ```
/// use musli::context;
///
/// musli::alloc::default(|alloc| {
///     let cx = context::new_in(alloc);
///     let encoding = musli::json::Encoding::new();
///     let string = encoding.to_string_with(&cx, &42)?;
///     assert_eq!(string, "42");
///     Ok(())
/// })?;
/// # Ok::<_, musli::context::ErrorMarker>(())
/// ```
///
/// We can also very conveniently set up an allocator which uses an existing
/// buffer:
///
/// ```
/// use musli::{alloc, context};
///
/// let mut buf = alloc::ArrayBuffer::new();
/// let alloc = alloc::Slice::new(&mut buf);
/// let cx = context::new_in(&alloc);
///
/// let encoding = musli::json::Encoding::new();
/// let string = encoding.to_string_with(&cx, &42)?;
/// assert_eq!(string, "42");
/// # Ok::<_, musli::context::ErrorMarker>(())
/// ```
#[inline]
pub fn new_in<A>(alloc: A) -> DefaultContext<A, NoTrace, Ignore>
where
    A: Allocator,
{
    DefaultContext::new_in(alloc)
}

/// Decode the contents of a nested container through `f`, one level of
/// nesting deeper.
///
/// The level is left whether or not `f` succeeds, so a context which is
/// reused after an error does not keep counting the levels which were active
/// when the error occurred.
#[cfg(any(
    feature = "storage",
    feature = "wire",
    feature = "descriptive",
    feature = "value",
    feature = "json",
    feature = "sqlite-jsonb",
    feature = "csv"
))]
#[inline(always)]
pub(crate) fn nested<C, O>(cx: C, f: impl FnOnce() -> Result<O, C::Error>) -> Result<O, C::Error>
where
    C: crate::Context,
{
    cx.enter_nesting()?;
    let result = f();
    cx.leave_nesting();
    result
}