scroll 0.13.0

A suite of powerful, extensible, generic, endian-aware Read/Write traits for byte buffers
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

use core::result;

use crate::ctx::TryIntoCtx;
use crate::error;

/// A very generic, contextual pwrite interface in Rust.
///
/// Like [Pread](trait.Pread.html) — but for writing!
///
/// Implementing `Pwrite` on a data store allows you to then write almost arbitrarily complex types
/// efficiently.
///
/// To this end the Pwrite trait works in conjuction with the [TryIntoCtx](ctx/trait.TryIntoCtx.html);
/// The `TryIntoCtx` trait implemented on a type defines how to convert said type into data that
/// an implementation of Pwrite can … well … write.
///
/// As with [Pread](trait.Pread.html) 'data' does not necessarily mean `&[u8]` but can be any
/// indexable type. In fact much of the documentation of `Pread` applies to `Pwrite` as well just
/// with 'read' switched for 'write' and 'From' switched with 'Into' so if you haven't yet you
/// should read the documentation of `Pread` first.
///
/// As with `Pread`, note that in the particular case of the implementation of `Pwrite` for `[u8]`,
/// writing it at the length boundary of that slice will cause to write in an empty slice.
/// i.e. we make use of the fact that `&bytes[bytes.len()..]` will return an empty slice, rather
/// than returning an error. In the past, scroll returned an offset error.
/// In this case, this is relevant if you are writing an empty slice inside an empty slice and
/// expected this to work.
///
/// Unless you need to implement your own data store — that is either can't convert to `&[u8]` or
/// have a data that does not expose a `&mut [u8]` — you will probably want to implement
/// [TryIntoCtx](ctx/trait.TryIntoCtx.html) on your Rust types to be written.
///
pub trait Pwrite<Ctx: Copy, E> {
    #[inline]
    fn pwrite<N: TryIntoCtx<Ctx, Self, Error = E>>(
        &mut self,
        n: N,
        offset: usize,
    ) -> result::Result<usize, E>
    where
        Ctx: Default,
    {
        self.pwrite_with(n, offset, Ctx::default())
    }

    /// Write `N` at offset `I` with context `Ctx`
    /// # Example
    /// ```
    /// use scroll::{Pwrite, Pread, LE};
    /// let mut bytes: [u8; 8] = [0, 0, 0, 0, 0, 0, 0, 0];
    /// bytes.pwrite_with::<u32>(0xbeefbeef, 0, LE).unwrap();
    /// assert_eq!(bytes.pread_with::<u32>(0, LE).unwrap(), 0xbeefbeef);
    fn pwrite_with<N: TryIntoCtx<Ctx, Self, Error = E>>(
        &mut self,
        n: N,
        offset: usize,
        ctx: Ctx,
    ) -> result::Result<usize, E>;

    /// Write `n` into `self` at `offset`, with a default `Ctx`. Updates the offset.
    #[inline]
    fn gwrite<N: TryIntoCtx<Ctx, Self, Error = E>>(
        &mut self,
        n: N,
        offset: &mut usize,
    ) -> result::Result<usize, E>
    where
        Ctx: Default,
    {
        let ctx = Ctx::default();
        self.gwrite_with(n, offset, ctx)
    }

    /// Write `n` into `self` at `offset`, with the `ctx`. Updates the offset.
    #[inline]
    fn gwrite_with<N: TryIntoCtx<Ctx, Self, Error = E>>(
        &mut self,
        n: N,
        offset: &mut usize,
        ctx: Ctx,
    ) -> result::Result<usize, E> {
        let o = *offset;
        self.pwrite_with(n, o, ctx).map(|size| {
            *offset += size;
            size
        })
    }
}

impl<Ctx: Copy, E: From<error::Error>> Pwrite<Ctx, E> for [u8] {
    fn pwrite_with<N: TryIntoCtx<Ctx, Self, Error = E>>(
        &mut self,
        n: N,
        offset: usize,
        ctx: Ctx,
    ) -> result::Result<usize, E> {
        if offset > self.len() {
            return Err(error::Error::BadOffset(offset).into());
        }
        let dst = &mut self[offset..];
        n.try_into_ctx(dst, ctx)
    }
}