docs: add deque examples and benchmarks

Author: jeresoftx

Cargo.toml

@@ -61,6 +61,18 @@ path = "examples/soluciones/queue_round_robin.rs"
 name = "solution_queue_filter_ready_jobs"
 path = "examples/soluciones/queue_filter_ready_jobs.rs"
 
+[[example]]
+name = "solution_deque_trace_ends"
+path = "examples/soluciones/deque_trace_ends.rs"
+
+[[example]]
+name = "solution_deque_sliding_window"
+path = "examples/soluciones/deque_sliding_window.rs"
+
+[[example]]
+name = "solution_deque_browser_history"
+path = "examples/soluciones/deque_browser_history.rs"
+
 [[bench]]
 name = "vector_bench"
 path = "benches/vector_bench.rs"
@@ -80,3 +92,8 @@ harness = false
 name = "queue_bench"
 path = "benches/queue_bench.rs"
 harness = false
+
+[[bench]]
+name = "deque_bench"
+path = "benches/deque_bench.rs"
+harness = false

benches/deque_bench.rs

@@ -0,0 +1,95 @@
+use rust_data_structures::deque::Deque;
+use rust_data_structures::linked_list::LinkedList;
+use rust_data_structures::vector::Vector;
+use std::hint::black_box;
+use std::time::{Duration, Instant};
+
+const SIZE: usize = 30_000;
+
+fn main() {
+    println!("deque benchmark (manual, std::time::Instant)");
+    println!("size: {SIZE}");
+    println!("push/pop front: {:?}", bench_deque_front());
+    println!("push/pop back: {:?}", bench_deque_back());
+    println!("indexed access: {:?}", bench_deque_get());
+    println!(
+        "linked list front comparison: {:?}",
+        bench_linked_list_front()
+    );
+    println!("vector front remove comparison: {:?}", bench_vector_front());
+}
+
+fn bench_deque_front() -> Duration {
+    let start = Instant::now();
+    let mut deque = Deque::new();
+
+    for value in 0..SIZE {
+        deque.push_front(black_box(value));
+    }
+
+    while let Some(value) = deque.pop_front() {
+        black_box(value);
+    }
+
+    start.elapsed()
+}
+
+fn bench_deque_back() -> Duration {
+    let start = Instant::now();
+    let mut deque = Deque::new();
+
+    for value in 0..SIZE {
+        deque.push_back(black_box(value));
+    }
+
+    while let Some(value) = deque.pop_back() {
+        black_box(value);
+    }
+
+    start.elapsed()
+}
+
+fn bench_deque_get() -> Duration {
+    let start = Instant::now();
+    let mut deque = Deque::new();
+
+    for value in 0..SIZE {
+        deque.push_back(value);
+    }
+
+    for index in 0..SIZE {
+        black_box(deque.get(index));
+    }
+
+    start.elapsed()
+}
+
+fn bench_linked_list_front() -> Duration {
+    let start = Instant::now();
+    let mut list = LinkedList::new();
+
+    for value in 0..SIZE {
+        list.push_front(black_box(value));
+    }
+
+    while let Some(value) = list.pop_front() {
+        black_box(value);
+    }
+
+    start.elapsed()
+}
+
+fn bench_vector_front() -> Duration {
+    let start = Instant::now();
+    let mut vector = Vector::new();
+
+    for value in 0..SIZE {
+        vector.push(black_box(value));
+    }
+
+    while !vector.is_empty() {
+        black_box(vector.remove(0));
+    }
+
+    start.elapsed()
+}

diagrams/05-deque.mmd

@@ -0,0 +1,33 @@
+flowchart LR
+    title["Deque: dos extremos sobre buffer circular"]
+
+    subgraph metadata["Metadatos"]
+        head["head = 4"]
+        len["len = 5"]
+        cap["capacity = 8"]
+    end
+
+    subgraph buffer["Buffer fisico"]
+        slot0["0: D"]
+        slot1["1: E (back)"]
+        slot2["2: libre"]
+        slot3["3: libre"]
+        slot4["4: A (front)"]
+        slot5["5: B"]
+        slot6["6: C"]
+        slot7["7: libre"]
+    end
+
+    head --> slot4
+    len --> slot1
+    cap --> slot7
+
+    push_front["push_front(Z)<br/>mueve head hacia atras"]
+    pop_front["pop_front()<br/>toma front y avanza head"]
+    push_back["push_back(F)<br/>escribe en (head + len) % capacity"]
+    pop_back["pop_back()<br/>toma (head + len - 1) % capacity"]
+
+    push_front --> slot3
+    pop_front --> head
+    push_back --> slot2
+    pop_back --> slot1

