slice_codec/buffer/
mod.rs

1// Copyright (c) ZeroC, Inc.
2
3//! TODO maybe write a comment explaining this module?
4
5pub mod slice;
6
7#[cfg(feature = "alloc")]
8pub mod vec;
9
10use crate::Result;
11use core::ops::Range;
12
13/// A trait for types that can be read from by a [Slice decoder](crate::decoder::Decoder).
14pub trait InputSource {
15    /// Returns the number of unread bytes currently remaining in the source.
16    fn remaining(&self) -> usize;
17
18    /// Returns the next byte available from this source without consuming it.
19    ///
20    /// If there are no more bytes available from this source, an [`UnexpectedEob`] error is returned instead.
21    ///
22    /// [`UnexpectedEob`]: crate::ErrorKind::UnexpectedEob
23    fn peek_byte(&mut self) -> Result<u8>;
24
25    /// Returns the next byte available from this source, and advances past it (consuming it).
26    ///
27    /// If there are no more bytes available from this source, an [`UnexpectedEob`] error is returned instead.
28    ///
29    /// [`UnexpectedEob`]: crate::ErrorKind::UnexpectedEob
30    fn read_byte(&mut self) -> Result<u8>;
31
32    // TODO these 4 functions need comments.
33    // TODO remove any of these functions that don't end up being used anywhere.
34    fn peek_bytes_exact<const N: usize>(&mut self) -> Result<&[u8; N]>;
35    fn read_bytes_exact<const N: usize>(&mut self) -> Result<&[u8; N]>;
36
37    fn peek_byte_slice_exact(&mut self, count: usize) -> Result<&[u8]>;
38    fn read_byte_slice_exact(&mut self, count: usize) -> Result<&[u8]>;
39
40    /// Reads bytes from this source into the provided buffer, and advances past them (consuming them).
41    ///
42    /// This function reads exactly `dest.len()`-many bytes, or if it's unable to, returns an error instead.
43    /// If such an error occurs, no guarantees are made about how many bytes were read from the source, except that it
44    /// is less than `dest.len()`.
45    fn read_bytes_into_exact(&mut self, dest: &mut [u8]) -> Result<()>;
46}
47
48/// A trait for types that can be written to by a [Slice encoder](crate::encoder::Encoder).
49pub trait OutputTarget {
50    /// Returns the number of unwritten bytes currently remaining in the target.
51    ///
52    /// Note: some implementations are capable of growing their underlying buffers as needed. For these implementations,
53    /// this function returns how many bytes can be written _without needing to grow_ ie. "... currently remaining ...".
54    /// For these types, it's generally safe to write more than `remaining()` bytes to the target, since it will simply
55    /// grow as needed. But these writes can still fail if an allocation error occurs.
56    fn remaining(&self) -> usize;
57
58    /// Attempts to write the provided byte into this target.
59    fn write_byte(&mut self, byte: u8) -> Result<()>;
60
61    /// Attempts to write the provided bytes into this target.
62    ///
63    /// This function will not return until either all the provided bytes have been written, or an unrecoverable error
64    /// has occurred. If such an error occurs, no guarantees are made about how many bytes were written, or the state
65    /// of the underlying target.
66    fn write_bytes_exact(&mut self, bytes: &[u8]) -> Result<()>;
67
68    /// Attempts to write the provided bytes into a reserved chunk of memory within this target.
69    ///
70    /// This is used alongside [`Self::reserve_space`] to write data into the target without appending it at the end.
71    /// However, this function cannot be used to write to arbitrary positions in the target; reservations must be made
72    /// in advance.
73    ///
74    /// It is legal to call this function multiple times with the same [`Reservation`], but as bytes are written,
75    /// the reservation will be shrunk accordingly (starting from the front) to ensure bytes are never over-written.
76    ///
77    /// Like [`Self::write_bytes_exact`], this function will not return until either all the provided bytes have been
78    /// written, or an unrecoverable error has occurred. If such an error occurs, no guarantees are made about how many
79    /// bytes were written, or the state of the underlying target.
80    fn write_bytes_into_reserved_exact(&mut self, reservation: &mut Reservation, bytes: &[u8]) -> Result<()>;
81
82    /// Reserves a chunk of memory in the target that can be written to later, and advances past it.
83    ///
84    /// The target's cursor is advanced by `count`-many bytes (so it points to the end of the reservation) meaning
85    /// additional writes to this target will continue normally outside the reserved memory.
86    ///
87    /// It returns a typed range ([`Reservation`]) specifying the beginning and end of this reserved memory. This memory
88    /// can written to later by passing the returned [`Reservation`] into [`Self::write_bytes_into_reserved_exact`].
89    ///
90    /// If the underlying target has insufficient memory (and couldn't allocate more) an error is returned instead.
91    fn reserve_space(&mut self, count: usize) -> Result<Reservation>;
92}
93
94/// Represents a span of bytes that have been reserved in an [`OutputTarget`].
95/// See [`OutputTarget::reserve_space`].
96#[derive(Debug)]
97#[must_use]
98pub struct Reservation(Range<usize>);
99
100impl Reservation {
101    /// Returns a [`Range`] corresponding to the byte positions held by this [`Reservation`].
102    fn range(&self) -> Range<usize> {
103        self.0.clone()
104    }
105}
slice_codec/buffer/mod.rs

slice_codec/buffer/
mod.rs
