Trait BufMut

unsafe trait BufMut

A trait for values that provide sequential write access to bytes.

Write bytes to a buffer

A buffer stores bytes in memory such that write operations are infallible. The underlying storage may or may not be in contiguous memory. A BufMut value is a cursor into the buffer. Writing to BufMut advances the cursor position.

The simplest BufMut is a Vec<u8>.

use bytes::BufMut;

let mut buf = vec![];

buf.put(&b"hello world"[..]);

assert_eq!(buf, b"hello world");

Required Methods

fn remaining_mut(self: &Self) -> usize

Returns the number of bytes that can be written from the current position until the end of the buffer is reached.

This value is greater than or equal to the length of the slice returned by chunk_mut().

Writing to a BufMut may involve allocating more memory on the fly. Implementations may fail before reaching the number of bytes indicated by this method if they encounter an allocation failure.

Examples

use bytes::BufMut;

let mut dst = [0; 10];
let mut buf = &mut dst[..];

let original_remaining = buf.remaining_mut();
buf.put(&b"hello"[..]);

assert_eq!(original_remaining - 5, buf.remaining_mut());

Implementer notes

Implementations of remaining_mut should ensure that the return value does not change unless a call is made to advance_mut or any other function that is documented to change the BufMut's current position.

Note

remaining_mut may return value smaller than actual available space.

unsafe fn advance_mut(self: &mut Self, cnt: usize)

Advance the internal cursor of the BufMut

The next call to chunk_mut will return a slice starting cnt bytes further into the underlying buffer.

Safety

The caller must ensure that the next cnt bytes of chunk are initialized.

Examples

use bytes::BufMut;

let mut buf = Vec::with_capacity(16);

// Write some data
buf.chunk_mut()[0..2].copy_from_slice(b"he");
unsafe { buf.advance_mut(2) };

// write more bytes
buf.chunk_mut()[0..3].copy_from_slice(b"llo");

unsafe { buf.advance_mut(3); }

assert_eq!(5, buf.len());
assert_eq!(buf, b"hello");

Panics

This function may panic if cnt > self.remaining_mut().

Implementer notes

It is recommended for implementations of advance_mut to panic if cnt > self.remaining_mut(). If the implementation does not panic, the call must behave as if cnt == self.remaining_mut().

A call with cnt == 0 should never panic and be a no-op.

fn chunk_mut(self: &mut Self) -> &mut UninitSlice

Returns a mutable slice starting at the current BufMut position and of length between 0 and BufMut::remaining_mut(). Note that this can be shorter than the whole remainder of the buffer (this allows non-continuous implementation).

This is a lower level function. Most operations are done with other functions.

The returned byte slice may represent uninitialized memory.

Examples

use bytes::BufMut;

let mut buf = Vec::with_capacity(16);

unsafe {
    // MaybeUninit::as_mut_ptr
    buf.chunk_mut()[0..].as_mut_ptr().write(b'h');
    buf.chunk_mut()[1..].as_mut_ptr().write(b'e');

    buf.advance_mut(2);

    buf.chunk_mut()[0..].as_mut_ptr().write(b'l');
    buf.chunk_mut()[1..].as_mut_ptr().write(b'l');
    buf.chunk_mut()[2..].as_mut_ptr().write(b'o');

    buf.advance_mut(3);
}

assert_eq!(5, buf.len());
assert_eq!(buf, b"hello");

Implementer notes

This function should never panic. chunk_mut() should return an empty slice if and only if remaining_mut() returns 0. In other words, chunk_mut() returning an empty slice implies that remaining_mut() will return 0 and remaining_mut() returning 0 implies that chunk_mut() will return an empty slice.

This function may trigger an out-of-memory abort if it tries to allocate memory and fails to do so.

Provided Methods

fn has_remaining_mut(self: &Self) -> bool

Returns true if there is space in self for more bytes.

This is equivalent to self.remaining_mut() != 0.

Examples

use bytes::BufMut;

let mut dst = [0; 5];
let mut buf = &mut dst[..];

assert!(buf.has_remaining_mut());

buf.put(&b"hello"[..]);

assert!(!buf.has_remaining_mut());

fn put<T: super::Buf>(self: &mut Self, src: T)
where
    Self: Sized

Transfer bytes into self from src and advance the cursor by the number of bytes written.

Examples

use bytes::BufMut;

