Struct SumQueue

pub struct SumQueue<T> { /* private fields */ }

Main struct that holds the queue of elements.

There are different ways to create the queue:

use std::time::Duration;
use sum_queue::SumQueue;

let mut queue: SumQueue<i32>;

// Create a queue with elements that expires after 60 seconds
queue = SumQueue::new(Duration::from_secs(60));
// Create with 500 milliseconds expiration and an initial capacity of 20 elements
queue = SumQueue::with_capacity(Duration::from_millis(500), 20);

Implementations

impl<T> SumQueue<T>

pub fn new(max_age_duration: Duration) -> SumQueue<T>

Creates an empty SumQueue, where the elements inside will live max_age_duration at maximum.

pub fn with_capacity(max_age_duration: Duration, capacity: usize) -> SumQueue<T>

Creates an empty SumQueue with a specific initial capacity. This preallocates enough memory for capacity elements, so that the BinaryHeap inside the SumQueue does not have to be reallocated until it contains at least that many values. The elements inside the queue will live max_age_duration time at maximum.

pub fn push(&mut self, item: T) -> usize

Pushes an item onto the heap of the queue.

See BinaryHeap::push to known more about the time complexity.

It returns the size of the queue, and before the element is pushed to the heap, it also drops all expired elements in the queue.

use std::time::Duration;
use sum_queue::SumQueue;
let mut queue = SumQueue::new(Duration::from_secs(60));
queue.push(1);
queue.push(5);
assert_eq!(queue.push(2), 3);
assert_eq!(queue.iter().collect::<Vec<_>>(), vec![&1, &5, &2]);

pub fn clear(&mut self)

Drops all items.

pub fn len(&mut self) -> usize

Returns the length of the heap.

It takes a mutable reference of self because before return the size it also cleans all the expired elements of the queue, so only no expired elements are count.

pub fn is_empty(&mut self) -> bool

Checks if the heap is empty. Expired elements are not taken into account because are droped by is_empty() before return the result.

use std::time::Duration;
use std::thread;
use sum_queue::SumQueue;
let mut queue = SumQueue::new(Duration::from_millis(600));

assert!(queue.is_empty());

queue.push(123);
queue.push(555);

assert!(!queue.is_empty());

thread::sleep(Duration::from_secs(1));

assert!(queue.is_empty());

pub fn capacity(&self) -> usize

Returns the number of elements the heap can hold without reallocating.

use std::time::Duration;
use sum_queue::SumQueue;
let mut queue: SumQueue<char> = SumQueue::with_capacity(Duration::from_secs(60), 5);
assert_eq!(queue.capacity(), 5);
assert_eq!(queue.len(), 0);

pub fn max_age(&self) -> Duration

Returns the max time the elements will live in the queue.

use std::time::Duration;
use sum_queue::SumQueue;
let mut queue: SumQueue<char> = SumQueue::new(Duration::from_secs(60));
assert_eq!(queue.max_age().as_secs(), 60);

pub fn peek(&mut self) -> Option<&T>

Returns the first item in the heap, or None if it is empty.

Before the element is returned, it also drops all expired elements from the queue.

use std::time::Duration;
use sum_queue::SumQueue;
let mut queue = SumQueue::new(Duration::from_secs(60));
assert_eq!(queue.peek(), None);
queue.push("Hello");
queue.push("World");
queue.push("!");
assert_eq!(queue.peek(), Some(&"Hello"));

pub fn pop(&mut self) -> Option<T>

Removes the first item from the heap and returns it, or None if it is empty.

Before the element is dropped from the queue and returned, it also drops all expired elements.

use std::time::Duration;
use sum_queue::SumQueue;
let mut queue = SumQueue::with_capacity(Duration::from_secs(60), 5);
assert_eq!(queue.pop(), None);
queue.push('a');
queue.push('x');
queue.push('c');
assert_eq!(queue.pop(), Some('a'));
assert_eq!(queue.pop(), Some('x'));
assert_eq!(queue.pop(), Some('c'));
assert_eq!(queue.pop(), None);

pub fn iter(&mut self) -> Iter<'_, T>

Returns an iterator visiting all values in the underlying heap, in same order they were pushed.

Before return the iterator, it also drops all expired elements.

The iterator does not change the state of the queue, this method takes ownership of the queue because as mentioned above it clears the expired elements before return the iterator, even if the iterator is not consumed later on.

use std::time::Duration;
use sum_queue::SumQueue;
let mut queue = SumQueue::new(Duration::from_secs(60));
queue.push('a');
queue.push('z');
queue.push('x');
assert_eq!(queue.iter().collect::<Vec<_>>(), vec![&'a', &'z', &'x']);

impl<T: Copy + Ord + Add<Output = T>> SumQueue<T>

pub fn stats(&mut self) -> QueueStats<T>

Get statistics of the queue. The type of the elements on it needs to implements the Copy, Ord and Add traits.

Before the stats are returned, it also drops all expired elements.

use std::time::Duration;
use sum_queue::SumQueue;
let mut queue: SumQueue<i64> = SumQueue::new(Duration::from_secs(1000));
queue.push(-10);
queue.push(50);
queue.push(40);
queue.push(20);
let stats = queue.stats();
assert_eq!(stats.min, Some(-10));
assert_eq!(stats.max, Some(50));
assert_eq!(stats.sum, Some(100));
assert_eq!(stats.len, 4);

See also push_and_stats.

pub fn push_and_stats(&mut self, item: T) -> QueueStats<T>

Pushes an item onto the heap of the queue, and returns the stats of the queue. The type of the elements on it need to implements the Copy, Ord and Add traits.

Before push and return the stats, it also drops all expired elements.

use std::time::Duration;
use sum_queue::SumQueue;
let mut queue: SumQueue<i64> = SumQueue::new(Duration::from_secs(1000));
queue.push(-10);
queue.push(50);
queue.push(40);
let stats = queue.push_and_stats(20);
assert_eq!(stats.min, Some(-10));
assert_eq!(stats.max, Some(50));
assert_eq!(stats.sum, Some(100));
assert_eq!(stats.len, 4);

Use push instead if you don’t need the stats or the elements in the heap don’t implement any of the required traits.