feat: add skip list learning artifacts

Author: jeresoftx

Cargo.toml

@@ -145,6 +145,18 @@ path = "examples/soluciones/bloom_filter_size_estimate.rs"
 name = "solution_bloom_filter_false_positive_probe"
 path = "examples/soluciones/bloom_filter_false_positive_probe.rs"
 
+[[example]]
+name = "solution_skip_list_trace_levels"
+path = "examples/soluciones/skip_list_trace_levels.rs"
+
+[[example]]
+name = "solution_skip_list_ordered_index"
+path = "examples/soluciones/skip_list_ordered_index.rs"
+
+[[example]]
+name = "solution_skip_list_expiring_window"
+path = "examples/soluciones/skip_list_expiring_window.rs"
+
 [[bench]]
 name = "vector_bench"
 path = "benches/vector_bench.rs"
@@ -199,3 +211,8 @@ harness = false
 name = "bloom_filter_bench"
 path = "benches/bloom_filter_bench.rs"
 harness = false
+
+[[bench]]
+name = "skip_list_bench"
+path = "benches/skip_list_bench.rs"
+harness = false

benches/skip_list_bench.rs

@@ -0,0 +1,74 @@
+use rust_data_structures::skip_list::SkipList;
+use std::collections::BTreeSet;
+use std::hint::black_box;
+use std::time::{Duration, Instant};
+
+const SIZE: i32 = 20_000;
+
+fn main() {
+    println!("skip list benchmark (manual, std::time::Instant)");
+    println!("size: {SIZE}");
+    println!("ordered insert: {:?}", bench_ordered_insert());
+    println!("permuted insert: {:?}", bench_permuted_insert());
+    println!("search: {:?}", bench_search());
+    println!("iteration: {:?}", bench_iteration());
+    println!("std btreeset search: {:?}", bench_btreeset_search());
+}
+
+fn bench_ordered_insert() -> Duration {
+    let start = Instant::now();
+    let mut list = SkipList::with_seed(20, 0.5, 1).unwrap();
+    for value in 0..SIZE {
+        black_box(list.insert(value));
+    }
+    start.elapsed()
+}
+
+fn bench_permuted_insert() -> Duration {
+    let start = Instant::now();
+    let mut list = SkipList::with_seed(20, 0.5, 1).unwrap();
+    for value in permuted_values() {
+        black_box(list.insert(value));
+    }
+    start.elapsed()
+}
+
+fn bench_search() -> Duration {
+    let mut list = SkipList::with_seed(20, 0.5, 1).unwrap();
+    for value in permuted_values() {
+        list.insert(value);
+    }
+
+    let start = Instant::now();
+    for value in 0..SIZE {
+        black_box(list.contains(&value));
+    }
+    start.elapsed()
+}
+
+fn bench_iteration() -> Duration {
+    let mut list = SkipList::with_seed(20, 0.5, 1).unwrap();
+    for value in permuted_values() {
+        list.insert(value);
+    }
+
+    let start = Instant::now();
+    for value in list.iter() {
+        black_box(value);
+    }
+    start.elapsed()
+}
+
+fn bench_btreeset_search() -> Duration {
+    let set = permuted_values().into_iter().collect::<BTreeSet<_>>();
+
+    let start = Instant::now();
+    for value in 0..SIZE {
+        black_box(set.contains(&value));
+    }
+    start.elapsed()
+}
+
+fn permuted_values() -> Vec<i32> {
+    (0..SIZE).map(|value| (value * 37) % SIZE).collect()
+}

diagrams/12-skip-list.mmd

@@ -0,0 +1,33 @@
+flowchart TB
+    title["Skip List: niveles probabilisticos"]
+
+    search["buscar 30"]
+
+    subgraph level3["Nivel 3"]
+        h3["head"] --> n30_3["30"] --> end3["nil"]
+    end
+
+    subgraph level2["Nivel 2"]
+        h2["head"] --> n10_2["10"] --> n30_2["30"] --> end2["nil"]
+    end
+
+    subgraph level1["Nivel 1"]
+        h1["head"] --> n10_1["10"] --> n20_1["20"] --> n30_1["30"] --> n40_1["40"] --> end1["nil"]
+    end
+
+    search --> h3
+    h3 --> n30_3
+    h2 --> n10_2
+    n10_2 --> n30_2
+    n10_1 --> n20_1 --> n30_1
+
+    insert["insert<br/>elige altura con moneda sesgada"]
+    remove["remove<br/>actualiza enlaces por nivel"]
+    iterate["iter<br/>recorre nivel 1"]
+    expected["busqueda esperada<br/>O(log n)"]
+
+    level3 --> expected
+    level2 --> expected
+    level1 --> iterate
+    insert --> level1
+    remove --> level2