let mut buf = vec![];

buf.put_u8(b'h');
buf.put(&b"ello"[..]);
buf.put(&b" world"[..]);

assert_eq!(buf, b"hello world");

Panics

Panics if self does not have enough capacity to contain src.

fn put_slice(self: &mut Self, src: &[u8])

Transfer bytes into self from src and advance the cursor by the number of bytes written.

self must have enough remaining capacity to contain all of src.

use bytes::BufMut;

let mut dst = [0; 6];

{
    let mut buf = &mut dst[..];
    buf.put_slice(b"hello");

    assert_eq!(1, buf.remaining_mut());
}

assert_eq!(b"hello\0", &dst);

fn put_bytes(self: &mut Self, val: u8, cnt: usize)

Put cnt bytes val into self.

Logically equivalent to calling self.put_u8(val) cnt times, but may work faster.

self must have at least cnt remaining capacity.

use bytes::BufMut;

let mut dst = [0; 6];

{
    let mut buf = &mut dst[..];
    buf.put_bytes(b'a', 4);

    assert_eq!(2, buf.remaining_mut());
}

assert_eq!(b"aaaa\0\0", &dst);

Panics

This function panics if there is not enough remaining capacity in self.

fn put_u8(self: &mut Self, n: u8)

Writes an unsigned 8 bit integer to self.

The current position is advanced by 1.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_u8(0x01);
assert_eq!(buf, b"\x01");

Panics

This function panics if there is not enough remaining capacity in self.

fn put_i8(self: &mut Self, n: i8)

Writes a signed 8 bit integer to self.

The current position is advanced by 1.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_i8(0x01);
assert_eq!(buf, b"\x01");

Panics

This function panics if there is not enough remaining capacity in self.

fn put_u16(self: &mut Self, n: u16)

Writes an unsigned 16 bit integer to self in big-endian byte order.

The current position is advanced by 2.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_u16(0x0809);
assert_eq!(buf, b"\x08\x09");

Panics

This function panics if there is not enough remaining capacity in self.

fn put_u16_le(self: &mut Self, n: u16)

Writes an unsigned 16 bit integer to self in little-endian byte order.

The current position is advanced by 2.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_u16_le(0x0809);
assert_eq!(buf, b"\x09\x08");

Panics

This function panics if there is not enough remaining capacity in self.

fn put_u16_ne(self: &mut Self, n: u16)

Writes an unsigned 16 bit integer to self in native-endian byte order.

The current position is advanced by 2.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_u16_ne(0x0809);
if cfg!(target_endian = "big") {
    assert_eq!(buf, b"\x08\x09");
} else {
    assert_eq!(buf, b"\x09\x08");
}

Panics

This function panics if there is not enough remaining capacity in self.

fn put_i16(self: &mut Self, n: i16)

Writes a signed 16 bit integer to self in big-endian byte order.

The current position is advanced by 2.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_i16(0x0809);
assert_eq!(buf, b"\x08\x09");

Panics

This function panics if there is not enough remaining capacity in self.

fn put_i16_le(self: &mut Self, n: i16)

Writes a signed 16 bit integer to self in little-endian byte order.

The current position is advanced by 2.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_i16_le(0x0809);
assert_eq!(buf, b"\x09\x08");

Panics

This function panics if there is not enough remaining capacity in self.

fn put_i16_ne(self: &mut Self, n: i16)

Writes a signed 16 bit integer to self in native-endian byte order.

The current position is advanced by 2.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_i16_ne(0x0809);
if cfg!(target_endian = "big") {
    assert_eq!(buf, b"\x08\x09");
} else {
    assert_eq!(buf, b"\x09\x08");
}

Panics

This function panics if there is not enough remaining capacity in self.

fn put_u32(self: &mut Self, n: u32)

Writes an unsigned 32 bit integer to self in big-endian byte order.

The current position is advanced by 4.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_u32(0x0809A0A1);
assert_eq!(buf, b"\x08\x09\xA0\xA1");

Panics

This function panics if there is not enough remaining capacity in self.

fn put_u32_le(self: &mut Self, n: u32)

Writes an unsigned 32 bit integer to self in little-endian byte order.

The current position is advanced by 4.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_u32_le(0x0809A0A1);
assert_eq!(buf, b"\xA1\xA0\x09\x08");

Panics

This function panics if there is not enough remaining capacity in self.

