docs: add linked list examples and benchmarks

Author: jeresoftx

Cargo.toml

@@ -25,7 +25,24 @@ path = "examples/soluciones/vector_insert_sorted.rs"
 name = "solution_vector_retain_prefix"
 path = "examples/soluciones/vector_retain_prefix.rs"
 
+[[example]]
+name = "solution_linked_list_reverse_input"
+path = "examples/soluciones/linked_list_reverse_input.rs"
+
+[[example]]
+name = "solution_linked_list_move_front_to_back"
+path = "examples/soluciones/linked_list_move_front_to_back.rs"
+
+[[example]]
+name = "solution_linked_list_remove_every_other"
+path = "examples/soluciones/linked_list_remove_every_other.rs"
+
 [[bench]]
 name = "vector_bench"
 path = "benches/vector_bench.rs"
 harness = false
+
+[[bench]]
+name = "linked_list_bench"
+path = "benches/linked_list_bench.rs"
+harness = false

benches/linked_list_bench.rs

@@ -0,0 +1,80 @@
+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 = 20_000;
+
+fn main() {
+    println!("linked list benchmark (manual, std::time::Instant)");
+    println!("size: {SIZE}");
+    println!("push_front: {:?}", bench_push_front());
+    println!("push_back: {:?}", bench_push_back());
+    println!("pop_front: {:?}", bench_pop_front());
+    println!("iterate linked list: {:?}", bench_linked_list_iteration());
+    println!("iterate vector: {:?}", bench_vector_iteration());
+}
+
+fn bench_push_front() -> Duration {
+    let start = Instant::now();
+    let mut list = LinkedList::new();
+
+    for value in 0..SIZE {
+        list.push_front(black_box(value));
+    }
+
+    black_box(list.len());
+    start.elapsed()
+}
+
+fn bench_push_back() -> Duration {
+    let start = Instant::now();
+    let mut list = LinkedList::new();
+
+    for value in 0..SIZE {
+        list.push_back(black_box(value));
+    }
+
+    black_box(list.len());
+    start.elapsed()
+}
+
+fn bench_pop_front() -> Duration {
+    let mut list = LinkedList::new();
+    for value in 0..SIZE {
+        list.push_back(value);
+    }
+
+    let start = Instant::now();
+    while let Some(value) = list.pop_front() {
+        black_box(value);
+    }
+
+    start.elapsed()
+}
+
+fn bench_linked_list_iteration() -> Duration {
+    let mut list = LinkedList::new();
+    for value in 0..SIZE {
+        list.push_front(value);
+    }
+
+    let start = Instant::now();
+    let sum: usize = list.iter().copied().map(black_box).sum();
+
+    black_box(sum);
+    start.elapsed()
+}
+
+fn bench_vector_iteration() -> Duration {
+    let mut vector = Vector::with_capacity(SIZE);
+    for value in 0..SIZE {
+        vector.push(value);
+    }
+
+    let start = Instant::now();
+    let sum: usize = vector.iter().copied().map(black_box).sum();
+
+    black_box(sum);
+    start.elapsed()
+}

diagrams/02-linked-list.mmd

@@ -0,0 +1,19 @@
+flowchart LR
+    title["Linked List: nodos enlazados por ownership"]
+
+    list["LinkedList<br/>head + len"]
+    node0["Node A<br/>value + next"]
+    node1["Node B<br/>value + next"]
+    node2["Node C<br/>value + next"]
+    none["None"]
+
+    list --> node0
+    node0 --> node1
+    node1 --> node2
+    node2 --> none
+
+    push_front["push_front(X)<br/>nuevo nodo apunta al head anterior"]
+    push_front --> list
+
+    push_back["push_back(X)<br/>recorre hasta next = None"]
+    push_back --> node2

examples/linked_list_advanced.rs

