circular_doubly_linked_list 0.1.0

//! # Circular Doubly Linked List - Feature Demonstration
//!
//! This demonstration application showcases all features of the
//! `CircularDoublyLinkedList` data structure implementation. It serves as
//! both a functional demo and educational resource for understanding
//! the capabilities and usage patterns of this data structure.
//!
//! ## Overview
//!
//! The Circular Doubly Linked List is a versatile data structure that provides:
//! - O(1) insertion and deletion at both ends
//! - O(1) access to front and back elements
//! - Efficient rotation operations
//! - Full iterator support
//! - Memory-safe API with unsafe internals
//!
//! ## Running the Demo
//!
//! ```bash
//! # Run the demonstration
//! cargo run
//!
//! # Run with release optimizations
//! cargo run --release
//!
//! # Run specific demo section (modify main function)
//! cargo run --features specific_demo
//! ```
//!
//! ## Demo Sections
//!
//! This demo covers the following feature categories:
//! 1. **Basic Operations** - Creation, push, pop, access
//! 2. **Modification Operations** - Insert, remove, clear
//! 3. **Rotation Operations** - Left and right rotation
//! 4. **Iterator Operations** - Forward, backward, mutable, consuming
//! 5. **Trait Implementations** - Clone, Debug, Extend, FromIterator
//! 6. **Advanced Usage** - Custom types, complex workflows
//! 7. **Edge Cases** - Empty list, single element, large lists
//! 8. **Performance Demo** - Large scale operations
//!
//! ## Expected Output
//!
//! The demo will print formatted output showing:
//! - Operation results
//! - List states after modifications
//! - Iterator behavior
//! - Performance metrics
//!
//! ## Safety Notes
//!
//! While this demo uses the safe public API, the underlying implementation
//! uses unsafe code for pointer manipulation. All unsafe operations are
//! encapsulated within safe abstractions.
//!
//! ## License
//!
//! This demo is part of the circular_doubly_linked_list crate and follows
//! the same licensing terms (MIT OR Apache-2.0).

use circular_doubly_linked_list::CircularDoublyLinkedList;

// ============================================================================
// Helper Functions
// ============================================================================

/// Prints a section header for demo output.
///
/// # Parameters
///
/// * `title` - The title of the demo section
///
/// # Examples
///
/// ```ignore
/// print_section_header("Basic Operations");
/// ```
fn print_section_header(title: &str) {
    println!("\n{}", "=".repeat(80));
    println!("  {}", title);
    println!("{}\n", "=".repeat(80));
}

/// Prints a subsection header for demo output.
///
/// # Parameters
///
/// * `subtitle` - The subtitle of the demo subsection
fn print_subsection(subtitle: &str) {
    println!("\n--- {} ---", subtitle);
}

/// Prints a demo step with description.
///
/// # Parameters
///
/// * `step` - The step number or identifier
/// * `description` - Description of what this step demonstrates
fn print_step(step: &str, description: impl AsRef<str>) {
    println!("  [{}] {}", step, description.as_ref());
}

// ============================================================================
// Demo: Basic Operations
// ============================================================================

/// Demonstrates basic list creation and initialization operations.
///
/// # Purpose
///
/// Shows the different ways to create a CircularDoublyLinkedList and
/// verifies initial state properties.
///
/// # Features Demonstrated
///
/// - `CircularDoublyLinkedList::new()`
/// - `CircularDoublyLinkedList::default()`
/// - `is_empty()`
/// - `len()`
fn demo_basic_creation() {
    print_section_header("DEMO 1: Basic List Creation");

    print_step("1", "Creating list with new()");
    let list1: CircularDoublyLinkedList<i32> = CircularDoublyLinkedList::new();
    println!(
        "      New list - Empty: {}, Length: {}",
        list1.is_empty(),
        list1.len()
    );

    print_step("2", "Creating list with default()");
    let list2: CircularDoublyLinkedList<i32> = CircularDoublyLinkedList::default();
    println!(
        "      Default list - Empty: {}, Length: {}",
        list2.is_empty(),
        list2.len()
    );

    print_step("3", "Verifying all creation methods produce empty lists");
    assert!(list1.is_empty() && list2.is_empty());
    println!("      ✓ All creation methods produce empty lists");
}