fn put_u32_ne(self: &mut Self, n: u32)

Writes an unsigned 32 bit integer to self in native-endian byte order.

The current position is advanced by 4.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_u32_ne(0x0809A0A1);
if cfg!(target_endian = "big") {
    assert_eq!(buf, b"\x08\x09\xA0\xA1");
} else {
    assert_eq!(buf, b"\xA1\xA0\x09\x08");
}

Panics

This function panics if there is not enough remaining capacity in self.

fn put_i32(self: &mut Self, n: i32)

Writes a signed 32 bit integer to self in big-endian byte order.

The current position is advanced by 4.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_i32(0x0809A0A1);
assert_eq!(buf, b"\x08\x09\xA0\xA1");

Panics

This function panics if there is not enough remaining capacity in self.

fn put_i32_le(self: &mut Self, n: i32)

Writes a signed 32 bit integer to self in little-endian byte order.

The current position is advanced by 4.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_i32_le(0x0809A0A1);
assert_eq!(buf, b"\xA1\xA0\x09\x08");

Panics

This function panics if there is not enough remaining capacity in self.

fn put_i32_ne(self: &mut Self, n: i32)

Writes a signed 32 bit integer to self in native-endian byte order.

The current position is advanced by 4.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_i32_ne(0x0809A0A1);
if cfg!(target_endian = "big") {
    assert_eq!(buf, b"\x08\x09\xA0\xA1");
} else {
    assert_eq!(buf, b"\xA1\xA0\x09\x08");
}

Panics

This function panics if there is not enough remaining capacity in self.

fn put_u64(self: &mut Self, n: u64)

Writes an unsigned 64 bit integer to self in the big-endian byte order.

The current position is advanced by 8.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_u64(0x0102030405060708);
assert_eq!(buf, b"\x01\x02\x03\x04\x05\x06\x07\x08");

Panics

This function panics if there is not enough remaining capacity in self.

fn put_u64_le(self: &mut Self, n: u64)

Writes an unsigned 64 bit integer to self in little-endian byte order.

The current position is advanced by 8.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_u64_le(0x0102030405060708);
assert_eq!(buf, b"\x08\x07\x06\x05\x04\x03\x02\x01");

Panics

This function panics if there is not enough remaining capacity in self.

fn put_u64_ne(self: &mut Self, n: u64)

Writes an unsigned 64 bit integer to self in native-endian byte order.

The current position is advanced by 8.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_u64_ne(0x0102030405060708);
if cfg!(target_endian = "big") {
    assert_eq!(buf, b"\x01\x02\x03\x04\x05\x06\x07\x08");
} else {
    assert_eq!(buf, b"\x08\x07\x06\x05\x04\x03\x02\x01");
}

Panics

This function panics if there is not enough remaining capacity in self.

fn put_i64(self: &mut Self, n: i64)

Writes a signed 64 bit integer to self in the big-endian byte order.

The current position is advanced by 8.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_i64(0x0102030405060708);
assert_eq!(buf, b"\x01\x02\x03\x04\x05\x06\x07\x08");

Panics

This function panics if there is not enough remaining capacity in self.

fn put_i64_le(self: &mut Self, n: i64)

Writes a signed 64 bit integer to self in little-endian byte order.

The current position is advanced by 8.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_i64_le(0x0102030405060708);
assert_eq!(buf, b"\x08\x07\x06\x05\x04\x03\x02\x01");

Panics

This function panics if there is not enough remaining capacity in self.

fn put_i64_ne(self: &mut Self, n: i64)

Writes a signed 64 bit integer to self in native-endian byte order.

The current position is advanced by 8.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_i64_ne(0x0102030405060708);
if cfg!(target_endian = "big") {
    assert_eq!(buf, b"\x01\x02\x03\x04\x05\x06\x07\x08");
} else {
    assert_eq!(buf, b"\x08\x07\x06\x05\x04\x03\x02\x01");
}

Panics

This function panics if there is not enough remaining capacity in self.

fn put_u128(self: &mut Self, n: u128)

Writes an unsigned 128 bit integer to self in the big-endian byte order.

The current position is advanced by 16.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_u128(0x01020304050607080910111213141516);
assert_eq!(buf, b"\x01\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15\x16");

Panics

This function panics if there is not enough remaining capacity in self.

