Struct CircularBuffer

pub struct CircularBuffer<T: Clone> { /* private fields */ }

Represents a FIFO CircularBuffer<T> data structure.

This structure is a limited capacity queue, with optional provisions for default values. Under normal circumstances, the size of the queue grows until it reaches its capacity, at which point any further additions push out its oldest member.

If default values are specified, then the size of the queue is always equal to its capacity, with empty slots occupied by the specified default value.

Type parameters

• T: Any type that implements the Clone trait.

Examples

let mut cbuf = CircularBuffer::<isize>::new(3);
let mut cbuf_def = CircularBuffer::with_default(3, 0isize);

// Check sizes
assert_eq!(cbuf.size(), 0);
assert_eq!(cbuf_def.size(), 3);

// Add elements
cbuf.add(6);
cbuf_def.add(7);

// Peek at the next element scheduled for removal
assert_eq!(cbuf.peek().unwrap(), 6);
assert_eq!(cbuf_def.peek().unwrap(), 0);

Implementations

impl<T: Clone> CircularBuffer<T>

pub fn new(capacity: usize) -> CircularBuffer<T>

Default CircularBuffer<T> initializer

Returns

A new, empty CircularBuffer<T>

Examples

let cbuf: CircularBuffer<isize> = CircularBuffer::new(3);
assert_eq!(cbuf.size(), 0);
assert_eq!(cbuf.capacity(), 3);

Examples found in repository

examples/cbuf.rs (line 11)

fn main() {
    println!("\nCircular buffer - typical usage");
    println!("--");

    println!("\nCreate an empty circular buffer with capacity 5:");
    println!("let mut cbuf: CircularBuffer<isize> = CircularBuffer::new(5);");
    let mut cbuf: CircularBuffer<isize> = CircularBuffer::new(5);

    println!("\nAdd elements to it:");
    println!("cbuf.add(1);");
    println!("> {:?}", cbuf.add(1));
    println!("cbuf.add(-2);");
    println!("> {:?}", cbuf.add(-2));
    println!("cbuf.add(3);");
    println!("> {:?}", cbuf.add(3));

    println!("\nCheck the buffer's size:");
    println!("cbuf.size();  // Should be 3");
    println!("> {}", cbuf.size());

    println!("\nRemove elements from it:");
    println!("cbuf.remove();  // Should be Ok(1)");
    println!("> {:?}", cbuf.remove());

    println!("\nCheck the buffer's size:");
    println!("cbuf.size();  // Should be 2");
    println!("> {}", cbuf.size());

    println!("\nPeek at the next element to be removed:");
    println!("cbuf.peek();  // Should be Ok(-2)");
    println!("> {:?}", cbuf.peek());

    println!("\nFill the buffer:");
    println!("cbuf.add(-7);");
    println!("> {:?}", cbuf.add(-7));
    println!("cbuf.add(8);");
    println!("> {:?}", cbuf.add(8));
    println!("cbuf.add(-9);");
    println!("> {:?}", cbuf.add(-9));

    println!("\nCheck the buffer's size:");
    println!("cbuf.size();  // Should be 5");
    println!("> {}", cbuf.size());

    println!("\nAdd a new element to the buffer:");
    println!("cbuf.add(10);  // Should be OK(Some(-2))");
    println!("{:?}", cbuf.add(10));

    println!("\nCheck the buffer's size:");
    println!("cbuf.size();  // Should still be 5");
    println!("> {}", cbuf.size());

    println!("\n--\n");
}

pub fn with_default(capacity: usize, default_value: T) -> CircularBuffer<T>

Create a CircularBuffer<T> with default values

Returns

A new CircularBuffer<T> filled with default values

Examples

let cbuf_def = CircularBuffer::with_default(3, -1isize);
assert_eq!(cbuf_def.size(), 3);
assert_eq!(cbuf_def.capacity(), 3);
assert_eq!(cbuf_def.peek(), Ok(-1));

Examples found in repository

examples/cbuf_def.rs (line 11)