/// Demonstrates push operations (front and back).
///
/// # Purpose
///
/// Shows how to add elements to both ends of the list and verifies
/// the ordering behavior.
///
/// # Features Demonstrated
///
/// - `push_front()`
/// - `push_back()`
/// - `front()`
/// - `back()`
/// - `len()`
fn demo_push_operations() {
    print_section_header("DEMO 2: Push Operations");

    let mut list = CircularDoublyLinkedList::new();

    print_subsection("Push Back (FIFO Order)");
    print_step("1", "Push back: 1, 2, 3");
    list.push_back(1);
    list.push_back(2);
    list.push_back(3);
    println!(
        "      Front: {:?}, Back: {:?}, Length: {}",
        list.front(),
        list.back(),
        list.len()
    );
    println!("      List: {:?}", list);

    print_subsection("Push Front (LIFO Order)");
    print_step("2", "Push front: 0, -1");
    list.push_front(0);
    list.push_front(-1);
    println!(
        "      Front: {:?}, Back: {:?}, Length: {}",
        list.front(),
        list.back(),
        list.len()
    );
    println!("      List: {:?}", list);

    print_subsection("Mixed Push Operations");
    print_step("3", "Demonstrating mixed push_front and push_back");
    let mut mixed = CircularDoublyLinkedList::new();
    mixed.push_back(2);
    mixed.push_front(1);
    mixed.push_back(3);
    mixed.push_front(0);
    println!("      Sequence: push_back(2), push_front(1), push_back(3), push_front(0)");
    println!("      Result: {:?}", mixed);
    println!("      ✓ Order preserved correctly");
}

/// Demonstrates pop operations (front and back).
///
/// # Purpose
///
/// Shows how to remove elements from both ends and handles edge cases
/// like popping from empty lists.
///
/// # Features Demonstrated
///
/// - `pop_front()`
/// - `pop_back()`
/// - Empty list handling
/// - Return type (Option<T>)
fn demo_pop_operations() {
    print_section_header("DEMO 3: Pop Operations");

    let mut list = CircularDoublyLinkedList::new();
    list.push_back(10);
    list.push_back(20);
    list.push_back(30);
    list.push_back(40);

    print_step("1", "Initial list state");
    println!("      List: {:?}", list);

    print_subsection("Pop Front");
    print_step("2", "Pop front elements one by one");
    while let Some(value) = list.pop_front() {
        println!("      Popped from front: {}", value);
    }
    println!(
        "      List after pop_front: {:?}, Empty: {}",
        list,
        list.is_empty()
    );

    // Rebuild for pop_back demo
    list.push_back(100);
    list.push_back(200);
    list.push_back(300);

    print_subsection("Pop Back");
    print_step("3", "Pop back elements one by one");
    while let Some(value) = list.pop_back() {
        println!("      Popped from back: {}", value);
    }
    println!(
        "      List after pop_back: {:?}, Empty: {}",
        list,
        list.is_empty()
    );

    print_subsection("Empty List Pop");
    print_step("4", "Attempting to pop from empty list");
    let result = list.pop_front();
    println!("      Pop from empty list returns: {:?}", result);
    println!("      ✓ Safe handling of empty list");
}

// ============================================================================
// Demo: Access Operations
// ============================================================================