fn put_u128_le(self: &mut Self, n: u128)

Writes an unsigned 128 bit integer to self in little-endian byte order.

The current position is advanced by 16.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_u128_le(0x01020304050607080910111213141516);
assert_eq!(buf, b"\x16\x15\x14\x13\x12\x11\x10\x09\x08\x07\x06\x05\x04\x03\x02\x01");

Panics

This function panics if there is not enough remaining capacity in self.

fn put_u128_ne(self: &mut Self, n: u128)

Writes an unsigned 128 bit integer to self in native-endian byte order.

The current position is advanced by 16.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_u128_ne(0x01020304050607080910111213141516);
if cfg!(target_endian = "big") {
    assert_eq!(buf, b"\x01\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15\x16");
} else {
    assert_eq!(buf, b"\x16\x15\x14\x13\x12\x11\x10\x09\x08\x07\x06\x05\x04\x03\x02\x01");
}

Panics

This function panics if there is not enough remaining capacity in self.

fn put_i128(self: &mut Self, n: i128)

Writes a signed 128 bit integer to self in the big-endian byte order.

The current position is advanced by 16.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_i128(0x01020304050607080910111213141516);
assert_eq!(buf, b"\x01\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15\x16");

Panics

This function panics if there is not enough remaining capacity in self.

fn put_i128_le(self: &mut Self, n: i128)

Writes a signed 128 bit integer to self in little-endian byte order.

The current position is advanced by 16.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_i128_le(0x01020304050607080910111213141516);
assert_eq!(buf, b"\x16\x15\x14\x13\x12\x11\x10\x09\x08\x07\x06\x05\x04\x03\x02\x01");

Panics

This function panics if there is not enough remaining capacity in self.

fn put_i128_ne(self: &mut Self, n: i128)

Writes a signed 128 bit integer to self in native-endian byte order.

The current position is advanced by 16.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_i128_ne(0x01020304050607080910111213141516);
if cfg!(target_endian = "big") {
    assert_eq!(buf, b"\x01\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15\x16");
} else {
    assert_eq!(buf, b"\x16\x15\x14\x13\x12\x11\x10\x09\x08\x07\x06\x05\x04\x03\x02\x01");
}

Panics

This function panics if there is not enough remaining capacity in self.

fn put_uint(self: &mut Self, n: u64, nbytes: usize)

Writes an unsigned n-byte integer to self in big-endian byte order.

The current position is advanced by nbytes.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_uint(0x010203, 3);
assert_eq!(buf, b"\x01\x02\x03");

Panics

This function panics if there is not enough remaining capacity in self or if nbytes is greater than 8.

fn put_uint_le(self: &mut Self, n: u64, nbytes: usize)

Writes an unsigned n-byte integer to self in the little-endian byte order.

The current position is advanced by nbytes.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_uint_le(0x010203, 3);
assert_eq!(buf, b"\x03\x02\x01");

Panics

This function panics if there is not enough remaining capacity in self or if nbytes is greater than 8.

fn put_uint_ne(self: &mut Self, n: u64, nbytes: usize)

Writes an unsigned n-byte integer to self in the native-endian byte order.

The current position is advanced by nbytes.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_uint_ne(0x010203, 3);
if cfg!(target_endian = "big") {
    assert_eq!(buf, b"\x01\x02\x03");
} else {
    assert_eq!(buf, b"\x03\x02\x01");
}

Panics

This function panics if there is not enough remaining capacity in self or if nbytes is greater than 8.

fn put_int(self: &mut Self, n: i64, nbytes: usize)

Writes low nbytes of a signed integer to self in big-endian byte order.

The current position is advanced by nbytes.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_int(0x0504010203, 3);
assert_eq!(buf, b"\x01\x02\x03");

Panics

This function panics if there is not enough remaining capacity in self or if nbytes is greater than 8.

fn put_int_le(self: &mut Self, n: i64, nbytes: usize)

Writes low nbytes of a signed integer to self in little-endian byte order.

The current position is advanced by nbytes.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_int_le(0x0504010203, 3);
assert_eq!(buf, b"\x03\x02\x01");

Panics

This function panics if there is not enough remaining capacity in self or if nbytes is greater than 8.

fn put_int_ne(self: &mut Self, n: i64, nbytes: usize)

Writes low nbytes of a signed integer to self in native-endian byte order.

