What is the purpose of `bytes::BytesMut::split_off` for dividing mutable buffers?

split_off divides a BytesMut buffer at a specified position, returning a new BytesMut containing the bytes after that position while truncating the original buffer to contain only the bytes before it—all without copying the underlying data. This enables zero-cost buffer division for protocols and parsers that need to separate headers from bodies, or extract discrete messages from a stream buffer without the overhead of copying bytes. The method modifies the original buffer in place and returns a new buffer that shares the same underlying storage, making it efficient for scenarios where you accumulate data and then extract portions for processing.

Basic split_off Behavior

use bytes::BytesMut;
 
fn basic_split_off() {
    let mut buf = BytesMut::from("hello world");
    
    // Split at position 5
    let second = buf.split_off(5);
    
    // buf now contains "hello" (truncated)
    // second contains " world" (new buffer)
    
    assert_eq!(&buf[..], b"hello");
    assert_eq!(&second[..], b" world");
}

split_off(at) returns bytes from position at to the end, while truncating the original to bytes 0 to at.

Zero-Copy Semantics

use bytes::BytesMut;
 
fn zero_copy_split() {
    // BytesMut uses reference counting internally
    let mut buf = BytesMut::from("hello world");
    
    // split_off doesn't copy bytes - it adjusts pointers
    let second = buf.split_off(5);
    
    // Both buf and second share the same underlying allocation
    // No memcpy occurred - just pointer adjustments
    
    // This is why BytesMut is efficient for parsing:
    // You can split buffers without the cost of copying data
}

The split operation adjusts internal pointers and reference counts, avoiding byte copying.

In-Place Modification

use bytes::BytesMut;
 
fn in_place_behavior() {
    let mut buf = BytesMut::from("hello world");
    
    // Original has 11 bytes
    assert_eq!(buf.len(), 11);
    
    // Split at position 6
    let second = buf.split_off(6);
    
    // Original is now truncated
    assert_eq!(buf.len(), 6);
    assert_eq!(&buf[..], b"hello ");
    
    // Returned buffer has remaining bytes
    assert_eq!(second.len(), 5);
    assert_eq!(&second[..], b"world");
    
    // Both are independent BytesMut values
}

The original buffer is modified in place; the returned buffer is a new value.

Common Pattern: Extracting Messages

use bytes::BytesMut;
 
fn extract_message() {
    // Accumulate incoming data
    let mut buffer = BytesMut::new();
    buffer.extend_from_slice(b"HEADER\r\nbody content here");
    
    // Find header delimiter
    if let Some(header_end) = buffer.windows(2).position(|w| w == b"\r\n") {
        let header_end = header_end + 2; // Include the delimiter
        
        // Split off the header portion
        let header = buffer.split_to(header_end);
        // buffer now contains just the body
        
        println!("Header: {:?}", String::from_utf8_lossy(&header));
        println!("Body: {:?}", String::from_utf8_lossy(&buffer));
    }
}

split_to is the inverse of split_off—it removes bytes from the front and returns them.

split_to vs split_off

use bytes::BytesMut;
 
fn split_directions() {
    let mut buf = BytesMut::from("hello world");
    
    // split_off(n): Returns bytes AFTER n, original keeps bytes BEFORE n
    let mut buf1 = BytesMut::from("hello world");
    let after = buf1.split_off(5);
    // buf1 = "hello", after = " world"
    
    // split_to(n): Returns bytes BEFORE n, original keeps bytes AFTER n
    let mut buf2 = BytesMut::from("hello world");
    let before = buf2.split_to(5);
    // before = "hello", buf2 = " world"
    
    // Both are zero-copy, both modify the original buffer
    // Choice depends on which portion you want to keep in the original
}

split_to removes from the front; split_off removes from the back.

Parsing Protocol Frames

use bytes::{BytesMut, Buf};
 
struct Frame {
    length: u32,
    data: BytesMut,
}
 
fn parse_frames(buffer: &mut BytesMut) -> Vec<Frame> {
    let mut frames = Vec::new();
    
    while buffer.len() >= 4 {
        // Read length prefix (4 bytes)
        let length = u32::from_be_bytes([
            buffer[0], buffer[1], buffer[2], buffer[3],
        ]) as usize;
        
        // Check if full frame is available
        if buffer.len() < 4 + length {
            break; // Wait for more data
        }
        
        // Remove length prefix
        buffer.advance(4);
        
        // Extract frame data
        let data = buffer.split_to(length);
        
        frames.push(Frame { length: length as u32, data });
    }
    
    frames
}
 
fn frame_parsing() {
    let mut buffer = BytesMut::new();
    
    // Frame 1: length=5, data="hello"
    buffer.extend_from_slice(&5u32.to_be_bytes());
    buffer.extend_from_slice(b"hello");
    
    // Frame 2: length=5, data="world"
    buffer.extend_from_slice(&5u32.to_be_bytes());
    buffer.extend_from_slice(b"world");
    
    // Parse all complete frames
    let frames = parse_frames(&mut buffer);
    
    assert_eq!(frames.len(), 2);
    assert_eq!(&frames[0].data[..], b"hello");
    assert_eq!(&frames[1].data[..], b"world");
    
    // buffer is now empty (all frames consumed)
    assert_eq!(buffer.len(), 0);
}