/// Demonstrates element access operations (immutable and mutable).
///
/// # Purpose
///
/// Shows how to access elements at both ends with both immutable and
/// mutable references.
///
/// # Features Demonstrated
///
/// - `front()`
/// - `back()`
/// - `front_mut()`
/// - `back_mut()`
/// - In-place modification
fn demo_access_operations() {
    print_section_header("DEMO 4: Access Operations");

    let mut list = CircularDoublyLinkedList::new();
    list.push_back(100);
    list.push_back(200);
    list.push_back(300);

    print_step("1", "Initial list state");
    println!("      List: {:?}", list);

    print_subsection("Immutable Access");
    print_step("2", "Access front and back immutably");
    if let Some(front) = list.front() {
        println!("      Front element: {}", front);
    }
    if let Some(back) = list.back() {
        println!("      Back element: {}", back);
    }

    print_subsection("Mutable Access");
    print_step("3", "Modify front and back elements in-place");
    if let Some(front) = list.front_mut() {
        let old_value = *front;
        *front = 999;
        println!("      Modified front: {} → {}", old_value, *front);
    }
    if let Some(back) = list.back_mut() {
        let old_value = *back;
        *back = 888;
        println!("      Modified back: {} → {}", old_value, *back);
    }

    print_step("4", "Verify modifications");
    println!("      List after modification: {:?}", list);
    println!("      ✓ In-place modification successful");
}

// ============================================================================
// Demo: Modification Operations
// ============================================================================

/// Demonstrates insert and remove operations at specific positions.
///
/// # Purpose
///
/// Shows how to insert and remove elements at arbitrary positions
/// within the list.
///
/// # Features Demonstrated
///
/// - `insert_after()`
/// - `remove_at()`
/// - Position validation
/// - Return types
fn demo_modification_operations() {
    print_section_header("DEMO 5: Modification Operations");

    let mut list = CircularDoublyLinkedList::new();
    list.push_back(1);
    list.push_back(2);
    list.push_back(4);
    list.push_back(5);

    print_step("1", "Initial list (missing 3)");
    println!("      List: {:?}", list);

    print_subsection("Insert After");
    print_step("2", "Insert 3 after position 1 (between 2 and 4)");
    let success = list.insert_after(1, 3);
    println!("      Insert successful: {}", success);
    println!("      List after insert: {:?}", list);

    print_subsection("Remove At");
    print_step("3", "Remove element at position 2 (value 3)");
    let removed = list.remove_at(2);
    println!("      Removed value: {:?}", removed);
    println!("      List after remove: {:?}", list);

    print_subsection("Invalid Position Handling");
    print_step("4", "Attempt insert/remove at invalid positions");
    let insert_fail = list.insert_after(100, 999);
    let remove_fail = list.remove_at(100);
    println!("      Insert at invalid position: {}", insert_fail);
    println!("      Remove at invalid position: {:?}", remove_fail);
    println!("      ✓ Invalid positions handled safely");
}

/// Demonstrates clear operation.
///
/// # Purpose
///
/// Shows how to remove all elements from the list.
///
/// # Features Demonstrated
///
/// - `clear()`
/// - Post-clear state
fn demo_clear_operation() {
    print_section_header("DEMO 6: Clear Operation");

    let mut list = CircularDoublyLinkedList::new();
    for i in 0..10 {
        list.push_back(i);
    }

    print_step("1", "List before clear");
    println!("      List: {:?}", list);
    println!("      Length: {}", list.len());

    print_step("2", "Clearing all elements");
    list.clear();

    print_step("3", "List after clear");
    println!("      List: {:?}", list);
    println!("      Length: {}, Empty: {}", list.len(), list.is_empty());
    println!("      ✓ Clear operation successful");
}

// ============================================================================
// Demo: Rotation Operations
// ============================================================================

