abin 0.1.6

A library for working with binaries and strings. The library tries to avoid heap-allocations / memory-copy whenever possible by automatically choosing a reasonable strategy: stack for small binaries; static-lifetime-binary or reference-counting.
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

/// Returns the un-synchronized view of self.
///
/// See also `UnSyncRef` and `IntoUnSync`.
pub trait IntoUnSyncView {
    type Target;

    /// Returns the un-synchronized view of self.
    ///
    /// What does 'view' mean: The implementation is not really changed, just the interface is
    /// changed. It's still backed by a synchronized implementation.
    ///
    /// ```rust
    /// use abin::{SBin, NewSBin, BinFactory, IntoUnSyncView, Bin, AnyBin, IntoSync};
    /// let string = "This is some string; content of the binary.";
    /// let sync_bin : SBin = NewSBin::copy_from_slice(string.as_bytes());
    /// function_wants_bin(sync_bin.un_sync());
    ///
    /// fn function_wants_bin(value : Bin) {
    ///     // note: the 'value' here is still a synchronized binary (it just wrapped inside an
    ///     // un-synchronized view).
    ///     assert_eq!("This is some string; content of the binary.".as_bytes(), value.as_slice());
    ///     // we can also un-wrap it to be a synchronized bin again... in this case, this is
    ///     // a cheap operation (but it's not always a cheap operation).
    ///     let _synchronized_again : SBin = value.into_sync();
    /// }
    /// ```
    fn un_sync(self) -> Self::Target;
}

/// Returns the un-synchronized view of self (as reference).
///
/// See also `IntoUnSyncView` and `IntoUnSync`.
pub trait UnSyncRef {
    type Target;

    /// Returns the un-synchronized view of self (as reference).
    ///
    /// What does 'view' mean: The implementation is not really changed, just the interface is
    /// changed. It's still backed by a synchronized implementation.
    ///
    /// ```rust
    /// use abin::{NewSBin, SBin, BinFactory, UnSyncRef, Bin, AnyBin};
    /// let string = "This is some string; content of the binary.";
    /// let sync_bin : SBin = NewSBin::copy_from_slice(string.as_bytes());
    /// function_wants_bin(sync_bin.un_sync_ref());
    ///
    /// fn function_wants_bin(value : &Bin) {
    ///     // note: the 'value' here is still a synchronized binary (it just wrapped inside an
    ///     // un-synchronized view).
    ///     assert_eq!("This is some string; content of the binary.".as_bytes(), value.as_slice());
    /// }
    /// ```
    fn un_sync_ref(&self) -> &Self::Target;
}

/// Converts self into the un-synchronized version.
///
/// See also `IntoUnSyncView` and `UnSyncRef`.
pub trait IntoUnSync {
    type Target;

    /// Converts self into the un-synchronized version.
    ///
    /// Note: Unlike the `IntoUnSyncView` this does not always just return a view, it might
    /// actually change the backend (depending on the implementation). This operation
    /// might be expensive - depending on the implementation (for example a reference counted
    /// binary must clone its data if there are multiple references to that binary). So if
    /// there's no good reason to use this, better use the `IntoUnSyncView`.
    ///
    /// ```rust
    /// use abin::{NewSBin, SBin, BinFactory, Bin, IntoUnSync, AnyBin, IntoSync};
    /// let string = "This is some string; content of the binary.";
    /// let sync_bin : SBin = NewSBin::copy_from_slice(string.as_bytes());
    /// function_wants_bin(sync_bin.un_sync_convert());
    ///
    /// fn function_wants_bin(value : Bin) {
    ///     // note: The 'value' is no longer sync. E.g. the reference counter of this binary
    ///     // is no longer synchronized.
    ///     assert_eq!("This is some string; content of the binary.".as_bytes(), value.as_slice());
    ///     // we can also un-wrap it to be a synchronized bin again... in this case, this is
    ///     // a cheap operation (since there are no other references to `value`).
    ///     let _synchronized_again : SBin = value.into_sync();
    /// }
    /// ```
    fn un_sync_convert(self) -> Self::Target;
}