examples/deque_advanced.rs

@@ -0,0 +1,19 @@
+use rust_data_structures::deque::Deque;
+
+fn main() {
+    let mut deque = Deque::with_capacity(4);
+
+    deque.push_back("B");
+    deque.push_back("C");
+    deque.push_back("D");
+    deque.pop_front();
+    deque.push_back("E");
+    deque.push_front("A");
+
+    println!("capacidad: {}", deque.capacity());
+    println!(
+        "orden logico: {:?}",
+        deque.iter().copied().collect::<Vec<_>>()
+    );
+    println!("indice 2: {:?}", deque.get(2));
+}

examples/deque_basic.rs

@@ -0,0 +1,12 @@
+use rust_data_structures::deque::Deque;
+
+fn main() {
+    let mut deque = Deque::new();
+
+    deque.push_back("centro");
+    deque.push_front("inicio");
+    deque.push_back("final");
+
+    println!("frente: {}", deque.front().unwrap());
+    println!("fondo: {}", deque.back().unwrap());
+}

examples/deque_intermediate.rs

@@ -0,0 +1,13 @@
+use rust_data_structures::deque::Deque;
+
+fn main() {
+    let mut work = Deque::new();
+
+    work.push_back("sincronizar docs");
+    work.push_back("correr tests");
+    work.push_front("incidente urgente");
+
+    while let Some(job) = work.pop_front() {
+        println!("procesando: {job}");
+    }
+}

examples/deque_real_case.rs

@@ -0,0 +1,23 @@
+use rust_data_structures::deque::Deque;
+
+fn main() {
+    let mut tabs = Deque::new();
+
+    tabs.push_back(Tab::new("Inicio"));
+    tabs.push_back(Tab::new("Curso"));
+    tabs.push_front(Tab::new("Pin: Roadmap"));
+
+    while let Some(tab) = tabs.pop_front() {
+        println!("visitando: {}", tab.title);
+    }
+}
+
+struct Tab {
+    title: &'static str,
+}
+
+impl Tab {
+    fn new(title: &'static str) -> Self {
+        Self { title }
+    }
+}

examples/soluciones/deque_browser_history.rs

@@ -0,0 +1,21 @@
+use rust_data_structures::deque::Deque;
+
+fn main() {
+    let mut history = Deque::new();
+    history.push_back("inicio");
+    history.push_back("curso");
+    history.push_back("capitulo");
+
+    assert_eq!(go_back(&mut history), Some("capitulo"));
+    history.push_front("pin-roadmap");
+
+    assert_eq!(
+        history.iter().copied().collect::<Vec<_>>(),
+        vec!["pin-roadmap", "inicio", "curso"]
+    );
+    println!("{:?}", history.iter().copied().collect::<Vec<_>>());
+}
+
+fn go_back(history: &mut Deque<&'static str>) -> Option<&'static str> {
+    history.pop_back()
+}

examples/soluciones/deque_sliding_window.rs

@@ -0,0 +1,39 @@
+use rust_data_structures::deque::Deque;
+
+fn main() {
+    let values = [4, 2, 12, 3, 8];
+    let maximums = sliding_window_maximums(&values, 3);
+
+    assert_eq!(maximums, vec![12, 12, 12]);
+    println!("{maximums:?}");
+}
+
+fn sliding_window_maximums(values: &[i32], window: usize) -> Vec<i32> {
+    let mut indexes = Deque::new();
+    let mut maximums = Vec::new();
+
+    for index in 0..values.len() {
+        while let Some(&front) = indexes.front() {
+            if front + window > index {
+                break;
+            }
+            indexes.pop_front();
+        }
+
+        while let Some(&back) = indexes.back() {
+            if values[back] >= values[index] {
+                break;
+            }
+            indexes.pop_back();
+        }
+
+        indexes.push_back(index);
+
+        if index + 1 >= window {
+            let front = indexes.front().copied().expect("window has a maximum");
+            maximums.push(values[front]);
+        }
+    }
+
+    maximums
+}

examples/soluciones/deque_trace_ends.rs

@@ -0,0 +1,16 @@
+use rust_data_structures::deque::Deque;
+
+fn main() {
+    let mut deque = Deque::new();
+    let mut trace = Vec::new();
+
+    deque.push_back("B");
+    deque.push_front("A");
+    deque.push_back("C");
+    trace.push(deque.pop_front());
+    trace.push(deque.pop_back());
+    trace.push(deque.pop_front());
+
+    assert_eq!(trace, vec![Some("A"), Some("C"), Some("B")]);
+    println!("{trace:?}");
+}