/// Demonstrates rotation operations (left and right).
///
/// # Purpose
///
/// Shows how to rotate the list efficiently without moving data.
///
/// # Features Demonstrated
///
/// - `rotate_left()`
/// - `rotate_right()`
/// - O(1) rotation
/// - Multiple rotations
fn demo_rotation_operations() {
    print_section_header("DEMO 7: Rotation Operations");

    let mut list = CircularDoublyLinkedList::new();
    for i in 1..=5 {
        list.push_back(i);
    }

    print_step("1", "Initial list");
    println!("      List: {:?}", list);

    print_subsection("Rotate Left");
    print_step("2", "Rotate left by 1 position");
    list.rotate_left();
    println!("      After 1 left rotation: {:?}", list);

    print_step("3", "Rotate left by 2 more positions");
    list.rotate_left();
    list.rotate_left();
    println!("      After 3 total left rotations: {:?}", list);

    print_subsection("Rotate Right");
    print_step("4", "Rotate right to restore original order");
    list.rotate_right();
    list.rotate_right();
    list.rotate_right();
    println!("      After 3 right rotations: {:?}", list);

    print_subsection("Full Cycle");
    print_step("5", "Rotate left 5 times (full cycle)");
    for _ in 0..5 {
        list.rotate_left();
    }
    println!("      After 5 left rotations (full cycle): {:?}", list);
    println!("      ✓ Rotation operations maintain list integrity");
}

// ============================================================================
// Demo: Iterator Operations
// ============================================================================

/// Demonstrates immutable iteration.
///
/// # Purpose
///
/// Shows various ways to iterate over the list immutably.
///
/// # Features Demonstrated
///
/// - `iter()`
/// - Forward iteration
/// - Backward iteration (`.rev()`)
/// - Iterator adapters
fn demo_iter_operations() {
    print_section_header("DEMO 8: Iterator Operations (Immutable)");

    let mut list = CircularDoublyLinkedList::new();
    for i in 1..=6 {
        list.push_back(i);
    }

    print_step("1", "Initial list");
    println!("      List: {:?}", list);

    print_subsection("Forward Iteration");
    print_step("2", "Iterate from front to back");
    print!("      ");
    for item in list.iter() {
        print!("{} ", item);
    }
    println!();

    print_subsection("Backward Iteration");
    print_step("3", "Iterate from back to front using .rev()");
    print!("      ");
    for item in list.iter().rev() {
        print!("{} ", item);
    }
    println!();

    print_subsection("Iterator Adapters");
    print_step("4", "Filter even numbers and square them");
    let squared_evens: Vec<i32> = list
        .iter()
        .filter(|&&x| x % 2 == 0)
        .map(|&x| x * x)
        .collect();
    println!("      Squared evens: {:?}", squared_evens);

    print_step("5", "Sum all elements");
    let sum: i32 = list.iter().sum();
    println!("      Sum of all elements: {}", sum);

    print_step("6", "Find first element greater than 4");
    if let Some(&found) = list.iter().find(|&&x| x > 4) {
        println!("      Found: {}", found);
    }

    println!("      ✓ Iterator operations work correctly");
}

/// Demonstrates mutable iteration.
///
/// # Purpose
///
/// Shows how to modify elements during iteration.
///
/// # Features Demonstrated
///
/// - `iter_mut()`
/// - In-place modification
/// - Mutable iterator adapters
fn demo_iter_mut_operations() {
    print_section_header("DEMO 9: Iterator Operations (Mutable)");

    let mut list = CircularDoublyLinkedList::new();
    for i in 1..=5 {
        list.push_back(i);
    }

    print_step("1", "Initial list");
    println!("      List: {:?}", list);

    print_subsection("Mutable Modification");
    print_step("2", "Multiply all elements by 2");
    for item in list.iter_mut() {
        *item *= 2;
    }
    println!("      After multiplication: {:?}", list);

    print_step("3", "Add index-based offset using enumerate");
    for (i, item) in list.iter_mut().enumerate() {
        *item += i as i32;
    }
    println!("      After index offset: {:?}", list);

    println!("      ✓ Mutable iteration successful");
}