fn main() {
    println!("\nCircular buffer with default values - typical usage");
    println!("--");

    println!("\nCreate a circular buffer with capacity 3 and default -1:");
    println!("let mut cbuf_def: CircularBuffer<isize> = CircularBuffer::with_default(3, -1);");
    let mut cbuf_def: CircularBuffer<isize> = CircularBuffer::with_default(3, -1);

    println!("\nCheck the buffer's size - should always be equal to the capacity:");
    println!("cbuf_def.size();  // Should be 3");
    println!("> {}", cbuf_def.size());

    println!("\nPeek at the next element to be removed:");
    println!("cbuf_def.peek();  // Should be Ok(-1)");
    println!("> {:?}", cbuf_def.peek());

    println!("\nAdd a new element to the buffer:");
    println!("cbuf_def.add(45);  // Should be Ok(Some(-1))");
    println!("{:?}", cbuf_def.add(45));

    println!("\nPeek at the next element to be removed:");
    println!("cbuf_def.peek();  // Should be Ok(-1)");
    println!("> {:?}", cbuf_def.peek());

    println!("\nFill the buffer:");
    println!("cbuf_def.add(56);");
    println!("> {:?}", cbuf_def.add(56));
    println!("cbuf_def.add(67);");
    println!("> {:?}", cbuf_def.add(67));

    println!("\nPeek at the next element to be removed:");
    println!("cbuf_def.peek();  // Should be Ok(45)");
    println!("> {:?}", cbuf_def.peek());

    println!("\nEmpty the buffer:");
    println!("cbuf_def.remove();");
    println!("{:?}", cbuf_def.remove());
    println!("cbuf_def.remove();");
    println!("{:?}", cbuf_def.remove());
    println!("cbuf_def.remove();");
    println!("{:?}", cbuf_def.remove());

    println!("\nConfirm the buffer's size:");
    println!("cbuf_def.size();  // Should be 3");
    println!("> {}", cbuf_def.size());

    println!("\nPeek at the next element to be removed:");
    println!("cbuf_def.peek();  // Should be Ok(-1)");
    println!("> {:?}", cbuf_def.peek());

    println!("\n--\n");
}

pub fn capacity(&self) -> usize

Gets the capacity of the CircularBuffer<T>

Returns

The number of allowed elements in the buffer

Examples

let mut cbuf: CircularBuffer<isize> = CircularBuffer::new(3);
assert_eq!(cbuf.capacity(), 3);

Trait Implementations

impl<T: Debug + Clone> Debug for CircularBuffer<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Clone> IsQueue<T> for CircularBuffer<T>

fn add(&mut self, val: T) -> Result<Option<T>, &str>

Adds an element to a circular buffer

Parameters

• val: Value to add to the buffer

Returns

• Ok(Some(T)): The oldest value in the buffer, in case the addition causes an overflow.
• Ok(None): Nothing, if the buffer has room for the added element

Examples

let mut cbuf: CircularBuffer<isize> = CircularBuffer::new(3);
let mut cbuf_def = CircularBuffer::with_default(3, 5isize);
assert_eq!(cbuf.add(42), Ok(None));
assert_eq!(cbuf_def.add(42), Ok(Some(5)));

fn remove(&mut self) -> Result<T, &str>

Removes an element from the circular buffer and returns it.

For circular buffers with default values, removing an element will add a new default value into the buffer.

Returns

• Ok(T): The oldest element in the buffer
• Error

Errors

Returns an error if an attempt is made to remove an element from an empty buffer

Examples

let mut cbuf: CircularBuffer<isize> = CircularBuffer::new(3);
cbuf.add(42);
assert_eq!(cbuf.remove(), Ok(42));
assert_eq!(cbuf.size(), 0);

let mut cbuf_def = CircularBuffer::with_default(3, 4isize);
cbuf_def.add(42);
assert_eq!(cbuf_def.remove(), Ok(4));

fn peek(&self) -> Result<T, &str>

Peek at the head of the circular buffer

Returns

• Ok(T): The next element scheduled for removal from the buffer
• Error

Errors

Returns an error if an attempt is made to peek into an empty buffer

Examples

let mut cbuf: CircularBuffer<isize> = CircularBuffer::new(3);
cbuf.add(42);
assert_eq!(cbuf.peek(), Ok(42));

fn size(&self) -> usize

Gets the size of the circular buffer

Returns

The number of elements in the buffer. Note, this includes default values, which means that the size of a buffer with default values should always be equal to its capacity

Examples

let mut cbuf: CircularBuffer<isize> = CircularBuffer::new(3);
assert_eq!(cbuf.size(), 0);
cbuf.add(42);
assert_eq!(cbuf.size(), 1);