@@ -0,0 +1,15 @@
+use rust_data_structures::linked_list::LinkedList;
+
+fn main() {
+    let mut list = LinkedList::new();
+
+    for value in 1..=5 {
+        list.push_back(value);
+    }
+
+    let removed = list.remove(2).expect("index 2 exists");
+    let remaining = list.iter().copied().collect::<Vec<_>>();
+
+    println!("removido: {removed}");
+    println!("restantes: {remaining:?}");
+}

examples/linked_list_basic.rs

@@ -0,0 +1,12 @@
+use rust_data_structures::linked_list::LinkedList;
+
+fn main() {
+    let mut pages = LinkedList::new();
+
+    pages.push_front("capitulo-vector");
+    pages.push_front("prefacio");
+
+    println!("primera pagina: {}", pages.front().unwrap());
+    println!("ultima pagina: {}", pages.back().unwrap());
+    println!("paginas: {}", pages.len());
+}

examples/linked_list_intermediate.rs

@@ -0,0 +1,13 @@
+use rust_data_structures::linked_list::LinkedList;
+
+fn main() {
+    let mut queue = LinkedList::new();
+
+    queue.push_back("validar README");
+    queue.push_back("revisar doctests");
+    queue.push_back("actualizar ROADMAP");
+
+    while let Some(task) = queue.pop_front() {
+        println!("procesando: {task}");
+    }
+}

examples/linked_list_real_case.rs

@@ -0,0 +1,24 @@
+use rust_data_structures::linked_list::LinkedList;
+
+fn main() {
+    let mut retry_queue = LinkedList::new();
+
+    retry_queue.push_back(Job::new("sync-calendar", 1));
+    retry_queue.push_back(Job::new("send-webhook", 2));
+    retry_queue.push_back(Job::new("rebuild-index", 1));
+
+    while let Some(job) = retry_queue.pop_front() {
+        println!("ejecutando {} (intento {})", job.name, job.attempt);
+    }
+}
+
+struct Job {
+    name: &'static str,
+    attempt: u8,
+}
+
+impl Job {
+    fn new(name: &'static str, attempt: u8) -> Self {
+        Self { name, attempt }
+    }
+}

examples/soluciones/linked_list_move_front_to_back.rs

@@ -0,0 +1,20 @@
+use rust_data_structures::linked_list::LinkedList;
+
+fn main() {
+    let mut list = LinkedList::new();
+    list.push_back("a");
+    list.push_back("b");
+    list.push_back("c");
+
+    move_front_to_back(&mut list);
+
+    let values = list.iter().copied().collect::<Vec<_>>();
+    assert_eq!(values, vec!["b", "c", "a"]);
+    println!("{values:?}");
+}
+
+fn move_front_to_back<T>(list: &mut LinkedList<T>) {
+    if let Some(value) = list.pop_front() {
+        list.push_back(value);
+    }
+}

examples/soluciones/linked_list_remove_every_other.rs

@@ -0,0 +1,23 @@
+use rust_data_structures::linked_list::LinkedList;
+
+fn main() {
+    let mut list = LinkedList::new();
+    for value in 1..=8 {
+        list.push_back(value);
+    }
+
+    remove_every_other(&mut list);
+
+    let values = list.iter().copied().collect::<Vec<_>>();
+    assert_eq!(values, vec![1, 3, 5, 7]);
+    println!("{values:?}");
+}
+
+fn remove_every_other<T>(list: &mut LinkedList<T>) {
+    let mut index = 1;
+
+    while index < list.len() {
+        list.remove(index);
+        index += 1;
+    }
+}

examples/soluciones/linked_list_reverse_input.rs

@@ -0,0 +1,19 @@
+use rust_data_structures::linked_list::LinkedList;
+
+fn main() {
+    let reversed = reverse_with_push_front([1, 2, 3, 4]);
+    let values = reversed.iter().copied().collect::<Vec<_>>();
+
+    assert_eq!(values, vec![4, 3, 2, 1]);
+    println!("{values:?}");
+}
+
+fn reverse_with_push_front(values: impl IntoIterator<Item = i32>) -> LinkedList<i32> {
+    let mut list = LinkedList::new();
+
+    for value in values {
+        list.push_front(value);
+    }
+
+    list
+}