/// Demonstrates consuming iteration.
///
/// # Purpose
///
/// Shows how to consume the list and take ownership of elements.
///
/// # Features Demonstrated
///
/// - `into_iter()`
/// - Ownership transfer
/// - List consumption
fn demo_into_iter_operations() {
    print_section_header("DEMO 10: Iterator Operations (Consuming)");

    let mut list = CircularDoublyLinkedList::new();
    list.push_back(String::from("Hello"));
    list.push_back(String::from("World"));
    list.push_back(String::from("from"));
    list.push_back(String::from("Rust"));

    print_step("1", "List before consumption");
    println!("      List: {:?}", list);

    print_subsection("Consume and Collect");
    print_step("2", "Consume list and collect into Vec");
    let vec: Vec<String> = list.into_iter().collect();
    println!("      Collected Vec: {:?}", vec);
    println!("      List consumed (cannot be used after into_iter)");

    print_subsection("Consume with For Loop");
    let mut list2 = CircularDoublyLinkedList::new();
    list2.push_back(10);
    list2.push_back(20);
    list2.push_back(30);

    print_step("3", "Consume with for loop and accumulate sum");
    let mut sum = 0;
    for value in list2.into_iter() {
        sum += value;
    }
    println!("      Sum of consumed values: {}", sum);

    println!("      ✓ Consuming iteration successful");
}

// ============================================================================
// Demo: Trait Implementations
// ============================================================================

/// Demonstrates Clone trait.
///
/// # Purpose
///
/// Shows how to create independent copies of the list.
///
/// # Features Demonstrated
///
/// - `clone()`
/// - Deep copy behavior
/// - Independence of clones
fn demo_clone_trait() {
    print_section_header("DEMO 11: Clone Trait");

    let mut original = CircularDoublyLinkedList::new();
    original.push_back(1);
    original.push_back(2);
    original.push_back(3);

    print_step("1", "Original list");
    println!("      Original: {:?}", original);

    print_step("2", "Create clone");
    let cloned = original.clone();
    println!("      Cloned: {:?}", cloned);

    print_step("3", "Modify clone independently");
    let mut cloned_mut = cloned.clone();
    cloned_mut.push_back(4);
    println!("      Modified clone: {:?}", cloned_mut);
    println!("      Original unchanged: {:?}", original);
    println!("      ✓ Clone creates independent copy");
}

/// Demonstrates Debug trait.
///
/// # Purpose
///
/// Shows debug formatting output.
///
/// # Features Demonstrated
///
/// - `Debug` implementation
/// - Format output
fn demo_debug_trait() {
    print_section_header("DEMO 12: Debug Trait");

    let mut list = CircularDoublyLinkedList::new();
    list.push_back(10);
    list.push_back(20);
    list.push_back(30);

    print_step("1", "Debug format output");
    println!("      {:?}", list);

    print_step("2", "Empty list debug format");
    let empty: CircularDoublyLinkedList<i32> = CircularDoublyLinkedList::new();
    println!("      {:?}", empty);
    println!("      ✓ Debug formatting works correctly");
}

/// Demonstrates Extend and FromIterator traits.
///
/// # Purpose
///
/// Shows how to use standard iterator traits with the list.
///
/// # Features Demonstrated
///
/// - `extend()`
/// - `from_iter()` / `collect()`
/// - Standard trait compatibility
fn demo_extend_from_iterator() {
    print_section_header("DEMO 13: Extend and FromIterator Traits");

    print_subsection("Extend");
    let mut list = CircularDoublyLinkedList::new();
    print_step("1", "Extend with vec![1, 2, 3]");
    list.extend(vec![1, 2, 3]);
    println!("      List after extend: {:?}", list);

    print_subsection("FromIterator (collect)");
    print_step("2", "Create list from iterator using collect()");
    let collected: CircularDoublyLinkedList<i32> = (0..5).collect();
    println!("      Collected from range: {:?}", collected);

    print_step("3", "Chain multiple operations");
    let chained: CircularDoublyLinkedList<i32> =
        vec![1, 2, 3].into_iter().map(|x| x * 10).collect();
    println!("      Chained operations: {:?}", chained);
    println!("      ✓ Trait implementations work correctly");
}