examples/skip_list_advanced.rs

@@ -0,0 +1,18 @@
+use rust_data_structures::skip_list::SkipList;
+
+fn main() {
+    let mut list = SkipList::with_seed(10, 0.5, 77).unwrap();
+
+    for value in [50, 10, 40, 20, 30] {
+        assert!(list.insert(value));
+    }
+
+    assert!(!list.insert(30));
+    assert_eq!(list.remove(&10), Some(10));
+    assert_eq!(list.remove(&99), None);
+
+    println!(
+        "despues de borrar: {:?}",
+        list.iter().copied().collect::<Vec<_>>()
+    );
+}

examples/skip_list_basic.rs

@@ -0,0 +1,13 @@
+use rust_data_structures::skip_list::SkipList;
+
+fn main() {
+    let mut index = SkipList::new();
+
+    index.insert(30);
+    index.insert(10);
+    index.insert(20);
+
+    println!("contiene 20: {}", index.contains(&20));
+    println!("contiene 40: {}", index.contains(&40));
+    println!("orden: {:?}", index.iter().copied().collect::<Vec<_>>());
+}

examples/skip_list_intermediate.rs

@@ -0,0 +1,13 @@
+use rust_data_structures::skip_list::SkipList;
+
+fn main() {
+    let mut list = SkipList::with_seed(8, 0.5, 2026).unwrap();
+
+    for value in [12, 4, 18, 1, 9, 15, 20, 7] {
+        list.insert(value);
+    }
+
+    println!("len: {}", list.len());
+    println!("nivel actual: {}", list.current_level());
+    println!("histograma de alturas: {:?}", list.level_histogram());
+}

examples/skip_list_real_case.rs

@@ -0,0 +1,26 @@
+use rust_data_structures::skip_list::SkipList;
+
+fn main() {
+    let mut pending_jobs = SkipList::with_seed(12, 0.5, 123).unwrap();
+
+    for scheduled_at in [1_720_000_300, 1_720_000_100, 1_720_000_200] {
+        pending_jobs.insert(scheduled_at);
+    }
+
+    let now = 1_720_000_200;
+    let ready = pending_jobs
+        .iter()
+        .copied()
+        .take_while(|scheduled_at| *scheduled_at <= now)
+        .collect::<Vec<_>>();
+
+    for scheduled_at in ready {
+        pending_jobs.remove(&scheduled_at);
+        println!("ejecutar job programado en {scheduled_at}");
+    }
+
+    println!(
+        "pendientes: {:?}",
+        pending_jobs.iter().copied().collect::<Vec<_>>()
+    );
+}

examples/soluciones/skip_list_expiring_window.rs

@@ -0,0 +1,22 @@
+use rust_data_structures::skip_list::SkipList;
+
+fn main() {
+    let mut timestamps = SkipList::new();
+
+    for timestamp in [10, 40, 20, 50, 30] {
+        timestamps.insert(timestamp);
+    }
+
+    let expired = timestamps
+        .iter()
+        .copied()
+        .take_while(|timestamp| *timestamp <= 30)
+        .collect::<Vec<_>>();
+
+    for timestamp in expired {
+        timestamps.remove(&timestamp);
+    }
+
+    assert_eq!(timestamps.iter().copied().collect::<Vec<_>>(), vec![40, 50]);
+    println!("ventana expirada removida");
+}

examples/soluciones/skip_list_ordered_index.rs

@@ -0,0 +1,17 @@
+use rust_data_structures::skip_list::SkipList;
+
+fn main() {
+    let mut offsets = SkipList::new();
+
+    for offset in [400, 100, 300, 200] {
+        assert!(offsets.insert(offset));
+    }
+
+    assert_eq!(
+        offsets.iter().copied().collect::<Vec<_>>(),
+        vec![100, 200, 300, 400]
+    );
+    assert!(offsets.contains(&300));
+
+    println!("indice ordenado listo");
+}

examples/soluciones/skip_list_trace_levels.rs

@@ -0,0 +1,15 @@
+use rust_data_structures::skip_list::SkipList;
+
+fn main() {
+    let mut list = SkipList::with_seed(8, 0.5, 2026).unwrap();
+
+    for value in 0..16 {
+        list.insert(value);
+    }
+
+    let histogram = list.level_histogram();
+    assert_eq!(histogram.iter().sum::<usize>(), list.len());
+    assert!(list.current_level() <= list.max_level());
+
+    println!("histograma de niveles: {histogram:?}");
+}