Use split_to to extract discrete frames from an accumulation buffer.

Streaming Data Processing

use bytes::BytesMut;
use std::io::{self, Read};
 
fn process_stream<R: Read>(mut reader: R) -> io::Result<Vec<BytesMut>> {
    let mut buffer = BytesMut::with_capacity(8192);
    let mut messages = Vec::new();
    
    loop {
        // Grow buffer if needed
        buffer.resize(buffer.len() + 1024, 0);
        
        // Read into the uninitialized portion
        let read = reader.read(&mut buffer[buffer.len() - 1024..])?;
        
        if read == 0 {
            break; // EOF
        }
        
        // Truncate to actual bytes read
        buffer.truncate(buffer.len() - 1024 + read);
        
        // Extract complete messages (newline-delimited for example)
        while let Some(pos) = buffer.iter().position(|&b| b == b'\n') {
            let message = buffer.split_to(pos + 1);
            messages.push(message);
        }
    }
    
    Ok(messages)
}

split_to and split_off enable efficient stream processing without copying.

Memory Management Details

use bytes::BytesMut;
 
fn memory_sharing() {
    // BytesMut uses reference-counted shared storage
    let mut buf = BytesMut::from("hello world this is a test");
    
    // First split
    let second = buf.split_off(11);
    // buf = "hello world"
    // second = " this is a test"
    
    // Both share the same underlying allocation
    // When either is dropped, reference count decreases
    // Memory is freed only when all references are dropped
    
    // This enables zero-copy slicing in many scenarios
    // But be aware that holding references prevents full deallocation
}

Split buffers share underlying storage through reference counting.

Capacity and Resizing

use bytes::BytesMut;
 
fn capacity_behavior() {
    let mut buf = BytesMut::with_capacity(100);
    buf.extend_from_slice(b"hello");
    
    // len = 5, capacity >= 100
    assert_eq!(buf.len(), 5);
    assert!(buf.capacity() >= 100);
    
    // split_off creates a new buffer with remaining capacity
    let second = buf.split_off(3);
    
    // buf has "hel", capacity may be adjusted
    // second has "lo", shares original allocation
    
    // After split, capacity distribution depends on implementation
    // The key point: no bytes are copied
}

Capacity after split depends on the internal implementation.

Working with Uninitialized Memory

use bytes::BytesMut;
 
fn uninitialized_capacity() {
    // BytesMut can reserve capacity without initializing
    let mut buf = BytesMut::with_capacity(1024);
    
    // Initially empty
    assert_eq!(buf.len(), 0);
    assert!(buf.capacity() >= 1024);
    
    // split_off on empty portion
    let empty = buf.split_off(0);
    assert_eq!(empty.len(), 0);
    
    // split_off beyond length (into reserved capacity)
    // This would panic - can only split within current length
    // buf.split_off(100); // PANIC: position beyond length
}

split_off can only split within the current length, not into reserved capacity.

Splitting at Boundaries

use bytes::BytesMut;
 
fn split_at_boundary() {
    let mut buf = BytesMut::from("header\r\n\r\nbody");
    
    // Find the header/body separator
    if let Some(pos) = buf.windows(4).position(|w| w == b"\r\n\r\n") {
        let separator_end = pos + 4;
        
        // Extract header (including separator)
        let header = buf.split_to(separator_end);
        // buf now contains just the body
        
        // Process header and body separately
        process_header(&header);
        process_body(&buf);
    }
}
 
fn process_header(header: &[u8]) {
    println!("Header: {:?}", String::from_utf8_lossy(header));
}
 
fn process_body(body: &[u8]) {
    println!("Body: {:?}", String::from_utf8_lossy(body));
}

Protocol parsing often needs to split at specific boundaries.

Comparison: split_off vs copy-based approach

use bytes::BytesMut;
 
fn copy_vs_zero_copy() {
    let mut buffer = BytesMut::from("hello world data more data");
    
    // Zero-copy with split_off
    let first = buffer.split_off(11);
    // buffer = "hello world"
    // first = " data more data"
    // No bytes were copied
    
    // Contrast with copy-based approach:
    let mut buffer2 = BytesMut::from("hello world data more data");
    
    // This copies bytes:
    let first_copy = buffer2[11..].to_vec();
    buffer2.truncate(11);
    // first_copy = " data more data" (copied)
    // buffer2 = "hello world"
    
    // The zero-copy approach is more efficient for large buffers
}

split_off avoids allocation and copying; traditional slicing copies.

Chunking Large Buffers

use bytes::BytesMut;
 
fn chunking() {
    let mut large = BytesMut::from(vec![0u8; 10_000]);
    
    let mut chunks = Vec::new();
    let chunk_size = 1000;
    
    while large.len() > chunk_size {
        let chunk = large.split_off(large.len() - chunk_size);
        chunks.push(chunk);
        // Wait - this gives us the LAST chunk in large
        // split_off returns the suffix, not prefix
    }
    
    // Correct approach for prefix chunks:
    let mut large2 = BytesMut::from(vec![0u8; 10_000]);
    let mut chunks2 = Vec::new();
    
    while large2.len() > chunk_size {
        chunks2.push(large2.split_to(chunk_size));
    }
    chunks2.push(large2); // Remaining
    
    assert_eq!(chunks2.len(), 10);
    for chunk in &chunks2 {
        assert_eq!(chunk.len(), 1000);
    }
}