// ============================================================================
// Demo: Advanced Usage
// ============================================================================

/// Demonstrates usage with custom types.
///
/// # Purpose
///
/// Shows that the list works with any type T, including custom structs.
///
/// # Features Demonstrated
///
/// - Generic type parameter
/// - Custom struct storage
/// - Clone requirement for some operations
fn demo_custom_types() {
    print_section_header("DEMO 14: Custom Types");

    #[derive(Debug, Clone, PartialEq)]
    struct Person {
        name: String,
        age: u32,
    }

    let mut list = CircularDoublyLinkedList::new();

    print_step("1", "Create list of custom Person struct");
    list.push_back(Person {
        name: String::from("Alice"),
        age: 30,
    });
    list.push_back(Person {
        name: String::from("Bob"),
        age: 25,
    });
    list.push_back(Person {
        name: String::from("Charlie"),
        age: 35,
    });

    print_step("2", "Display all persons");
    for person in list.iter() {
        println!("      {} (age: {})", person.name, person.age);
    }

    print_step("3", "Access and modify");
    if let Some(first) = list.front_mut() {
        first.age += 1;
        println!("      Updated first person's age: {}", first.age);
    }

    println!("      ✓ Custom types work correctly");
}

/// Demonstrates usage with various standard types.
///
/// # Purpose
///
/// Shows compatibility with common Rust types.
///
/// # Features Demonstrated
///
/// - String
/// - Vec
/// - Option
/// - Result
/// - Tuple
fn demo_standard_types() {
    print_section_header("DEMO 15: Standard Types");

    print_subsection("String");
    let mut string_list = CircularDoublyLinkedList::new();
    string_list.push_back(String::from("Hello"));
    string_list.push_back(String::from("World"));
    println!("      String list: {:?}", string_list);

    print_subsection("Vec");
    let mut vec_list = CircularDoublyLinkedList::new();
    vec_list.push_back(vec![1, 2, 3]);
    vec_list.push_back(vec![4, 5, 6]);
    println!("      Vec list: {:?}", vec_list);

    print_subsection("Option");
    let mut option_list = CircularDoublyLinkedList::new();
    option_list.push_back(Some(42));
    option_list.push_back(None);
    option_list.push_back(Some(100));
    println!("      Option list: {:?}", option_list);

    print_subsection("Tuple");
    let mut tuple_list = CircularDoublyLinkedList::new();
    tuple_list.push_back((1, "a"));
    tuple_list.push_back((2, "b"));
    println!("      Tuple list: {:?}", tuple_list);

    println!("      ✓ All standard types work correctly");
}

// ============================================================================
// Demo: Edge Cases
// ============================================================================

/// Demonstrates edge case handling.
///
/// # Purpose
///
/// Shows how the list handles boundary conditions safely.
///
/// # Features Demonstrated
///
/// - Empty list operations
/// - Single element operations
/// - Large list handling
fn demo_edge_cases() {
    print_section_header("DEMO 16: Edge Cases");

    print_subsection("Empty List");
    let mut empty: CircularDoublyLinkedList<i32> = CircularDoublyLinkedList::new();
    print_step("1", "Operations on empty list");
    println!("      front(): {:?}", empty.front());
    println!("      back(): {:?}", empty.back());
    println!("      pop_front(): {:?}", empty.pop_front());
    println!("      pop_back(): {:?}", empty.pop_back());
    println!("      remove_at(0): {:?}", empty.remove_at(0));
    println!("      insert_after(0, 1): {}", empty.insert_after(0, 1));
    empty.rotate_left();
    empty.rotate_right();
    println!("      ✓ All empty list operations handled safely");

    print_subsection("Single Element");
    let mut single = CircularDoublyLinkedList::new();
    single.push_back(42);
    print_step("2", "Operations on single element list");
    println!(
        "      front() == back(): {}",
        single.front() == single.back()
    );
    single.rotate_left();
    println!("      After rotate_left: {:?}", single);
    single.pop_front();
    println!("      After pop: empty = {}", single.is_empty());
    println!("      ✓ Single element operations handled correctly");

    print_subsection("Large List");
    let mut large = CircularDoublyLinkedList::new();
    print_step("3", "Create and iterate large list (10,000 elements)");
    for i in 0..10_000 {
        large.push_back(i);
    }
    println!("      Created list with {} elements", large.len());
    let sum: i64 = large.iter().map(|&x| x as i64).sum();
    println!("      Sum of all elements: {}", sum);
    println!("      ✓ Large list handled efficiently");
}