The current position is advanced by nbytes.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_int_ne(0x010203, 3);
if cfg!(target_endian = "big") {
    assert_eq!(buf, b"\x01\x02\x03");
} else {
    assert_eq!(buf, b"\x03\x02\x01");
}

Panics

This function panics if there is not enough remaining capacity in self or if nbytes is greater than 8.

fn put_f32(self: &mut Self, n: f32)

Writes an IEEE754 single-precision (4 bytes) floating point number to self in big-endian byte order.

The current position is advanced by 4.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_f32(1.2f32);
assert_eq!(buf, b"\x3F\x99\x99\x9A");

Panics

This function panics if there is not enough remaining capacity in self.

fn put_f32_le(self: &mut Self, n: f32)

Writes an IEEE754 single-precision (4 bytes) floating point number to self in little-endian byte order.

The current position is advanced by 4.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_f32_le(1.2f32);
assert_eq!(buf, b"\x9A\x99\x99\x3F");

Panics

This function panics if there is not enough remaining capacity in self.

fn put_f32_ne(self: &mut Self, n: f32)

Writes an IEEE754 single-precision (4 bytes) floating point number to self in native-endian byte order.

The current position is advanced by 4.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_f32_ne(1.2f32);
if cfg!(target_endian = "big") {
    assert_eq!(buf, b"\x3F\x99\x99\x9A");
} else {
    assert_eq!(buf, b"\x9A\x99\x99\x3F");
}

Panics

This function panics if there is not enough remaining capacity in self.

fn put_f64(self: &mut Self, n: f64)

Writes an IEEE754 double-precision (8 bytes) floating point number to self in big-endian byte order.

The current position is advanced by 8.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_f64(1.2f64);
assert_eq!(buf, b"\x3F\xF3\x33\x33\x33\x33\x33\x33");

Panics

This function panics if there is not enough remaining capacity in self.

fn put_f64_le(self: &mut Self, n: f64)

Writes an IEEE754 double-precision (8 bytes) floating point number to self in little-endian byte order.

The current position is advanced by 8.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_f64_le(1.2f64);
assert_eq!(buf, b"\x33\x33\x33\x33\x33\x33\xF3\x3F");

Panics

This function panics if there is not enough remaining capacity in self.

fn put_f64_ne(self: &mut Self, n: f64)

Writes an IEEE754 double-precision (8 bytes) floating point number to self in native-endian byte order.

The current position is advanced by 8.

Examples

use bytes::BufMut;

let mut buf = vec![];
buf.put_f64_ne(1.2f64);
if cfg!(target_endian = "big") {
    assert_eq!(buf, b"\x3F\xF3\x33\x33\x33\x33\x33\x33");
} else {
    assert_eq!(buf, b"\x33\x33\x33\x33\x33\x33\xF3\x3F");
}

Panics

This function panics if there is not enough remaining capacity in self.

fn limit(self: Self, limit: usize) -> Limit<Self>
where
    Self: Sized

Creates an adaptor which can write at most limit bytes to self.

Examples

use bytes::BufMut;

let arr = &mut [0u8; 128][..];
assert_eq!(arr.remaining_mut(), 128);

let dst = arr.limit(10);
assert_eq!(dst.remaining_mut(), 10);

fn writer(self: Self) -> Writer<Self>
where
    Self: Sized

Creates an adaptor which implements the Write trait for self.

This function returns a new value which implements Write by adapting the Write trait functions to the BufMut trait functions. Given that BufMut operations are infallible, none of the Write functions will return with Err.

Examples

use bytes::BufMut;
use std::io::Write;

let mut buf = vec![].writer();

let num = buf.write(&b"hello world"[..]).unwrap();
assert_eq!(11, num);

let buf = buf.into_inner();

assert_eq!(*buf, b"hello world"[..]);

fn chain_mut<U: BufMut>(self: Self, next: U) -> Chain<Self, U>
where
    Self: Sized

Creates an adapter which will chain this buffer with another.

The returned BufMut instance will first write to all bytes from self. Afterwards, it will write to next.

Examples

use bytes::BufMut;

let mut a = [0u8; 5];
let mut b = [0u8; 6];

let mut chain = (&mut a[..]).chain_mut(&mut b[..]);

chain.put_slice(b"hello world");

assert_eq!(&a[..], b"hello");
assert_eq!(&b[..], b" world");

Implementors