Use split_to for prefix chunks, split_off for suffix chunks.

Advanced: Multiple Splits

use bytes::BytesMut;
 
fn multiple_splits() {
    let mut buf = BytesMut::from("one:two:three:four");
    
    let mut parts = Vec::new();
    
    while let Some(pos) = buf.iter().position(|&b| b == b':') {
        let part = buf.split_to(pos);
        buf.advance(1); // Skip the delimiter
        parts.push(part);
    }
    
    // Don't forget the last part
    if !buf.is_empty() {
        parts.push(buf);
    }
    
    assert_eq!(parts.len(), 4);
    assert_eq!(&parts[0][..], b"one");
    assert_eq!(&parts[3][..], b"four");
}

Repeated splits enable delimiter-based parsing without copying.

Thread Safety Considerations

use bytes::BytesMut;
 
fn thread_safety() {
    let mut buf = BytesMut::from("hello world");
    
    // split_off requires &mut self
    let second = buf.split_off(5);
    
    // After split, buf and second are independent
    // They can be sent to different threads
    
    // Note: BytesMut is not Clone (unlike Bytes)
    // Each split creates a unique owner of that portion
    
    // The underlying storage is reference counted
    // But mutable access is exclusive to each owner
}

After splitting, each BytesMut can be sent to different threads.

Integration with Bytes (Immutable)

use bytes::{BytesMut, Bytes};
 
fn convert_to_bytes() {
    let mut buf = BytesMut::from("hello world");
    
    let second = buf.split_off(5);
    
    // Convert to immutable Bytes for sharing
    let immutable_first: Bytes = buf.freeze();
    let immutable_second: Bytes = second.freeze();
    
    // Bytes is Clone and can be shared cheaply
    // BytesMut is unique and mutable
}

freeze() converts BytesMut to immutable Bytes for efficient sharing.

Real-World Pattern: HTTP Parser

use bytes::BytesMut;
 
struct HttpParser {
    buffer: BytesMut,
}
 
impl HttpParser {
    fn new() -> Self {
        Self {
            buffer: BytesMut::with_capacity(8192),
        }
    }
    
    fn feed(&mut self, data: &[u8]) {
        self.buffer.extend_from_slice(data);
    }
    
    fn try_parse(&mut self) -> Option<HttpRequest> {
        // Find end of headers
        let header_end = self.buffer.windows(4)
            .position(|w| w == b"\r\n\r\n")?;
        
        // Extract headers section
        let headers_bytes = self.buffer.split_to(header_end + 4);
        self.buffer.advance(0); // Keep remaining in buffer
        
        // Parse content-length from headers (simplified)
        let content_length = self.parse_content_length(&headers_bytes)?;
        
        if self.buffer.len() < content_length {
            // Not enough body data yet
            // Re-insert headers (inefficient for this example)
            return None;
        }
        
        // Extract body
        let body = self.buffer.split_to(content_length);
        
        Some(HttpRequest {
            headers: headers_bytes,
            body,
        })
    }
    
    fn parse_content_length(&self, headers: &[u8]) -> Option<usize> {
        // Simplified: would parse actual headers
        Some(0)
    }
}
 
struct HttpRequest {
    headers: BytesMut,
    body: BytesMut,
}

split_to and split_off enable incremental parsing without copying.

Synthesis

Quick reference:

use bytes::BytesMut;
 
let mut buf = BytesMut::from("hello world");
 
// split_off(n): Returns bytes AFTER n
// Original keeps bytes 0..n, returned has bytes n..end
let suffix = buf.split_off(5);
// buf = "hello", suffix = " world"
 
// split_to(n): Returns bytes BEFORE n  
// Returned has bytes 0..n, original keeps bytes n..end
let mut buf2 = BytesMut::from("hello world");
let prefix = buf2.split_to(5);
// prefix = "hello", buf2 = " world"
 
// Key properties:
// 1. Zero-copy: just adjusts pointers
// 2. Modifies original in place
// 3. Returns new BytesMut
// 4. Both share underlying allocation (reference counted)
 
// Common patterns:
// - split_to: Extract messages from stream buffer
// - split_off: Separate suffix from accumulated data
// - Combine with advance() for delimiter skipping

Key insight: split_off and split_to enable zero-copy buffer division by adjusting internal pointers rather than copying bytes. Use split_to when you want to extract and process the front portion (common for parsing), and split_off when you want to extract the back portion (common for separating processed from unprocessed data). Both methods modify the original buffer and return a new buffer that shares the same underlying storage through reference counting. This makes them efficient for stream processing, protocol parsing, and any scenario where you accumulate data and extract portions for handling.

What is the purpose of bytes::BytesMut::split_off for dividing mutable buffers?