// ============================================================================
// Demo: Use Case Patterns
// ============================================================================

/// Demonstrates queue usage pattern (FIFO).
///
/// # Purpose
///
/// Shows how to use the list as a queue data structure.
fn demo_queue_pattern() {
    print_section_header("DEMO 17: Queue Pattern (FIFO)");

    let mut queue = CircularDoublyLinkedList::new();

    print_step("1", "Enqueue operations (push_back)");
    queue.push_back("Task 1");
    queue.push_back("Task 2");
    queue.push_back("Task 3");
    println!("      Queue: {:?}", queue);

    print_step("2", "Dequeue operations (pop_front)");
    while let Some(task) = queue.pop_front() {
        println!("      Processing: {}", task);
    }
    println!("      ✓ Queue pattern works correctly");
}

/// Demonstrates stack usage pattern (LIFO).
///
/// # Purpose
///
/// Shows how to use the list as a stack data structure.
fn demo_stack_pattern() {
    print_section_header("DEMO 18: Stack Pattern (LIFO)");

    let mut stack = CircularDoublyLinkedList::new();

    print_step("1", "Push operations (push_front)");
    stack.push_front("Page 1");
    stack.push_front("Page 2");
    stack.push_front("Page 3");
    println!("      Stack: {:?}", stack);

    print_step("2", "Pop operations (pop_front)");
    while let Some(page) = stack.pop_front() {
        println!("      Popped: {}", page);
    }
    println!("      ✓ Stack pattern works correctly");
}

/// Demonstrates deque usage pattern (double-ended).
///
/// # Purpose
///
/// Shows how to use the list as a double-ended queue.
fn demo_deque_pattern() {
    print_section_header("DEMO 19: Deque Pattern (Double-Ended)");

    let mut deque = CircularDoublyLinkedList::new();

    print_step("1", "Add from both ends");
    deque.push_back(1);
    deque.push_front(0);
    deque.push_back(2);
    deque.push_front(-1);
    println!("      Deque: {:?}", deque);

    print_step("2", "Remove from both ends");
    println!("      Pop front: {:?}", deque.pop_front());
    println!("      Pop back: {:?}", deque.pop_back());
    println!("      Remaining: {:?}", deque);
    println!("      ✓ Deque pattern works correctly");
}

/// Demonstrates circular buffer usage pattern.
///
/// # Purpose
///
/// Shows how rotation enables circular buffer behavior.
fn demo_circular_buffer_pattern() {
    print_section_header("DEMO 20: Circular Buffer Pattern");

    let mut buffer = CircularDoublyLinkedList::new();
    for i in 0..5 {
        buffer.push_back(i);
    }

    print_step("1", "Initial buffer");
    println!("      Buffer: {:?}", buffer);

    print_step("2", "Simulate circular read head movement");
    for rotation in 1..=5 {
        buffer.rotate_left();
        println!("      After rotation {}: {:?}", rotation, buffer);
    }

    print_step("3", "Buffer returns to original position after N rotations");
    println!("      ✓ Circular buffer pattern works correctly");
}

