#
bytes/buf/
buf_mut.rs

    1use crate::buf::{limit, Chain, Limit, UninitSlice};
    2#[cfg(feature = "std")]
    3use crate::buf::{writer, Writer};
    4use crate::{panic_advance, panic_does_not_fit, TryGetError};
    5
    6use core::{mem, ptr};
    7
    8use alloc::{boxed::Box, vec::Vec};
    9
    10/// A trait for values that provide sequential write access to bytes.
    11///
    12/// Write bytes to a buffer
    13///
    14/// A buffer stores bytes in memory such that write operations are infallible.
    15/// The underlying storage may or may not be in contiguous memory. A `BufMut`
    16/// value is a cursor into the buffer. Writing to `BufMut` advances the cursor
    17/// position.
    18///
    19/// The simplest `BufMut` is a `Vec<u8>`.
    20///
    21/// ```
    22/// use bytes::BufMut;
    23///
    24/// let mut buf = vec![];
    25///
    26/// buf.put(&b"hello world"[..]);
    27///
    28/// assert_eq!(buf, b"hello world");
    29/// ```
    30pub unsafe trait BufMut {
    31    /// Returns the number of bytes that can be written from the current
    32    /// position until the end of the buffer is reached.
    33    ///
    34    /// This value is greater than or equal to the length of the slice returned
    35    /// by `chunk_mut()`.
    36    ///
    37    /// Writing to a `BufMut` may involve allocating more memory on the fly.
    38    /// Implementations may fail before reaching the number of bytes indicated
    39    /// by this method if they encounter an allocation failure.
    40    ///
    41    /// # Examples
    42    ///
    43    /// ```
    44    /// use bytes::BufMut;
    45    ///
    46    /// let mut dst = [0; 10];
    47    /// let mut buf = &mut dst[..];
    48    ///
    49    /// let original_remaining = buf.remaining_mut();
    50    /// buf.put(&b"hello"[..]);
    51    ///
    52    /// assert_eq!(original_remaining - 5, buf.remaining_mut());
    53    /// ```
    54    ///
    55    /// # Implementer notes
    56    ///
    57    /// Implementations of `remaining_mut` should ensure that the return value
    58    /// does not change unless a call is made to `advance_mut` or any other
    59    /// function that is documented to change the `BufMut`'s current position.
    60    ///
    61    /// # Note
    62    ///
    63    /// `remaining_mut` may return value smaller than actual available space.
    64    fn remaining_mut(&self) -> usize;
    65
    66    /// Advance the internal cursor of the BufMut
    67    ///
    68    /// The next call to `chunk_mut` will return a slice starting `cnt` bytes
    69    /// further into the underlying buffer.
    70    ///
    71    /// # Safety
    72    ///
    73    /// The caller must ensure that the next `cnt` bytes of `chunk` are
    74    /// initialized.
    75    ///
    76    /// # Examples
    77    ///
    78    /// ```
    79    /// use bytes::BufMut;
    80    ///
    81    /// let mut buf = Vec::with_capacity(16);
    82    ///
    83    /// // Write some data
    84    /// buf.chunk_mut()[0..2].copy_from_slice(b"he");
    85    /// unsafe { buf.advance_mut(2) };
    86    ///
    87    /// // write more bytes
    88    /// buf.chunk_mut()[0..3].copy_from_slice(b"llo");
    89    ///
    90    /// unsafe { buf.advance_mut(3); }
    91    ///
    92    /// assert_eq!(5, buf.len());
    93    /// assert_eq!(buf, b"hello");
    94    /// ```
    95    ///
    96    /// # Panics
    97    ///
    98    /// This function **may** panic if `cnt > self.remaining_mut()`.
    99    ///
    100    /// # Implementer notes
    101    ///
    102    /// It is recommended for implementations of `advance_mut` to panic if
    103    /// `cnt > self.remaining_mut()`. If the implementation does not panic,
    104    /// the call must behave as if `cnt == self.remaining_mut()`.
    105    ///
    106    /// A call with `cnt == 0` should never panic and be a no-op.
    107    unsafe fn advance_mut(&mut self, cnt: usize);
    108
    109    /// Returns true if there is space in `self` for more bytes.
    110    ///
    111    /// This is equivalent to `self.remaining_mut() != 0`.
    112    ///
    113    /// # Examples
    114    ///
    115    /// ```
    116    /// use bytes::BufMut;
    117    ///
    118    /// let mut dst = [0; 5];
    119    /// let mut buf = &mut dst[..];
    120    ///
    121    /// assert!(buf.has_remaining_mut());
    122    ///
    123    /// buf.put(&b"hello"[..]);
    124    ///
    125    /// assert!(!buf.has_remaining_mut());
    126    /// ```
    127    #[inline]
    128    fn has_remaining_mut(&self) -> bool {
    129        self.remaining_mut() > 0
    130    }
    131
    132    /// Returns a mutable slice starting at the current BufMut position and of
    133    /// length between 0 and `BufMut::remaining_mut()`. Note that this *can* be shorter than the
    134    /// whole remainder of the buffer (this allows non-continuous implementation).
    135    ///
    136    /// This is a lower level function. Most operations are done with other
    137    /// functions.
    138    ///
    139    /// The returned byte slice may represent uninitialized memory.
    140    ///
    141    /// # Examples
    142    ///
    143    /// ```
    144    /// use bytes::BufMut;
    145    ///
    146    /// let mut buf = Vec::with_capacity(16);
    147    ///
    148    /// unsafe {
    149    ///     // MaybeUninit::as_mut_ptr
    150    ///     buf.chunk_mut()[0..].as_mut_ptr().write(b'h');
    151    ///     buf.chunk_mut()[1..].as_mut_ptr().write(b'e');
    152    ///
    153    ///     buf.advance_mut(2);
    154    ///
    155    ///     buf.chunk_mut()[0..].as_mut_ptr().write(b'l');
    156    ///     buf.chunk_mut()[1..].as_mut_ptr().write(b'l');
    157    ///     buf.chunk_mut()[2..].as_mut_ptr().write(b'o');
    158    ///
    159    ///     buf.advance_mut(3);
    160    /// }
    161    ///
    162    /// assert_eq!(5, buf.len());
    163    /// assert_eq!(buf, b"hello");
    164    /// ```
    165    ///
    166    /// # Implementer notes
    167    ///
    168    /// This function should never panic. `chunk_mut()` should return an empty
    169    /// slice **if and only if** `remaining_mut()` returns 0. In other words,
    170    /// `chunk_mut()` returning an empty slice implies that `remaining_mut()` will
    171    /// return 0 and `remaining_mut()` returning 0 implies that `chunk_mut()` will
    172    /// return an empty slice.
    173    ///
    174    /// This function may trigger an out-of-memory abort if it tries to allocate
    175    /// memory and fails to do so.
    176    // The `chunk_mut` method was previously called `bytes_mut`. This alias makes the
    177    // rename more easily discoverable.
    178    #[cfg_attr(docsrs, doc(alias = "bytes_mut"))]
    179    fn chunk_mut(&mut self) -> &mut UninitSlice;
    180
    181    /// Transfer bytes into `self` from `src` and advance the cursor by the
    182    /// number of bytes written.
    183    ///
    184    /// # Examples
    185    ///
    186    /// ```
    187    /// use bytes::BufMut;
    188    ///
    189    /// let mut buf = vec![];
    190    ///
    191    /// buf.put_u8(b'h');
    192    /// buf.put(&b"ello"[..]);
    193    /// buf.put(&b" world"[..]);
    194    ///
    195    /// assert_eq!(buf, b"hello world");
    196    /// ```
    197    ///
    198    /// # Panics
    199    ///
    200    /// Panics if `self` does not have enough capacity to contain `src`.
    201    #[inline]
    202    fn put<T: super::Buf>(&mut self, mut src: T)
    203    where
    204        Self: Sized,
    205    {
    206        if self.remaining_mut() < src.remaining() {
    207            panic_advance(&TryGetError {
    208                requested: src.remaining(),
    209                available: self.remaining_mut(),
    210            });
    211        }
    212
    213        while src.has_remaining() {
    214            let s = src.chunk();
    215            let d = self.chunk_mut();
    216            let cnt = usize::min(s.len(), d.len());
    217
    218            d[..cnt].copy_from_slice(&s[..cnt]);
    219
    220            // SAFETY: We just initialized `cnt` bytes in `self`.
    221            unsafe { self.advance_mut(cnt) };
    222            src.advance(cnt);
    223        }
    224    }
    225
    226    /// Transfer bytes into `self` from `src` and advance the cursor by the
    227    /// number of bytes written.
    228    ///
    229    /// `self` must have enough remaining capacity to contain all of `src`.
    230    ///
    231    /// ```
    232    /// use bytes::BufMut;
    233    ///
    234    /// let mut dst = [0; 6];
    235    ///
    236    /// {
    237    ///     let mut buf = &mut dst[..];
    238    ///     buf.put_slice(b"hello");
    239    ///
    240    ///     assert_eq!(1, buf.remaining_mut());
    241    /// }
    242    ///
    243    /// assert_eq!(b"hello\0", &dst);
    244    /// ```
    245    #[inline]
    246    fn put_slice(&mut self, mut src: &[u8]) {
    247        if self.remaining_mut() < src.len() {
    248            panic_advance(&TryGetError {
    249                requested: src.len(),
    250                available: self.remaining_mut(),
    251            });
    252        }
    253
    254        while !src.is_empty() {
    255            let dst = self.chunk_mut();
    256            let cnt = usize::min(src.len(), dst.len());
    257
    258            dst[..cnt].copy_from_slice(&src[..cnt]);
    259            src = &src[cnt..];
    260
    261            // SAFETY: We just initialized `cnt` bytes in `self`.
    262            unsafe { self.advance_mut(cnt) };
    263        }
    264    }
    265
    266    /// Put `cnt` bytes `val` into `self`.
    267    ///
    268    /// Logically equivalent to calling `self.put_u8(val)` `cnt` times, but may work faster.
    269    ///
    270    /// `self` must have at least `cnt` remaining capacity.
    271    ///
    272    /// ```
    273    /// use bytes::BufMut;
    274    ///
    275    /// let mut dst = [0; 6];
    276    ///
    277    /// {
    278    ///     let mut buf = &mut dst[..];
    279    ///     buf.put_bytes(b'a', 4);
    280    ///
    281    ///     assert_eq!(2, buf.remaining_mut());
    282    /// }
    283    ///
    284    /// assert_eq!(b"aaaa\0\0", &dst);
    285    /// ```
    286    ///
    287    /// # Panics
    288    ///
    289    /// This function panics if there is not enough remaining capacity in
    290    /// `self`.
    291    #[inline]
    292    fn put_bytes(&mut self, val: u8, mut cnt: usize) {
    293        if self.remaining_mut() < cnt {
    294            panic_advance(&TryGetError {
    295                requested: cnt,
    296                available: self.remaining_mut(),
    297            })
    298        }
    299
    300        while cnt > 0 {
    301            let dst = self.chunk_mut();
    302            let dst_len = usize::min(dst.len(), cnt);
    303            // SAFETY: The pointer is valid for `dst_len <= dst.len()` bytes.
    304            unsafe { core::ptr::write_bytes(dst.as_mut_ptr(), val, dst_len) };
    305            // SAFETY: We just initialized `dst_len` bytes in `self`.
    306            unsafe { self.advance_mut(dst_len) };
    307            cnt -= dst_len;
    308        }
    309    }
    310
    311    /// Writes an unsigned 8 bit integer to `self`.
    312    ///
    313    /// The current position is advanced by 1.
    314    ///
    315    /// # Examples
    316    ///
    317    /// ```
    318    /// use bytes::BufMut;
    319    ///
    320    /// let mut buf = vec![];
    321    /// buf.put_u8(0x01);
    322    /// assert_eq!(buf, b"\x01");
    323    /// ```
    324    ///
    325    /// # Panics
    326    ///
    327    /// This function panics if there is not enough remaining capacity in
    328    /// `self`.
    329    #[inline]
    330    fn put_u8(&mut self, n: u8) {
    331        let src = [n];
    332        self.put_slice(&src);
    333    }
    334
    335    /// Writes a signed 8 bit integer to `self`.
    336    ///
    337    /// The current position is advanced by 1.
    338    ///
    339    /// # Examples
    340    ///
    341    /// ```
    342    /// use bytes::BufMut;
    343    ///
    344    /// let mut buf = vec![];
    345    /// buf.put_i8(0x01);
    346    /// assert_eq!(buf, b"\x01");
    347    /// ```
    348    ///
    349    /// # Panics
    350    ///
    351    /// This function panics if there is not enough remaining capacity in
    352    /// `self`.
    353    #[inline]
    354    fn put_i8(&mut self, n: i8) {
    355        let src = [n as u8];
    356        self.put_slice(&src)
    357    }
    358
    359    /// Writes an unsigned 16 bit integer to `self` in big-endian byte order.
    360    ///
    361    /// The current position is advanced by 2.
    362    ///
    363    /// # Examples
    364    ///
    365    /// ```
    366    /// use bytes::BufMut;
    367    ///
    368    /// let mut buf = vec![];
    369    /// buf.put_u16(0x0809);
    370    /// assert_eq!(buf, b"\x08\x09");
    371    /// ```
    372    ///
    373    /// # Panics
    374    ///
    375    /// This function panics if there is not enough remaining capacity in
    376    /// `self`.
    377    #[inline]
    378    fn put_u16(&mut self, n: u16) {
    379        self.put_slice(&n.to_be_bytes())
    380    }
    381
    382    /// Writes an unsigned 16 bit integer to `self` in little-endian byte order.
    383    ///
    384    /// The current position is advanced by 2.
    385    ///
    386    /// # Examples
    387    ///
    388    /// ```
    389    /// use bytes::BufMut;
    390    ///
    391    /// let mut buf = vec![];
    392    /// buf.put_u16_le(0x0809);
    393    /// assert_eq!(buf, b"\x09\x08");
    394    /// ```
    395    ///
    396    /// # Panics
    397    ///
    398    /// This function panics if there is not enough remaining capacity in
    399    /// `self`.
    400    #[inline]
    401    fn put_u16_le(&mut self, n: u16) {
    402        self.put_slice(&n.to_le_bytes())
    403    }
    404
    405    /// Writes an unsigned 16 bit integer to `self` in native-endian byte order.
    406    ///
    407    /// The current position is advanced by 2.
    408    ///
    409    /// # Examples
    410    ///
    411    /// ```
    412    /// use bytes::BufMut;
    413    ///
    414    /// let mut buf = vec![];
    415    /// buf.put_u16_ne(0x0809);
    416    /// if cfg!(target_endian = "big") {
    417    ///     assert_eq!(buf, b"\x08\x09");
    418    /// } else {
    419    ///     assert_eq!(buf, b"\x09\x08");
    420    /// }
    421    /// ```
    422    ///
    423    /// # Panics
    424    ///
    425    /// This function panics if there is not enough remaining capacity in
    426    /// `self`.
    427    #[inline]
    428    fn put_u16_ne(&mut self, n: u16) {
    429        self.put_slice(&n.to_ne_bytes())
    430    }
    431
    432    /// Writes a signed 16 bit integer to `self` in big-endian byte order.
    433    ///
    434    /// The current position is advanced by 2.
    435    ///
    436    /// # Examples
    437    ///
    438    /// ```
    439    /// use bytes::BufMut;
    440    ///
    441    /// let mut buf = vec![];
    442    /// buf.put_i16(0x0809);
    443    /// assert_eq!(buf, b"\x08\x09");
    444    /// ```
    445    ///
    446    /// # Panics
    447    ///
    448    /// This function panics if there is not enough remaining capacity in
    449    /// `self`.
    450    #[inline]
    451    fn put_i16(&mut self, n: i16) {
    452        self.put_slice(&n.to_be_bytes())
    453    }
    454
    455    /// Writes a signed 16 bit integer to `self` in little-endian byte order.
    456    ///
    457    /// The current position is advanced by 2.
    458    ///
    459    /// # Examples
    460    ///
    461    /// ```
    462    /// use bytes::BufMut;
    463    ///
    464    /// let mut buf = vec![];
    465    /// buf.put_i16_le(0x0809);
    466    /// assert_eq!(buf, b"\x09\x08");
    467    /// ```
    468    ///
    469    /// # Panics
    470    ///
    471    /// This function panics if there is not enough remaining capacity in
    472    /// `self`.
    473    #[inline]
    474    fn put_i16_le(&mut self, n: i16) {
    475        self.put_slice(&n.to_le_bytes())
    476    }
    477
    478    /// Writes a signed 16 bit integer to `self` in native-endian byte order.
    479    ///
    480    /// The current position is advanced by 2.
    481    ///
    482    /// # Examples
    483    ///
    484    /// ```
    485    /// use bytes::BufMut;
    486    ///
    487    /// let mut buf = vec![];
    488    /// buf.put_i16_ne(0x0809);
    489    /// if cfg!(target_endian = "big") {
    490    ///     assert_eq!(buf, b"\x08\x09");
    491    /// } else {
    492    ///     assert_eq!(buf, b"\x09\x08");
    493    /// }
    494    /// ```
    495    ///
    496    /// # Panics
    497    ///
    498    /// This function panics if there is not enough remaining capacity in
    499    /// `self`.
    500    #[inline]
    501    fn put_i16_ne(&mut self, n: i16) {
    502        self.put_slice(&n.to_ne_bytes())
    503    }
    504
    505    /// Writes an unsigned 32 bit integer to `self` in big-endian byte order.
    506    ///
    507    /// The current position is advanced by 4.
    508    ///
    509    /// # Examples
    510    ///
    511    /// ```
    512    /// use bytes::BufMut;
    513    ///
    514    /// let mut buf = vec![];
    515    /// buf.put_u32(0x0809A0A1);
    516    /// assert_eq!(buf, b"\x08\x09\xA0\xA1");
    517    /// ```
    518    ///
    519    /// # Panics
    520    ///
    521    /// This function panics if there is not enough remaining capacity in
    522    /// `self`.
    523    #[inline]
    524    fn put_u32(&mut self, n: u32) {
    525        self.put_slice(&n.to_be_bytes())
    526    }
    527
    528    /// Writes an unsigned 32 bit integer to `self` in little-endian byte order.
    529    ///
    530    /// The current position is advanced by 4.
    531    ///
    532    /// # Examples
    533    ///
    534    /// ```
    535    /// use bytes::BufMut;
    536    ///
    537    /// let mut buf = vec![];
    538    /// buf.put_u32_le(0x0809A0A1);
    539    /// assert_eq!(buf, b"\xA1\xA0\x09\x08");
    540    /// ```
    541    ///
    542    /// # Panics
    543    ///
    544    /// This function panics if there is not enough remaining capacity in
    545    /// `self`.
    546    #[inline]
    547    fn put_u32_le(&mut self, n: u32) {
    548        self.put_slice(&n.to_le_bytes())
    549    }
    550
    551    /// Writes an unsigned 32 bit integer to `self` in native-endian byte order.
    552    ///
    553    /// The current position is advanced by 4.
    554    ///
    555    /// # Examples
    556    ///
    557    /// ```
    558    /// use bytes::BufMut;
    559    ///
    560    /// let mut buf = vec![];
    561    /// buf.put_u32_ne(0x0809A0A1);
    562    /// if cfg!(target_endian = "big") {
    563    ///     assert_eq!(buf, b"\x08\x09\xA0\xA1");
    564    /// } else {
    565    ///     assert_eq!(buf, b"\xA1\xA0\x09\x08");
    566    /// }
    567    /// ```
    568    ///
    569    /// # Panics
    570    ///
    571    /// This function panics if there is not enough remaining capacity in
    572    /// `self`.
    573    #[inline]
    574    fn put_u32_ne(&mut self, n: u32) {
    575        self.put_slice(&n.to_ne_bytes())
    576    }
    577
    578    /// Writes a signed 32 bit integer to `self` in big-endian byte order.
    579    ///
    580    /// The current position is advanced by 4.
    581    ///
    582    /// # Examples
    583    ///
    584    /// ```
    585    /// use bytes::BufMut;
    586    ///
    587    /// let mut buf = vec![];
    588    /// buf.put_i32(0x0809A0A1);
    589    /// assert_eq!(buf, b"\x08\x09\xA0\xA1");
    590    /// ```
    591    ///
    592    /// # Panics
    593    ///
    594    /// This function panics if there is not enough remaining capacity in
    595    /// `self`.
    596    #[inline]
    597    fn put_i32(&mut self, n: i32) {
    598        self.put_slice(&n.to_be_bytes())
    599    }
    600
    601    /// Writes a signed 32 bit integer to `self` in little-endian byte order.
    602    ///
    603    /// The current position is advanced by 4.
    604    ///
    605    /// # Examples
    606    ///
    607    /// ```
    608    /// use bytes::BufMut;
    609    ///
    610    /// let mut buf = vec![];
    611    /// buf.put_i32_le(0x0809A0A1);
    612    /// assert_eq!(buf, b"\xA1\xA0\x09\x08");
    613    /// ```
    614    ///
    615    /// # Panics
    616    ///
    617    /// This function panics if there is not enough remaining capacity in
    618    /// `self`.
    619    #[inline]
    620    fn put_i32_le(&mut self, n: i32) {
    621        self.put_slice(&n.to_le_bytes())
    622    }
    623
    624    /// Writes a signed 32 bit integer to `self` in native-endian byte order.
    625    ///
    626    /// The current position is advanced by 4.
    627    ///
    628    /// # Examples
    629    ///
    630    /// ```
    631    /// use bytes::BufMut;
    632    ///
    633    /// let mut buf = vec![];
    634    /// buf.put_i32_ne(0x0809A0A1);
    635    /// if cfg!(target_endian = "big") {
    636    ///     assert_eq!(buf, b"\x08\x09\xA0\xA1");
    637    /// } else {
    638    ///     assert_eq!(buf, b"\xA1\xA0\x09\x08");
    639    /// }
    640    /// ```
    641    ///
    642    /// # Panics
    643    ///
    644    /// This function panics if there is not enough remaining capacity in
    645    /// `self`.
    646    #[inline]
    647    fn put_i32_ne(&mut self, n: i32) {
    648        self.put_slice(&n.to_ne_bytes())
    649    }
    650
    651    /// Writes an unsigned 64 bit integer to `self` in the big-endian byte order.
    652    ///
    653    /// The current position is advanced by 8.
    654    ///
    655    /// # Examples
    656    ///
    657    /// ```
    658    /// use bytes::BufMut;
    659    ///
    660    /// let mut buf = vec![];
    661    /// buf.put_u64(0x0102030405060708);
    662    /// assert_eq!(buf, b"\x01\x02\x03\x04\x05\x06\x07\x08");
    663    /// ```
    664    ///
    665    /// # Panics
    666    ///
    667    /// This function panics if there is not enough remaining capacity in
    668    /// `self`.
    669    #[inline]
    670    fn put_u64(&mut self, n: u64) {
    671        self.put_slice(&n.to_be_bytes())
    672    }
    673
    674    /// Writes an unsigned 64 bit integer to `self` in little-endian byte order.
    675    ///
    676    /// The current position is advanced by 8.
    677    ///
    678    /// # Examples
    679    ///
    680    /// ```
    681    /// use bytes::BufMut;
    682    ///
    683    /// let mut buf = vec![];
    684    /// buf.put_u64_le(0x0102030405060708);
    685    /// assert_eq!(buf, b"\x08\x07\x06\x05\x04\x03\x02\x01");
    686    /// ```
    687    ///
    688    /// # Panics
    689    ///
    690    /// This function panics if there is not enough remaining capacity in
    691    /// `self`.
    692    #[inline]
    693    fn put_u64_le(&mut self, n: u64) {
    694        self.put_slice(&n.to_le_bytes())
    695    }
    696
    697    /// Writes an unsigned 64 bit integer to `self` in native-endian byte order.
    698    ///
    699    /// The current position is advanced by 8.
    700    ///
    701    /// # Examples
    702    ///
    703    /// ```
    704    /// use bytes::BufMut;
    705    ///
    706    /// let mut buf = vec![];
    707    /// buf.put_u64_ne(0x0102030405060708);
    708    /// if cfg!(target_endian = "big") {
    709    ///     assert_eq!(buf, b"\x01\x02\x03\x04\x05\x06\x07\x08");
    710    /// } else {
    711    ///     assert_eq!(buf, b"\x08\x07\x06\x05\x04\x03\x02\x01");
    712    /// }
    713    /// ```
    714    ///
    715    /// # Panics
    716    ///
    717    /// This function panics if there is not enough remaining capacity in
    718    /// `self`.
    719    #[inline]
    720    fn put_u64_ne(&mut self, n: u64) {
    721        self.put_slice(&n.to_ne_bytes())
    722    }
    723
    724    /// Writes a signed 64 bit integer to `self` in the big-endian byte order.
    725    ///
    726    /// The current position is advanced by 8.
    727    ///
    728    /// # Examples
    729    ///
    730    /// ```
    731    /// use bytes::BufMut;
    732    ///
    733    /// let mut buf = vec![];
    734    /// buf.put_i64(0x0102030405060708);
    735    /// assert_eq!(buf, b"\x01\x02\x03\x04\x05\x06\x07\x08");
    736    /// ```
    737    ///
    738    /// # Panics
    739    ///
    740    /// This function panics if there is not enough remaining capacity in
    741    /// `self`.
    742    #[inline]
    743    fn put_i64(&mut self, n: i64) {
    744        self.put_slice(&n.to_be_bytes())
    745    }
    746
    747    /// Writes a signed 64 bit integer to `self` in little-endian byte order.
    748    ///
    749    /// The current position is advanced by 8.
    750    ///
    751    /// # Examples
    752    ///
    753    /// ```
    754    /// use bytes::BufMut;
    755    ///
    756    /// let mut buf = vec![];
    757    /// buf.put_i64_le(0x0102030405060708);
    758    /// assert_eq!(buf, b"\x08\x07\x06\x05\x04\x03\x02\x01");
    759    /// ```
    760    ///
    761    /// # Panics
    762    ///
    763    /// This function panics if there is not enough remaining capacity in
    764    /// `self`.
    765    #[inline]
    766    fn put_i64_le(&mut self, n: i64) {
    767        self.put_slice(&n.to_le_bytes())
    768    }
    769
    770    /// Writes a signed 64 bit integer to `self` in native-endian byte order.
    771    ///
    772    /// The current position is advanced by 8.
    773    ///
    774    /// # Examples
    775    ///
    776    /// ```
    777    /// use bytes::BufMut;
    778    ///
    779    /// let mut buf = vec![];
    780    /// buf.put_i64_ne(0x0102030405060708);
    781    /// if cfg!(target_endian = "big") {
    782    ///     assert_eq!(buf, b"\x01\x02\x03\x04\x05\x06\x07\x08");
    783    /// } else {
    784    ///     assert_eq!(buf, b"\x08\x07\x06\x05\x04\x03\x02\x01");
    785    /// }
    786    /// ```
    787    ///
    788    /// # Panics
    789    ///
    790    /// This function panics if there is not enough remaining capacity in
    791    /// `self`.
    792    #[inline]
    793    fn put_i64_ne(&mut self, n: i64) {
    794        self.put_slice(&n.to_ne_bytes())
    795    }
    796
    797    /// Writes an unsigned 128 bit integer to `self` in the big-endian byte order.
    798    ///
    799    /// The current position is advanced by 16.
    800    ///
    801    /// # Examples
    802    ///
    803    /// ```
    804    /// use bytes::BufMut;
    805    ///
    806    /// let mut buf = vec![];
    807    /// buf.put_u128(0x01020304050607080910111213141516);
    808    /// assert_eq!(buf, b"\x01\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15\x16");
    809    /// ```
    810    ///
    811    /// # Panics
    812    ///
    813    /// This function panics if there is not enough remaining capacity in
    814    /// `self`.
    815    #[inline]
    816    fn put_u128(&mut self, n: u128) {
    817        self.put_slice(&n.to_be_bytes())
    818    }
    819
    820    /// Writes an unsigned 128 bit integer to `self` in little-endian byte order.
    821    ///
    822    /// The current position is advanced by 16.
    823    ///
    824    /// # Examples
    825    ///
    826    /// ```
    827    /// use bytes::BufMut;
    828    ///
    829    /// let mut buf = vec![];
    830    /// buf.put_u128_le(0x01020304050607080910111213141516);
    831    /// assert_eq!(buf, b"\x16\x15\x14\x13\x12\x11\x10\x09\x08\x07\x06\x05\x04\x03\x02\x01");
    832    /// ```
    833    ///
    834    /// # Panics
    835    ///
    836    /// This function panics if there is not enough remaining capacity in
    837    /// `self`.
    838    #[inline]
    839    fn put_u128_le(&mut self, n: u128) {
    840        self.put_slice(&n.to_le_bytes())
    841    }
    842
    843    /// Writes an unsigned 128 bit integer to `self` in native-endian byte order.
    844    ///
    845    /// The current position is advanced by 16.
    846    ///
    847    /// # Examples
    848    ///
    849    /// ```
    850    /// use bytes::BufMut;
    851    ///
    852    /// let mut buf = vec![];
    853    /// buf.put_u128_ne(0x01020304050607080910111213141516);
    854    /// if cfg!(target_endian = "big") {
    855    ///     assert_eq!(buf, b"\x01\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15\x16");
    856    /// } else {
    857    ///     assert_eq!(buf, b"\x16\x15\x14\x13\x12\x11\x10\x09\x08\x07\x06\x05\x04\x03\x02\x01");
    858    /// }
    859    /// ```
    860    ///
    861    /// # Panics
    862    ///
    863    /// This function panics if there is not enough remaining capacity in
    864    /// `self`.
    865    #[inline]
    866    fn put_u128_ne(&mut self, n: u128) {
    867        self.put_slice(&n.to_ne_bytes())
    868    }
    869
    870    /// Writes a signed 128 bit integer to `self` in the big-endian byte order.
    871    ///
    872    /// The current position is advanced by 16.
    873    ///
    874    /// # Examples
    875    ///
    876    /// ```
    877    /// use bytes::BufMut;
    878    ///
    879    /// let mut buf = vec![];
    880    /// buf.put_i128(0x01020304050607080910111213141516);
    881    /// assert_eq!(buf, b"\x01\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15\x16");
    882    /// ```
    883    ///
    884    /// # Panics
    885    ///
    886    /// This function panics if there is not enough remaining capacity in
    887    /// `self`.
    888    #[inline]
    889    fn put_i128(&mut self, n: i128) {
    890        self.put_slice(&n.to_be_bytes())
    891    }
    892
    893    /// Writes a signed 128 bit integer to `self` in little-endian byte order.
    894    ///
    895    /// The current position is advanced by 16.
    896    ///
    897    /// # Examples
    898    ///
    899    /// ```
    900    /// use bytes::BufMut;
    901    ///
    902    /// let mut buf = vec![];
    903    /// buf.put_i128_le(0x01020304050607080910111213141516);
    904    /// assert_eq!(buf, b"\x16\x15\x14\x13\x12\x11\x10\x09\x08\x07\x06\x05\x04\x03\x02\x01");
    905    /// ```
    906    ///
    907    /// # Panics
    908    ///
    909    /// This function panics if there is not enough remaining capacity in
    910    /// `self`.
    911    #[inline]
    912    fn put_i128_le(&mut self, n: i128) {
    913        self.put_slice(&n.to_le_bytes())
    914    }
    915
    916    /// Writes a signed 128 bit integer to `self` in native-endian byte order.
    917    ///
    918    /// The current position is advanced by 16.
    919    ///
    920    /// # Examples
    921    ///
    922    /// ```
    923    /// use bytes::BufMut;
    924    ///
    925    /// let mut buf = vec![];
    926    /// buf.put_i128_ne(0x01020304050607080910111213141516);
    927    /// if cfg!(target_endian = "big") {
    928    ///     assert_eq!(buf, b"\x01\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15\x16");
    929    /// } else {
    930    ///     assert_eq!(buf, b"\x16\x15\x14\x13\x12\x11\x10\x09\x08\x07\x06\x05\x04\x03\x02\x01");
    931    /// }
    932    /// ```
    933    ///
    934    /// # Panics
    935    ///
    936    /// This function panics if there is not enough remaining capacity in
    937    /// `self`.
    938    #[inline]
    939    fn put_i128_ne(&mut self, n: i128) {
    940        self.put_slice(&n.to_ne_bytes())
    941    }
    942
    943    /// Writes an unsigned n-byte integer to `self` in big-endian byte order.
    944    ///
    945    /// The current position is advanced by `nbytes`.
    946    ///
    947    /// # Examples
    948    ///
    949    /// ```
    950    /// use bytes::BufMut;
    951    ///
    952    /// let mut buf = vec![];
    953    /// buf.put_uint(0x010203, 3);
    954    /// assert_eq!(buf, b"\x01\x02\x03");
    955    /// ```
    956    ///
    957    /// # Panics
    958    ///
    959    /// This function panics if there is not enough remaining capacity in
    960    /// `self` or if `nbytes` is greater than 8.
    961    #[inline]
    962    fn put_uint(&mut self, n: u64, nbytes: usize) {
    963        let start = match mem::size_of_val(&n).checked_sub(nbytes) {
    964            Some(start) => start,
    965            None => panic_does_not_fit(nbytes, mem::size_of_val(&n)),
    966        };
    967
    968        self.put_slice(&n.to_be_bytes()[start..]);
    969    }
    970
    971    /// Writes an unsigned n-byte integer to `self` in the little-endian byte order.
    972    ///
    973    /// The current position is advanced by `nbytes`.
    974    ///
    975    /// # Examples
    976    ///
    977    /// ```
    978    /// use bytes::BufMut;
    979    ///
    980    /// let mut buf = vec![];
    981    /// buf.put_uint_le(0x010203, 3);
    982    /// assert_eq!(buf, b"\x03\x02\x01");
    983    /// ```
    984    ///
    985    /// # Panics
    986    ///
    987    /// This function panics if there is not enough remaining capacity in
    988    /// `self` or if `nbytes` is greater than 8.
    989    #[inline]
    990    fn put_uint_le(&mut self, n: u64, nbytes: usize) {
    991        let slice = n.to_le_bytes();
    992        let slice = match slice.get(..nbytes) {
    993            Some(slice) => slice,
    994            None => panic_does_not_fit(nbytes, slice.len()),
    995        };
    996
    997        self.put_slice(slice);
    998    }
    999
    1000    /// Writes an unsigned n-byte integer to `self` in the native-endian byte order.
    1001    ///
    1002    /// The current position is advanced by `nbytes`.
    1003    ///
    1004    /// # Examples
    1005    ///
    1006    /// ```
    1007    /// use bytes::BufMut;
    1008    ///
    1009    /// let mut buf = vec![];
    1010    /// buf.put_uint_ne(0x010203, 3);
    1011    /// if cfg!(target_endian = "big") {
    1012    ///     assert_eq!(buf, b"\x01\x02\x03");
    1013    /// } else {
    1014    ///     assert_eq!(buf, b"\x03\x02\x01");
    1015    /// }
    1016    /// ```
    1017    ///
    1018    /// # Panics
    1019    ///
    1020    /// This function panics if there is not enough remaining capacity in
    1021    /// `self` or if `nbytes` is greater than 8.
    1022    #[inline]
    1023    fn put_uint_ne(&mut self, n: u64, nbytes: usize) {
    1024        if cfg!(target_endian = "big") {
    1025            self.put_uint(n, nbytes)
    1026        } else {
    1027            self.put_uint_le(n, nbytes)
    1028        }
    1029    }
    1030
    1031    /// Writes low `nbytes` of a signed integer to `self` in big-endian byte order.
    1032    ///
    1033    /// The current position is advanced by `nbytes`.
    1034    ///
    1035    /// # Examples
    1036    ///
    1037    /// ```
    1038    /// use bytes::BufMut;
    1039    ///
    1040    /// let mut buf = vec![];
    1041    /// buf.put_int(0x0504010203, 3);
    1042    /// assert_eq!(buf, b"\x01\x02\x03");
    1043    /// ```
    1044    ///
    1045    /// # Panics
    1046    ///
    1047    /// This function panics if there is not enough remaining capacity in
    1048    /// `self` or if `nbytes` is greater than 8.
    1049    #[inline]
    1050    fn put_int(&mut self, n: i64, nbytes: usize) {
    1051        let start = match mem::size_of_val(&n).checked_sub(nbytes) {
    1052            Some(start) => start,
    1053            None => panic_does_not_fit(nbytes, mem::size_of_val(&n)),
    1054        };
    1055
    1056        self.put_slice(&n.to_be_bytes()[start..]);
    1057    }
    1058
    1059    /// Writes low `nbytes` of a signed integer to `self` in little-endian byte order.
    1060    ///
    1061    /// The current position is advanced by `nbytes`.
    1062    ///
    1063    /// # Examples
    1064    ///
    1065    /// ```
    1066    /// use bytes::BufMut;
    1067    ///
    1068    /// let mut buf = vec![];
    1069    /// buf.put_int_le(0x0504010203, 3);
    1070    /// assert_eq!(buf, b"\x03\x02\x01");
    1071    /// ```
    1072    ///
    1073    /// # Panics
    1074    ///
    1075    /// This function panics if there is not enough remaining capacity in
    1076    /// `self` or if `nbytes` is greater than 8.
    1077    #[inline]
    1078    fn put_int_le(&mut self, n: i64, nbytes: usize) {
    1079        let slice = n.to_le_bytes();
    1080        let slice = match slice.get(..nbytes) {
    1081            Some(slice) => slice,
    1082            None => panic_does_not_fit(nbytes, slice.len()),
    1083        };
    1084
    1085        self.put_slice(slice);
    1086    }
    1087
    1088    /// Writes low `nbytes` of a signed integer to `self` in native-endian byte order.
    1089    ///
    1090    /// The current position is advanced by `nbytes`.
    1091    ///
    1092    /// # Examples
    1093    ///
    1094    /// ```
    1095    /// use bytes::BufMut;
    1096    ///
    1097    /// let mut buf = vec![];
    1098    /// buf.put_int_ne(0x010203, 3);
    1099    /// if cfg!(target_endian = "big") {
    1100    ///     assert_eq!(buf, b"\x01\x02\x03");
    1101    /// } else {
    1102    ///     assert_eq!(buf, b"\x03\x02\x01");
    1103    /// }
    1104    /// ```
    1105    ///
    1106    /// # Panics
    1107    ///
    1108    /// This function panics if there is not enough remaining capacity in
    1109    /// `self` or if `nbytes` is greater than 8.
    1110    #[inline]
    1111    fn put_int_ne(&mut self, n: i64, nbytes: usize) {
    1112        if cfg!(target_endian = "big") {
    1113            self.put_int(n, nbytes)
    1114        } else {
    1115            self.put_int_le(n, nbytes)
    1116        }
    1117    }
    1118
    1119    /// Writes an IEEE754 single-precision (4 bytes) floating point number to
    1120    /// `self` in big-endian byte order.
    1121    ///
    1122    /// The current position is advanced by 4.
    1123    ///
    1124    /// # Examples
    1125    ///
    1126    /// ```
    1127    /// use bytes::BufMut;
    1128    ///
    1129    /// let mut buf = vec![];
    1130    /// buf.put_f32(1.2f32);
    1131    /// assert_eq!(buf, b"\x3F\x99\x99\x9A");
    1132    /// ```
    1133    ///
    1134    /// # Panics
    1135    ///
    1136    /// This function panics if there is not enough remaining capacity in
    1137    /// `self`.
    1138    #[inline]
    1139    fn put_f32(&mut self, n: f32) {
    1140        self.put_u32(n.to_bits());
    1141    }
    1142
    1143    /// Writes an IEEE754 single-precision (4 bytes) floating point number to
    1144    /// `self` in little-endian byte order.
    1145    ///
    1146    /// The current position is advanced by 4.
    1147    ///
    1148    /// # Examples
    1149    ///
    1150    /// ```
    1151    /// use bytes::BufMut;
    1152    ///
    1153    /// let mut buf = vec![];
    1154    /// buf.put_f32_le(1.2f32);
    1155    /// assert_eq!(buf, b"\x9A\x99\x99\x3F");
    1156    /// ```
    1157    ///
    1158    /// # Panics
    1159    ///
    1160    /// This function panics if there is not enough remaining capacity in
    1161    /// `self`.
    1162    #[inline]
    1163    fn put_f32_le(&mut self, n: f32) {
    1164        self.put_u32_le(n.to_bits());
    1165    }
    1166
    1167    /// Writes an IEEE754 single-precision (4 bytes) floating point number to
    1168    /// `self` in native-endian byte order.
    1169    ///
    1170    /// The current position is advanced by 4.
    1171    ///
    1172    /// # Examples
    1173    ///
    1174    /// ```
    1175    /// use bytes::BufMut;
    1176    ///
    1177    /// let mut buf = vec![];
    1178    /// buf.put_f32_ne(1.2f32);
    1179    /// if cfg!(target_endian = "big") {
    1180    ///     assert_eq!(buf, b"\x3F\x99\x99\x9A");
    1181    /// } else {
    1182    ///     assert_eq!(buf, b"\x9A\x99\x99\x3F");
    1183    /// }
    1184    /// ```
    1185    ///
    1186    /// # Panics
    1187    ///
    1188    /// This function panics if there is not enough remaining capacity in
    1189    /// `self`.
    1190    #[inline]
    1191    fn put_f32_ne(&mut self, n: f32) {
    1192        self.put_u32_ne(n.to_bits());
    1193    }
    1194
    1195    /// Writes an IEEE754 double-precision (8 bytes) floating point number to
    1196    /// `self` in big-endian byte order.
    1197    ///
    1198    /// The current position is advanced by 8.
    1199    ///
    1200    /// # Examples
    1201    ///
    1202    /// ```
    1203    /// use bytes::BufMut;
    1204    ///
    1205    /// let mut buf = vec![];
    1206    /// buf.put_f64(1.2f64);
    1207    /// assert_eq!(buf, b"\x3F\xF3\x33\x33\x33\x33\x33\x33");
    1208    /// ```
    1209    ///
    1210    /// # Panics
    1211    ///
    1212    /// This function panics if there is not enough remaining capacity in
    1213    /// `self`.
    1214    #[inline]
    1215    fn put_f64(&mut self, n: f64) {
    1216        self.put_u64(n.to_bits());
    1217    }
    1218
    1219    /// Writes an IEEE754 double-precision (8 bytes) floating point number to
    1220    /// `self` in little-endian byte order.
    1221    ///
    1222    /// The current position is advanced by 8.
    1223    ///
    1224    /// # Examples
    1225    ///
    1226    /// ```
    1227    /// use bytes::BufMut;
    1228    ///
    1229    /// let mut buf = vec![];
    1230    /// buf.put_f64_le(1.2f64);
    1231    /// assert_eq!(buf, b"\x33\x33\x33\x33\x33\x33\xF3\x3F");
    1232    /// ```
    1233    ///
    1234    /// # Panics
    1235    ///
    1236    /// This function panics if there is not enough remaining capacity in
    1237    /// `self`.
    1238    #[inline]
    1239    fn put_f64_le(&mut self, n: f64) {
    1240        self.put_u64_le(n.to_bits());
    1241    }
    1242
    1243    /// Writes an IEEE754 double-precision (8 bytes) floating point number to
    1244    /// `self` in native-endian byte order.
    1245    ///
    1246    /// The current position is advanced by 8.
    1247    ///
    1248    /// # Examples
    1249    ///
    1250    /// ```
    1251    /// use bytes::BufMut;
    1252    ///
    1253    /// let mut buf = vec![];
    1254    /// buf.put_f64_ne(1.2f64);
    1255    /// if cfg!(target_endian = "big") {
    1256    ///     assert_eq!(buf, b"\x3F\xF3\x33\x33\x33\x33\x33\x33");
    1257    /// } else {
    1258    ///     assert_eq!(buf, b"\x33\x33\x33\x33\x33\x33\xF3\x3F");
    1259    /// }
    1260    /// ```
    1261    ///
    1262    /// # Panics
    1263    ///
    1264    /// This function panics if there is not enough remaining capacity in
    1265    /// `self`.
    1266    #[inline]
    1267    fn put_f64_ne(&mut self, n: f64) {
    1268        self.put_u64_ne(n.to_bits());
    1269    }
    1270
    1271    /// Creates an adaptor which can write at most `limit` bytes to `self`.
    1272    ///
    1273    /// # Examples
    1274    ///
    1275    /// ```
    1276    /// use bytes::BufMut;
    1277    ///
    1278    /// let arr = &mut [0u8; 128][..];
    1279    /// assert_eq!(arr.remaining_mut(), 128);
    1280    ///
    1281    /// let dst = arr.limit(10);
    1282    /// assert_eq!(dst.remaining_mut(), 10);
    1283    /// ```
    1284    #[inline]
    1285    fn limit(self, limit: usize) -> Limit<Self>
    1286    where
    1287        Self: Sized,
    1288    {
    1289        limit::new(self, limit)
    1290    }
    1291
    1292    /// Creates an adaptor which implements the `Write` trait for `self`.
    1293    ///
    1294    /// This function returns a new value which implements `Write` by adapting
    1295    /// the `Write` trait functions to the `BufMut` trait functions. Given that
    1296    /// `BufMut` operations are infallible, none of the `Write` functions will
    1297    /// return with `Err`.
    1298    ///
    1299    /// # Examples
    1300    ///
    1301    /// ```
    1302    /// use bytes::BufMut;
    1303    /// use std::io::Write;
    1304    ///
    1305    /// let mut buf = vec![].writer();
    1306    ///
    1307    /// let num = buf.write(&b"hello world"[..]).unwrap();
    1308    /// assert_eq!(11, num);
    1309    ///
    1310    /// let buf = buf.into_inner();
    1311    ///
    1312    /// assert_eq!(*buf, b"hello world"[..]);
    1313    /// ```
    1314    #[cfg(feature = "std")]
    1315    #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
    1316    #[inline]
    1317    fn writer(self) -> Writer<Self>
    1318    where
    1319        Self: Sized,
    1320    {
    1321        writer::new(self)
    1322    }
    1323
    1324    /// Creates an adapter which will chain this buffer with another.
    1325    ///
    1326    /// The returned `BufMut` instance will first write to all bytes from
    1327    /// `self`. Afterwards, it will write to `next`.
    1328    ///
    1329    /// # Examples
    1330    ///
    1331    /// ```
    1332    /// use bytes::BufMut;
    1333    ///
    1334    /// let mut a = [0u8; 5];
    1335    /// let mut b = [0u8; 6];
    1336    ///
    1337    /// let mut chain = (&mut a[..]).chain_mut(&mut b[..]);
    1338    ///
    1339    /// chain.put_slice(b"hello world");
    1340    ///
    1341    /// assert_eq!(&a[..], b"hello");
    1342    /// assert_eq!(&b[..], b" world");
    1343    /// ```
    1344    #[inline]
    1345    fn chain_mut<U: BufMut>(self, next: U) -> Chain<Self, U>
    1346    where
    1347        Self: Sized,
    1348    {
    1349        Chain::new(self, next)
    1350    }
    1351}
    1352
    1353macro_rules! deref_forward_bufmut {
    1354    () => {
    1355        #[inline]
    1356        fn remaining_mut(&self) -> usize {
    1357            (**self).remaining_mut()
    1358        }
    1359
    1360        #[inline]
    1361        fn chunk_mut(&mut self) -> &mut UninitSlice {
    1362            (**self).chunk_mut()
    1363        }
    1364
    1365        #[inline]
    1366        unsafe fn advance_mut(&mut self, cnt: usize) {
    1367            (**self).advance_mut(cnt)
    1368        }
    1369
    1370        #[inline]
    1371        fn put_slice(&mut self, src: &[u8]) {
    1372            (**self).put_slice(src)
    1373        }
    1374
    1375        #[inline]
    1376        fn put_u8(&mut self, n: u8) {
    1377            (**self).put_u8(n)
    1378        }
    1379
    1380        #[inline]
    1381        fn put_i8(&mut self, n: i8) {
    1382            (**self).put_i8(n)
    1383        }
    1384
    1385        #[inline]
    1386        fn put_u16(&mut self, n: u16) {
    1387            (**self).put_u16(n)
    1388        }
    1389
    1390        #[inline]
    1391        fn put_u16_le(&mut self, n: u16) {
    1392            (**self).put_u16_le(n)
    1393        }
    1394
    1395        #[inline]
    1396        fn put_u16_ne(&mut self, n: u16) {
    1397            (**self).put_u16_ne(n)
    1398        }
    1399
    1400        #[inline]
    1401        fn put_i16(&mut self, n: i16) {
    1402            (**self).put_i16(n)
    1403        }
    1404
    1405        #[inline]
    1406        fn put_i16_le(&mut self, n: i16) {
    1407            (**self).put_i16_le(n)
    1408        }
    1409
    1410        #[inline]
    1411        fn put_i16_ne(&mut self, n: i16) {
    1412            (**self).put_i16_ne(n)
    1413        }
    1414
    1415        #[inline]
    1416        fn put_u32(&mut self, n: u32) {
    1417            (**self).put_u32(n)
    1418        }
    1419
    1420        #[inline]
    1421        fn put_u32_le(&mut self, n: u32) {
    1422            (**self).put_u32_le(n)
    1423        }
    1424
    1425        #[inline]
    1426        fn put_u32_ne(&mut self, n: u32) {
    1427            (**self).put_u32_ne(n)
    1428        }
    1429
    1430        #[inline]
    1431        fn put_i32(&mut self, n: i32) {
    1432            (**self).put_i32(n)
    1433        }
    1434
    1435        #[inline]
    1436        fn put_i32_le(&mut self, n: i32) {
    1437            (**self).put_i32_le(n)
    1438        }
    1439
    1440        #[inline]
    1441        fn put_i32_ne(&mut self, n: i32) {
    1442            (**self).put_i32_ne(n)
    1443        }
    1444
    1445        #[inline]
    1446        fn put_u64(&mut self, n: u64) {
    1447            (**self).put_u64(n)
    1448        }
    1449
    1450        #[inline]
    1451        fn put_u64_le(&mut self, n: u64) {
    1452            (**self).put_u64_le(n)
    1453        }
    1454
    1455        #[inline]
    1456        fn put_u64_ne(&mut self, n: u64) {
    1457            (**self).put_u64_ne(n)
    1458        }
    1459
    1460        #[inline]
    1461        fn put_i64(&mut self, n: i64) {
    1462            (**self).put_i64(n)
    1463        }
    1464
    1465        #[inline]
    1466        fn put_i64_le(&mut self, n: i64) {
    1467            (**self).put_i64_le(n)
    1468        }
    1469
    1470        #[inline]
    1471        fn put_i64_ne(&mut self, n: i64) {
    1472            (**self).put_i64_ne(n)
    1473        }
    1474    };
    1475}
    1476
    1477unsafe impl<T: BufMut + ?Sized> BufMut for &mut T {
    1478    deref_forward_bufmut!();
    1479}
    1480
    1481unsafe impl<T: BufMut + ?Sized> BufMut for Box<T> {
    1482    deref_forward_bufmut!();
    1483}
    1484
    1485unsafe impl BufMut for &mut [u8] {
    1486    #[inline]
    1487    fn remaining_mut(&self) -> usize {
    1488        self.len()
    1489    }
    1490
    1491    #[inline]
    1492    fn chunk_mut(&mut self) -> &mut UninitSlice {
    1493        UninitSlice::new(self)
    1494    }
    1495
    1496    #[inline]
    1497    unsafe fn advance_mut(&mut self, cnt: usize) {
    1498        if self.len() < cnt {
    1499            panic_advance(&TryGetError {
    1500                requested: cnt,
    1501                available: self.len(),
    1502            });
    1503        }
    1504
    1505        // Lifetime dance taken from `impl Write for &mut [u8]`.
    1506        let (_, b) = core::mem::take(self).split_at_mut(cnt);
    1507        *self = b;
    1508    }
    1509
    1510    #[inline]
    1511    fn put_slice(&mut self, src: &[u8]) {
    1512        if self.len() < src.len() {
    1513            panic_advance(&TryGetError {
    1514                requested: src.len(),
    1515                available: self.len(),
    1516            });
    1517        }
    1518
    1519        self[..src.len()].copy_from_slice(src);
    1520        // SAFETY: We just initialized `src.len()` bytes.
    1521        unsafe { self.advance_mut(src.len()) };
    1522    }
    1523
    1524    #[inline]
    1525    fn put_bytes(&mut self, val: u8, cnt: usize) {
    1526        if self.len() < cnt {
    1527            panic_advance(&TryGetError {
    1528                requested: cnt,
    1529                available: self.len(),
    1530            });
    1531        }
    1532
    1533        // SAFETY: We just checked that the pointer is valid for `cnt` bytes.
    1534        unsafe {
    1535            ptr::write_bytes(self.as_mut_ptr(), val, cnt);
    1536            self.advance_mut(cnt);
    1537        }
    1538    }
    1539}
    1540
    1541unsafe impl BufMut for &mut [core::mem::MaybeUninit<u8>] {
    1542    #[inline]
    1543    fn remaining_mut(&self) -> usize {
    1544        self.len()
    1545    }
    1546
    1547    #[inline]
    1548    fn chunk_mut(&mut self) -> &mut UninitSlice {
    1549        UninitSlice::uninit(self)
    1550    }
    1551
    1552    #[inline]
    1553    unsafe fn advance_mut(&mut self, cnt: usize) {
    1554        if self.len() < cnt {
    1555            panic_advance(&TryGetError {
    1556                requested: cnt,
    1557                available: self.len(),
    1558            });
    1559        }
    1560
    1561        // Lifetime dance taken from `impl Write for &mut [u8]`.
    1562        let (_, b) = core::mem::take(self).split_at_mut(cnt);
    1563        *self = b;
    1564    }
    1565
    1566    #[inline]
    1567    fn put_slice(&mut self, src: &[u8]) {
    1568        if self.len() < src.len() {
    1569            panic_advance(&TryGetError {
    1570                requested: src.len(),
    1571                available: self.len(),
    1572            });
    1573        }
    1574
    1575        // SAFETY: We just checked that the pointer is valid for `src.len()` bytes.
    1576        unsafe {
    1577            ptr::copy_nonoverlapping(src.as_ptr(), self.as_mut_ptr().cast(), src.len());
    1578            self.advance_mut(src.len());
    1579        }
    1580    }
    1581
    1582    #[inline]
    1583    fn put_bytes(&mut self, val: u8, cnt: usize) {
    1584        if self.len() < cnt {
    1585            panic_advance(&TryGetError {
    1586                requested: cnt,
    1587                available: self.len(),
    1588            });
    1589        }
    1590
    1591        // SAFETY: We just checked that the pointer is valid for `cnt` bytes.
    1592        unsafe {
    1593            ptr::write_bytes(self.as_mut_ptr() as *mut u8, val, cnt);
    1594            self.advance_mut(cnt);
    1595        }
    1596    }
    1597}
    1598
    1599unsafe impl BufMut for Vec<u8> {
    1600    #[inline]
    1601    fn remaining_mut(&self) -> usize {
    1602        // A vector can never have more than isize::MAX bytes
    1603        isize::MAX as usize - self.len()
    1604    }
    1605
    1606    #[inline]
    1607    unsafe fn advance_mut(&mut self, cnt: usize) {
    1608        let len = self.len();
    1609        let remaining = self.capacity() - len;
    1610
    1611        if remaining < cnt {
    1612            panic_advance(&TryGetError {
    1613                requested: cnt,
    1614                available: remaining,
    1615            });
    1616        }
    1617
    1618        // Addition will not overflow since the sum is at most the capacity.
    1619        self.set_len(len + cnt);
    1620    }
    1621
    1622    #[inline]
    1623    fn chunk_mut(&mut self) -> &mut UninitSlice {
    1624        if self.capacity() == self.len() {
    1625            self.reserve(64); // Grow the vec
    1626        }
    1627
    1628        let cap = self.capacity();
    1629        let len = self.len();
    1630
    1631        let ptr = self.as_mut_ptr();
    1632        // SAFETY: Since `ptr` is valid for `cap` bytes, `ptr.add(len)` must be
    1633        // valid for `cap - len` bytes. The subtraction will not underflow since
    1634        // `len <= cap`.
    1635        unsafe { UninitSlice::from_raw_parts_mut(ptr.add(len), cap - len) }
    1636    }
    1637
    1638    // Specialize these methods so they can skip checking `remaining_mut`
    1639    // and `advance_mut`.
    1640    #[inline]
    1641    fn put<T: super::Buf>(&mut self, mut src: T)
    1642    where
    1643        Self: Sized,
    1644    {
    1645        // In case the src isn't contiguous, reserve upfront.
    1646        self.reserve(src.remaining());
    1647
    1648        while src.has_remaining() {
    1649            let s = src.chunk();
    1650            let l = s.len();
    1651            self.extend_from_slice(s);
    1652            src.advance(l);
    1653        }
    1654    }
    1655
    1656    #[inline]
    1657    fn put_slice(&mut self, src: &[u8]) {
    1658        self.extend_from_slice(src);
    1659    }
    1660
    1661    #[inline]
    1662    fn put_bytes(&mut self, val: u8, cnt: usize) {
    1663        // If the addition overflows, then the `resize` will fail.
    1664        let new_len = self.len().saturating_add(cnt);
    1665        self.resize(new_len, val);
    1666    }
    1667}
    1668
    1669// The existence of this function makes the compiler catch if the BufMut
    1670// trait is "object-safe" or not.
    1671fn _assert_trait_object(_b: &dyn BufMut) {}