// ============================================================================
// Demo: Performance Comparison
// ============================================================================

/// Demonstrates performance characteristics.
///
/// # Purpose
///
/// Shows the O(1) performance of key operations.
///
/// # Note
///
/// This is a demonstration, not a benchmark. For accurate benchmarks,
/// use cargo bench with proper benchmark harness.
fn demo_performance() {
    print_section_header("DEMO 21: Performance Characteristics");

    const SIZE: usize = 100_000;

    print_subsection("Push Front Performance");
    print_step("1", format!("Push {} elements to front", SIZE));
    let mut list = CircularDoublyLinkedList::new();
    let start = std::time::Instant::now();
    for i in 0..SIZE {
        list.push_front(i);
    }
    let duration = start.elapsed();
    println!("      Time: {:?}", duration);
    println!("      Elements: {}", list.len());

    print_subsection("Push Back Performance");
    print_step("2", format!("Push {} elements to back", SIZE));
    let mut list = CircularDoublyLinkedList::new();
    let start = std::time::Instant::now();
    for i in 0..SIZE {
        list.push_back(i);
    }
    let duration = start.elapsed();
    println!("      Time: {:?}", duration);
    println!("      Elements: {}", list.len());

    print_subsection("Front/Back Access Performance");
    print_step("3", format!("Access front/back {} times", SIZE));
    let start = std::time::Instant::now();
    for _ in 0..SIZE {
        let _ = list.front();
        let _ = list.back();
    }
    let duration = start.elapsed();
    println!("      Time: {:?}", duration);

    print_subsection("Rotation Performance");
    print_step("4", format!("Rotate {} times", SIZE));
    let start = std::time::Instant::now();
    for _ in 0..SIZE {
        list.rotate_left();
    }
    let duration = start.elapsed();
    println!("      Time: {:?}", duration);
    println!("      ✓ O(1) operations demonstrated");
}

// ============================================================================
// Main Function
// ============================================================================

/// Main entry point for the demonstration application.
///
/// # Purpose
///
/// Runs all demo sections sequentially to showcase the full capabilities
/// of the CircularDoublyLinkedList data structure.
///
/// # Execution Flow
///
/// 1. Print welcome message
/// 2. Run all demo functions in order
/// 3. Print completion message
///
/// # Returns
///
/// Returns `()` on successful completion.
///
/// # Examples
///
/// ```bash
/// cargo run
/// ```
fn main() {
    println!("{}", "★".repeat(80));
    println!("  CIRCULAR DOUBLY LINKED LIST - FEATURE DEMONSTRATION");
    println!("  Rust Data Structure Implementation");
    println!("{}", "★".repeat(80));

    // Basic Operations
    demo_basic_creation();
    demo_push_operations();
    demo_pop_operations();
    demo_access_operations();

    // Modification Operations
    demo_modification_operations();
    demo_clear_operation();

    // Rotation Operations
    demo_rotation_operations();

    // Iterator Operations
    demo_iter_operations();
    demo_iter_mut_operations();
    demo_into_iter_operations();

    // Trait Implementations
    demo_clone_trait();
    demo_debug_trait();
    demo_extend_from_iterator();

    // Advanced Usage
    demo_custom_types();
    demo_standard_types();

    // Edge Cases
    demo_edge_cases();

    // Use Case Patterns
    demo_queue_pattern();
    demo_stack_pattern();
    demo_deque_pattern();
    demo_circular_buffer_pattern();

    // Performance
    demo_performance();

    // Completion
    println!("\n{}", "★".repeat(80));
    println!("  DEMONSTRATION COMPLETE");
    println!("  All features showcased successfully!");
    println!("{}", "★".repeat(80));
    println!("\n💡 For more information, see the crate documentation:");
    println!("   cargo doc --open\n");
}