circular_doubly_linked_list 0.1.0

//! Node module containing the core node structure for the circular doubly linked list.
//!
//! This module provides the foundational `Node` struct that stores data and
//! raw pointers to adjacent nodes. All operations on nodes are unsafe and
//! should only be accessed through the safe API in the `list` module.

use core::ptr::NonNull;
use std::boxed::Box;

/// A node in the circular doubly linked list.
///
/// Each node contains three fields:
/// - `data`: The actual value stored in the node (owned by the node)
/// - `next`: Raw pointer to the next node in the circular sequence
/// - `prev`: Raw pointer to the previous node in the circular sequence
///
/// # Type Parameters
///
/// * `T` - The type of data stored in the node. Can be any type.
///
/// # Memory Layout
///
/// ```text
/// +------+------+------+------+
/// | next | prev | data | ...  |
/// +------+------+------+------+
/// ```
///
/// # Safety
///
/// This struct uses raw pointers and should only be manipulated through
/// safe APIs provided by `CircularDoublyLinkedList`. Direct manipulation
/// can lead to undefined behavior including:
/// - Use-after-free
/// - Double-free
/// - Memory leaks
/// - Data corruption
///
/// # Examples
///
/// ```ignore
/// // This is internal implementation detail
/// // Users should not interact with Node directly
/// use circular_doubly_linked_list::node::Node;
///
/// let node_ptr = Node::new(42);
/// // node_ptr is a NonNull<Node<i32>>
/// // Remember to deallocate when done
/// unsafe {
///     let _value = Node::dealloc(node_ptr);
/// }
/// ```
///
/// # Invariants
///
/// For a properly integrated node in a list:
/// - `next` points to the successor node (or self for single-element list)
/// - `prev` points to the predecessor node (or self for single-element list)
/// - For a list with head H and tail T: `H.prev == T` and `T.next == H`
pub(crate) struct Node<T> {
    /// Pointer to the next node in the circular sequence.
    ///
    /// # Invariants
    ///
    /// - Must always point to a valid `Node<T>` when the node is in a list
    /// - For a standalone node, points to self
    /// - Never null (uses `NonNull` for safety)
    pub(crate) next: NonNull<Node<T>>,

    /// Pointer to the previous node in the circular sequence.
    ///
    /// # Invariants
    ///
    /// - Must always point to a valid `Node<T>` when the node is in a list
    /// - For a standalone node, points to self
    /// - Never null (uses `NonNull` for safety)
    pub(crate) prev: NonNull<Node<T>>,

    /// The data stored in this node.
    ///
    /// This field owns the data and will be returned when the node is
    /// deallocated via `dealloc()`.
    pub(crate) data: T,
}

impl<T> Node<T> {
    /// Creates a new node with the given data.
    ///
    /// Allocates a new node on the heap and initializes it with self-referential
    /// pointers (both `next` and `prev` point to the node itself). This is the
    /// correct initial state for a node that will become the only element in a
    /// new list.
    ///
    /// # Parameters
    ///
    /// * `data` - The value to store in the node. This value is moved into the node.
    ///
    /// # Returns
    ///
    /// Returns a `NonNull<Node<T>>` pointer to the newly created and allocated node.
    /// The pointer is guaranteed to be non-null and properly aligned.
    ///
    /// # Safety
    ///
    /// The returned pointer must be properly deallocated when no longer needed
    /// using `dealloc()`. Failure to do so will result in a memory leak.
    ///
    /// The `next` and `prev` pointers are initially self-referential and must be
    /// updated before the node is integrated into a multi-node list.
    ///
    /// # Panics
    ///
    /// Panics if memory allocation fails (though this is extremely rare in practice).
    ///
    /// # Examples
    ///
    /// ```ignore
    /// use circular_doubly_linked_list::node::Node;
    ///
    /// let node_ptr = Node::new(42);
    ///
    /// unsafe {
    ///     // Verify self-referential pointers
    ///     assert_eq!(Node::get_next(node_ptr).as_ptr(), node_ptr.as_ptr());
    ///     assert_eq!(Node::get_prev(node_ptr).as_ptr(), node_ptr.as_ptr());
    ///     
    ///     // Access the data
    ///     assert_eq!(*Node::data_ref(node_ptr), 42);
    ///     
    ///     // Clean up
    ///     let value = Node::dealloc(node_ptr);
    ///     assert_eq!(value, 42);
    /// }
    /// ```
    pub(crate) fn new(data: T) -> NonNull<Self> {
        let boxed = Box::new(Self {
            data,
            next: NonNull::dangling(),
            prev: NonNull::dangling(),
        });

        let ptr =
            NonNull::new(Box::into_raw(boxed)).expect("Box::into_raw should never return null");

        unsafe {
            (*ptr.as_ptr()).next = ptr;
            (*ptr.as_ptr()).prev = ptr;
        }

        ptr
    }

    /// Creates a new node with data and explicit next/prev pointers.
    ///
    /// This is a lower-level constructor that allows setting the neighbor pointers
    /// directly. Use with caution as incorrect pointers can corrupt the list.
    ///
    /// # Parameters
    ///
    /// * `data` - The value to store in the node
    /// * `next` - Pointer to the next node in the sequence
    /// * `prev` - Pointer to the previous node in the sequence
    ///
    /// # Returns
    ///
    /// Returns a `NonNull<Node<T>>` pointer to the newly created node.
    ///
    /// # Safety
    ///
    /// The caller must ensure that:
    /// - `next` and `prev` pointers are valid and point to allocated `Node<T>` instances
    /// - The pointers form a valid circular chain
    /// - No aliasing violations occur (no multiple mutable references)
    ///
    /// Incorrect use can lead to undefined behavior including memory corruption.
    ///
    /// # Examples
    ///
    /// ```ignore
    /// use circular_doubly_linked_list::node::Node;
    ///
    /// unsafe {
    ///     let node1 = Node::new(1);
    ///     let node2 = Node::new(2);
    ///     
    ///     // Create a new node linking node1 and node2
    ///     let new_node = Node::with_pointers(3, node2, node1);
    ///     
    ///     // Remember to clean up all nodes
    ///     Node::dealloc(node1);
    ///     Node::dealloc(node2);
    ///     Node::dealloc(new_node);
    /// }
    /// ```
    #[allow(dead_code)]
    pub(crate) fn with_pointers(
        data: T,
        next: NonNull<Self>,
        prev: NonNull<Self>,
    ) -> NonNull<Self> {
        let boxed = Box::new(Self { data, next, prev });
        NonNull::new(Box::into_raw(boxed)).expect("Box::into_raw should never return null")
    }

    /// Returns a mutable reference to the data stored in the node.
    ///
    /// # Parameters
    ///
    /// * `ptr` - NonNull pointer to the node containing the data
    ///
    /// # Returns
    ///
    /// Returns a mutable reference `&mut T` to the data stored in the node.
    ///
    /// # Safety
    ///
    /// The caller must ensure that:
    /// - `ptr` is valid and points to an allocated `Node<T>`
    /// - The node is not currently borrowed immutably elsewhere
    /// - No other mutable reference to this data exists simultaneously
    /// - The node will not be deallocated while the reference is in use
    ///
    /// # Examples
    ///
    /// ```ignore
    /// use circular_doubly_linked_list::node::Node;
    ///
    /// let node_ptr = Node::new(42);
    ///
    /// unsafe {
    ///     let data_mut = Node::data_mut(node_ptr);
    ///     *data_mut = 100;
    ///     
    ///     assert_eq!(*Node::data_ref(node_ptr), 100);
    ///     
    ///     Node::dealloc(node_ptr);
    /// }
    /// ```
    pub(crate) unsafe fn data_mut<'a>(ptr: NonNull<Self>) -> &'a mut T {
        unsafe { &mut (*ptr.as_ptr()).data }
    }

    /// Returns an immutable reference to the data stored in the node.
    ///
    /// # Parameters
    ///
    /// * `ptr` - NonNull pointer to the node containing the data
    ///
    /// # Returns
    ///
    /// Returns an immutable reference `&T` to the data stored in the node.
    ///
    /// # Safety
    ///
    /// The caller must ensure that:
    /// - `ptr` is valid and points to an allocated `Node<T>`
    /// - The node will not be deallocated while the reference is in use
    ///
    /// # Examples
    ///
    /// ```ignore
    /// use circular_doubly_linked_list::node::Node;
    ///
    /// let node_ptr = Node::new(42);
    ///
    /// unsafe {
    ///     let data_ref = Node::data_ref(node_ptr);
    ///     assert_eq!(*data_ref, 42);
    ///     
    ///     Node::dealloc(node_ptr);
    /// }
    /// ```
    pub(crate) unsafe fn data_ref<'a>(ptr: NonNull<Self>) -> &'a T {
        unsafe { &(*ptr.as_ptr()).data }
    }

    /// Deallocates the node and returns the contained data.
    ///
    /// This function reconstructs a `Box` from the raw pointer and extracts
    /// the data, properly freeing the node's memory allocation.
    ///
    /// # Parameters
    ///
    /// * `ptr` - NonNull pointer to the node to deallocate
    ///
    /// # Returns
    ///
    /// Returns the data `T` that was contained in the node.
    ///
    /// # Safety
    ///
    /// The caller must ensure that:
    /// - `ptr` is valid and points to an allocated `Node<T>`
    /// - `ptr` has not been previously deallocated (no double-free)
    /// - The node has been properly unlinked from the list before deallocation
    /// - No references to this node's data exist after this call
    ///
    /// # Examples
    ///
    /// ```ignore
    /// use circular_doubly_linked_list::node::Node;
    ///
    /// let node_ptr = Node::new(42);
    ///
    /// unsafe {
    ///     let value = Node::dealloc(node_ptr);
    ///     assert_eq!(value, 42);
    ///     // node_ptr must not be used after this point
    /// }
    /// ```
    pub(crate) unsafe fn dealloc(ptr: NonNull<Self>) -> T {
        unsafe {
            let boxed = Box::from_raw(ptr.as_ptr());
            boxed.data
        }
    }

    /// Updates the next pointer of the node.
    ///
    /// # Parameters
    ///
    /// * `ptr` - NonNull pointer to the node whose next pointer will be updated
    /// * `next` - New next pointer (must point to a valid `Node<T>`)
    ///
    /// # Safety
    ///
    /// The caller must ensure that:
    /// - `ptr` is valid and points to an allocated `Node<T>`
    /// - `next` is valid and points to an allocated `Node<T>`
    /// - The new pointer maintains list invariants (circular chain)
    ///
    /// # Examples
    ///
    /// ```ignore
    /// use circular_doubly_linked_list::node::Node;
    ///
    /// unsafe {
    ///     let node1 = Node::new(1);
    ///     let node2 = Node::new(2);
    ///     
    ///     Node::set_next(node1, node2);
    ///     assert_eq!(Node::get_next(node1).as_ptr(), node2.as_ptr());
    ///     
    ///     Node::dealloc(node1);
    ///     Node::dealloc(node2);
    /// }
    /// ```
    pub(crate) unsafe fn set_next(ptr: NonNull<Self>, next: NonNull<Self>) {
        unsafe { (*ptr.as_ptr()).next = next }
    }

    /// Updates the previous pointer of the node.
    ///
    /// # Parameters
    ///
    /// * `ptr` - NonNull pointer to the node whose prev pointer will be updated
    /// * `prev` - New previous pointer (must point to a valid `Node<T>`)
    ///
    /// # Safety
    ///
    /// The caller must ensure that:
    /// - `ptr` is valid and points to an allocated `Node<T>`
    /// - `prev` is valid and points to an allocated `Node<T>`
    /// - The new pointer maintains list invariants (circular chain)
    ///
    /// # Examples
    ///
    /// ```ignore
    /// use circular_doubly_linked_list::node::Node;
    ///
    /// unsafe {
    ///     let node1 = Node::new(1);
    ///     let node2 = Node::new(2);
    ///     
    ///     Node::set_prev(node2, node1);
    ///     assert_eq!(Node::get_prev(node2).as_ptr(), node1.as_ptr());
    ///     
    ///     Node::dealloc(node1);
    ///     Node::dealloc(node2);
    /// }
    /// ```
    pub(crate) unsafe fn set_prev(ptr: NonNull<Self>, prev: NonNull<Self>) {
        unsafe { (*ptr.as_ptr()).prev = prev }
    }

    /// Returns the next pointer of the node.
    ///
    /// # Parameters
    ///
    /// * `ptr` - NonNull pointer to the node
    ///
    /// # Returns
    ///
    /// Returns the `next` pointer as `NonNull<Node<T>>`.
    ///
    /// # Safety
    ///
    /// The caller must ensure that `ptr` is a valid pointer to an allocated `Node<T>`.
    ///
    /// # Examples
    ///
    /// ```ignore
    /// use circular_doubly_linked_list::node::Node;
    ///
    /// let node_ptr = Node::new(42);
    ///
    /// unsafe {
    ///     let next = Node::get_next(node_ptr);
    ///     // For standalone node, next points to self
    ///     assert_eq!(next.as_ptr(), node_ptr.as_ptr());
    ///     
    ///     Node::dealloc(node_ptr);
    /// }
    /// ```
    pub(crate) unsafe fn get_next(ptr: NonNull<Self>) -> NonNull<Self> {
        unsafe { (*ptr.as_ptr()).next }
    }

    /// Returns the previous pointer of the node.
    ///
    /// # Parameters
    ///
    /// * `ptr` - NonNull pointer to the node
    ///
    /// # Returns
    ///
    /// Returns the `prev` pointer as `NonNull<Node<T>>`.
    ///
    /// # Safety
    ///
    /// The caller must ensure that `ptr` is a valid pointer to an allocated `Node<T>`.
    ///
    /// # Examples
    ///
    /// ```ignore
    /// use circular_doubly_linked_list::node::Node;
    ///
    /// let node_ptr = Node::new(42);
    ///
    /// unsafe {
    ///     let prev = Node::get_prev(node_ptr);
    ///     // For standalone node, prev points to self
    ///     assert_eq!(prev.as_ptr(), node_ptr.as_ptr());
    ///     
    ///     Node::dealloc(node_ptr);
    /// }
    /// ```
    pub(crate) unsafe fn get_prev(ptr: NonNull<Self>) -> NonNull<Self> {
        unsafe { (*ptr.as_ptr()).prev }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Tests basic node creation with primitive data.
    ///
    /// # Purpose
    ///
    /// Verifies that a new node can be created with primitive integer data
    /// and that the data is correctly stored and retrievable.
    ///
    /// # Expected Behavior
    ///
    /// - Node is successfully created
    /// - Data value matches the input
    /// - Node can be deallocated without errors
    ///
    /// # Test Steps
    ///
    /// 1. Create a new node with value 42
    /// 2. Verify the data can be read back
    /// 3. Deallocate the node and verify data recovery
    ///
    /// # Safety
    ///
    /// This test uses unsafe operations as required by the Node API.
    #[test]
    fn test_node_creation_with_primitive() {
        // Create a new node with integer data
        let ptr = Node::new(42);

        unsafe {
            // Verify the data is correctly stored
            assert_eq!(
                *Node::data_ref(ptr),
                42,
                "Node data should match input value"
            );

            // Deallocate and verify data recovery
            let recovered = Node::dealloc(ptr);
            assert_eq!(
                recovered, 42,
                "Deallocated data should match original value"
            );
        }
    }

    /// Tests node creation with string data.
    ///
    /// # Purpose
    ///
    /// Verifies that nodes can store complex types like String with proper
    /// memory management and drop semantics.
    ///
    /// # Expected Behavior
    ///
    /// - String data is correctly stored
    /// - String can be read back without corruption
    /// - String is properly recovered on deallocation
    ///
    /// # Memory Considerations
    ///
    /// String types require heap allocation, testing that Node properly
    /// handles types with drop glue.
    #[test]
    fn test_node_creation_with_string() {
        let input = String::from("hello world");
        let ptr = Node::new(input.clone());

        unsafe {
            assert_eq!(
                *Node::data_ref(ptr),
                "hello world",
                "String data should be preserved"
            );

            let recovered = Node::dealloc(ptr);
            assert_eq!(recovered, input, "Recovered string should match original");
        }
    }

    /// Tests that a standalone node has self-referential pointers.
    ///
    /// # Purpose
    ///
    /// Verifies the circular invariant for a single node: both `next` and
    /// `prev` pointers should point to the node itself.
    ///
    /// # Expected Behavior
    ///
    /// - `next` pointer equals the node's own pointer
    /// - `prev` pointer equals the node's own pointer
    /// - This enables single-element list functionality
    ///
    /// # Invariants Tested
    ///
    /// For a standalone node N:
    /// - N.next == N
    /// - N.prev == N
    ///
    /// # Safety
    ///
    /// Pointer comparisons are safe as we're only comparing addresses,
    /// not dereferencing.
    #[test]
    fn test_node_self_referential_pointers() {
        let ptr = Node::new("test");

        unsafe {
            // Get the next and prev pointers
            let next_ptr = Node::get_next(ptr);
            let prev_ptr = Node::get_prev(ptr);

            // Verify both point to the same node (self-referential)
            assert_eq!(
                next_ptr.as_ptr(),
                ptr.as_ptr(),
                "Next pointer should point to self for standalone node"
            );
            assert_eq!(
                prev_ptr.as_ptr(),
                ptr.as_ptr(),
                "Prev pointer should point to self for standalone node"
            );

            Node::dealloc(ptr);
        }
    }

    /// Tests mutable data access through the node.
    ///
    /// # Purpose
    ///
    /// Verifies that node data can be modified through a mutable reference
    /// and that changes persist.
    ///
    /// # Expected Behavior
    ///
    /// - Mutable reference can be obtained
    /// - Data can be modified through the reference
    /// - Modified value is visible on subsequent reads
    ///
    /// # Use Case
    ///
    /// This functionality enables in-place modification of list elements
    /// without removal and re-insertion.
    #[test]
    fn test_node_data_mutable_access() {
        let ptr = Node::new(42);

        unsafe {
            // Get mutable reference
            let data_mut = Node::data_mut(ptr);

            // Modify the data
            *data_mut = 100;

            // Verify the change persisted
            assert_eq!(
                *Node::data_ref(ptr),
                100,
                "Modified value should be visible on subsequent read"
            );

            Node::dealloc(ptr);
        }
    }

    /// Tests setting and getting the next pointer.
    ///
    /// # Purpose
    ///
    /// Verifies that the next pointer can be updated and retrieved correctly.
    ///
    /// # Expected Behavior
    ///
    /// - Next pointer can be set to another node
    /// - Get operation returns the previously set pointer
    /// - Original self-reference is overwritten
    ///
    /// # Safety Notes
    ///
    /// The caller must ensure the next pointer is valid. This test uses
    /// valid node pointers to maintain safety.
    #[test]
    fn test_node_set_get_next_pointer() {
        unsafe {
            let node1 = Node::new(1);
            let node2 = Node::new(2);

            // Set node1's next to node2
            Node::set_next(node1, node2);

            // Verify the pointer was set correctly
            let retrieved_next = Node::get_next(node1);
            assert_eq!(
                retrieved_next.as_ptr(),
                node2.as_ptr(),
                "Next pointer should match the set value"
            );

            // Verify node2's pointer wasn't affected
            let node2_next = Node::get_next(node2);
            assert_eq!(
                node2_next.as_ptr(),
                node2.as_ptr(),
                "Node2's next should still be self-referential"
            );

            Node::dealloc(node1);
            Node::dealloc(node2);
        }
    }

    /// Tests setting and getting the previous pointer.
    ///
    /// # Purpose
    ///
    /// Verifies that the prev pointer can be updated and retrieved correctly.
    ///
    /// # Expected Behavior
    ///
    /// - Prev pointer can be set to another node
    /// - Get operation returns the previously set pointer
    /// - Original self-reference is overwritten
    ///
    /// # Safety Notes
    ///
    /// The caller must ensure the prev pointer is valid. This test uses
    /// valid node pointers to maintain safety.
    #[test]
    fn test_node_set_get_prev_pointer() {
        unsafe {
            let node1 = Node::new(1);
            let node2 = Node::new(2);

            // Set node2's prev to node1
            Node::set_prev(node2, node1);

            // Verify the pointer was set correctly
            let retrieved_prev = Node::get_prev(node2);
            assert_eq!(
                retrieved_prev.as_ptr(),
                node1.as_ptr(),
                "Prev pointer should match the set value"
            );

            // Verify node1's pointer wasn't affected
            let node1_prev = Node::get_prev(node1);
            assert_eq!(
                node1_prev.as_ptr(),
                node1.as_ptr(),
                "Node1's prev should still be self-referential"
            );

            Node::dealloc(node1);
            Node::dealloc(node2);
        }
    }

    /// Tests node creation with explicit pointers.
    ///
    /// # Purpose
    ///
    /// Verifies the `with_pointers` constructor correctly initializes
    /// a node with custom next and prev pointers.
    ///
    /// # Expected Behavior
    ///
    /// - Node is created with specified data
    /// - Next pointer matches the provided value
    /// - Prev pointer matches the provided value
    ///
    /// # Use Case
    ///
    /// This constructor is used when inserting nodes between existing
    /// nodes in the list.
    #[test]
    fn test_node_creation_with_explicit_pointers() {
        unsafe {
            let node1 = Node::new(1);
            let node2 = Node::new(2);

            // Create a new node with explicit pointers
            let node3 = Node::with_pointers(3, node2, node1);

            // Verify data
            assert_eq!(*Node::data_ref(node3), 3, "Data should match input");

            // Verify next pointer
            let next = Node::get_next(node3);
            assert_eq!(
                next.as_ptr(),
                node2.as_ptr(),
                "Next pointer should match provided value"
            );

            // Verify prev pointer
            let prev = Node::get_prev(node3);
            assert_eq!(
                prev.as_ptr(),
                node1.as_ptr(),
                "Prev pointer should match provided value"
            );

            Node::dealloc(node1);
            Node::dealloc(node2);
            Node::dealloc(node3);
        }
    }

    /// Tests deallocation returns the original data.
    ///
    /// # Purpose
    ///
    /// Verifies that `dealloc` properly extracts and returns the data
    /// while freeing the node's memory.
    ///
    /// # Expected Behavior
    ///
    /// - Dealloc returns the exact data that was stored
    /// - The returned value owns the data (move semantics)
    /// - Memory is properly freed (no leaks)
    ///
    /// # Memory Safety
    ///
    /// After deallocation, the pointer must not be used. This test
    /// ensures we don't access the pointer after dealloc.
    #[test]
    fn test_node_dealloc_returns_data() {
        let original_value = 42;
        let ptr = Node::new(original_value);

        unsafe {
            let recovered = Node::dealloc(ptr);
            assert_eq!(
                recovered, original_value,
                "Dealloc should return the original data"
            );

            // ptr must not be used after this point
            // Using it would be undefined behavior
        }
    }

    /// Tests node with Vec type (complex heap-allocated data).
    ///
    /// # Purpose
    ///
    /// Verifies that nodes can store complex heap-allocated types
    /// with proper memory management.
    ///
    /// # Expected Behavior
    ///
    /// - Vec data is correctly stored
    /// - Vec can be read without corruption
    /// - Vec is properly recovered on deallocation
    ///
    /// # Memory Considerations
    ///
    /// Vec types have internal heap allocations, testing that Node
    /// properly handles types with complex drop semantics.
    #[test]
    fn test_node_with_vec_type() {
        let input = vec![1, 2, 3, 4, 5];
        let ptr = Node::new(input.clone());

        unsafe {
            assert_eq!(*Node::data_ref(ptr), input, "Vec data should be preserved");

            let recovered = Node::dealloc(ptr);
            assert_eq!(recovered, input, "Recovered Vec should match original");
        }
    }

    /// Tests node with Option type.
    ///
    /// # Purpose
    ///
    /// Verifies that nodes can store enum types like Option.
    ///
    /// # Expected Behavior
    ///
    /// - Option::Some is correctly stored
    /// - Option::None is correctly stored
    /// - Enum discriminant is preserved
    #[test]
    fn test_node_with_option_type() {
        // Test with Some
        let ptr_some = Node::new(Some(42));
        unsafe {
            assert_eq!(*Node::data_ref(ptr_some), Some(42));
            Node::dealloc(ptr_some);
        }

        // Test with None
        let ptr_none: NonNull<Node<Option<i32>>> = Node::new(None);
        unsafe {
            assert_eq!(*Node::data_ref(ptr_none), None);
            Node::dealloc(ptr_none);
        }
    }

    /// Tests node with custom struct type.
    ///
    /// # Purpose
    ///
    /// Verifies that nodes can store user-defined struct types.
    ///
    /// # Expected Behavior
    ///
    /// - Struct fields are correctly stored
    /// - All fields are accessible
    /// - Struct is properly recovered
    ///
    /// # Use Case
    ///
    /// This demonstrates that Node works with any type T, not just
    /// primitives.
    #[test]
    fn test_node_with_custom_struct() {
        #[derive(Debug, Clone, PartialEq)]
        struct Point {
            x: i32,
            y: i32,
        }

        let input = Point { x: 10, y: 20 };
        let ptr = Node::new(input.clone());

        unsafe {
            assert_eq!(
                *Node::data_ref(ptr),
                input,
                "Custom struct should be preserved"
            );

            let recovered = Node::dealloc(ptr);
            assert_eq!(recovered, input, "Recovered struct should match original");
        }
    }

    /// Tests multiple pointer updates on the same node.
    ///
    /// # Purpose
    ///
    /// Verifies that pointers can be updated multiple times correctly.
    ///
    /// # Expected Behavior
    ///
    /// - Each update overwrites the previous value
    /// - Final state reflects the last update
    /// - No memory corruption occurs
    #[test]
    fn test_node_multiple_pointer_updates() {
        unsafe {
            let node1 = Node::new(1);
            let node2 = Node::new(2);
            let node3 = Node::new(3);

            // Initial state: self-referential
            assert_eq!(Node::get_next(node1).as_ptr(), node1.as_ptr());

            // First update
            Node::set_next(node1, node2);
            assert_eq!(Node::get_next(node1).as_ptr(), node2.as_ptr());

            // Second update
            Node::set_next(node1, node3);
            assert_eq!(
                Node::get_next(node1).as_ptr(),
                node3.as_ptr(),
                "Second update should overwrite first"
            );

            Node::dealloc(node1);
            Node::dealloc(node2);
            Node::dealloc(node3);
        }
    }

    /// Tests node with boolean type.
    ///
    /// # Purpose
    ///
    /// Verifies that nodes can store primitive boolean values.
    #[test]
    fn test_node_with_bool_type() {
        let ptr_true = Node::new(true);
        let ptr_false = Node::new(false);

        unsafe {
            assert_eq!(*Node::data_ref(ptr_true), true);
            assert_eq!(*Node::data_ref(ptr_false), false);

            Node::dealloc(ptr_true);
            Node::dealloc(ptr_false);
        }
    }

    /// Tests node with float type.
    ///
    /// # Purpose
    ///
    /// Verifies that nodes can store floating-point values.
    #[test]
    fn test_node_with_float_type() {
        let ptr = Node::new(3.14159f64);

        unsafe {
            let value = *Node::data_ref(ptr);
            assert!(
                (value - 3.14159).abs() < f64::EPSILON,
                "Float value should be preserved"
            );
            Node::dealloc(ptr);
        }
    }

    /// Tests node with tuple type.
    ///
    /// # Purpose
    ///
    /// Verifies that nodes can store tuple types.
    #[test]
    fn test_node_with_tuple_type() {
        let input = (42, "hello", true);
        let ptr = Node::new(input);

        unsafe {
            let (num, text, flag) = *Node::data_ref(ptr);
            assert_eq!(num, 42);
            assert_eq!(text, "hello");
            assert_eq!(flag, true);

            Node::dealloc(ptr);
        }
    }

    /// Tests that node pointers are properly aligned.
    ///
    /// # Purpose
    ///
    /// Verifies that allocated nodes meet Rust's alignment requirements.
    ///
    /// # Safety
    ///
    /// Proper alignment is required for safe pointer dereferencing.
    #[test]
    fn test_node_pointer_alignment() {
        let ptr = Node::new(42);

        // NonNull pointers should be properly aligned
        assert!(
            ptr.as_ptr() as usize % core::mem::align_of::<Node<i32>>() == 0,
            "Node pointer should be properly aligned"
        );

        unsafe {
            Node::dealloc(ptr);
        }
    }

    /// Tests node creation in a loop (stress test).
    ///
    /// # Purpose
    ///
    /// Verifies that multiple nodes can be created and deallocated
    /// without memory leaks or corruption.
    ///
    /// # Expected Behavior
    ///
    /// - All nodes are created successfully
    /// - All nodes are deallocated successfully
    /// - No panics or errors occur
    #[test]
    fn test_node_creation_loop() {
        const COUNT: usize = 100;

        for i in 0..COUNT {
            let ptr = Node::new(i);
            unsafe {
                assert_eq!(*Node::data_ref(ptr), i);
                Node::dealloc(ptr);
            }
        }
    }

    /// Tests with_pointers maintains circular links.
    ///
    /// # Purpose
    ///
    /// Verifies that nodes created with explicit pointers can form
    /// valid circular chains.
    ///
    /// # Expected Behavior
    ///
    /// - Three nodes can be linked in a circle
    /// - Each node's next/prev pointers are correct
    ///
    /// # Safety
    ///
    /// This test carefully manages pointer lifetimes to ensure
    /// no use-after-free occurs.
    #[test]
    fn test_with_pointers_circular_chain() {
        unsafe {
            // Create three nodes
            let node1 = Node::new(1);
            let node2 = Node::new(2);
            let node3 = Node::new(3);

            // Link them in a circle using with_pointers for node2
            Node::set_next(node1, node2);
            Node::set_prev(node1, node3);

            // node2 already has self-referential, update it
            Node::set_next(node2, node3);
            Node::set_prev(node2, node1);

            Node::set_next(node3, node1);
            Node::set_prev(node3, node2);

            // Verify circular links
            assert_eq!(Node::get_next(node1).as_ptr(), node2.as_ptr());
            assert_eq!(Node::get_prev(node1).as_ptr(), node3.as_ptr());

            assert_eq!(Node::get_next(node2).as_ptr(), node3.as_ptr());
            assert_eq!(Node::get_prev(node2).as_ptr(), node1.as_ptr());

            assert_eq!(Node::get_next(node3).as_ptr(), node1.as_ptr());
            assert_eq!(Node::get_prev(node3).as_ptr(), node2.as_ptr());

            // Clean up
            Node::dealloc(node1);
            Node::dealloc(node2);
            Node::dealloc(node3);
        }
    }

    /// Tests with_pointers with same next and prev.
    ///
    /// # Purpose
    ///
    /// Verifies behavior when next and prev point to the same node.
    ///
    /// # Expected Behavior
    ///
    /// - Node can be created with identical next/prev pointers
    /// - This is valid for single-element circular lists
    #[test]
    fn test_with_pointers_same_pointers() {
        unsafe {
            let node1 = Node::new(1);

            // Create node2 with both pointers pointing to node1
            let node2 = Node::with_pointers(2, node1, node1);

            assert_eq!(Node::get_next(node2).as_ptr(), node1.as_ptr());
            assert_eq!(Node::get_prev(node2).as_ptr(), node1.as_ptr());

            Node::dealloc(node1);
            Node::dealloc(node2);
        }
    }

    /// Tests with_pointers data integrity.
    ///
    /// # Purpose
    ///
    /// Verifies that data is correctly stored when using with_pointers.
    #[test]
    fn test_with_pointers_data_integrity() {
        unsafe {
            let node1 = Node::new("1".to_string());
            let node2 = Node::new("1".to_string());

            // Test with various data types
            let node_str = Node::with_pointers(String::from("test"), node1, node2);

            assert_eq!(*Node::data_ref(node_str), "test");

            // Clean up
            let _ = Node::dealloc(node_str);
            Node::dealloc(node1);
            Node::dealloc(node2);
        }
    }

    /// Tests with_pointers complex type.
    ///
    /// # Purpose
    ///
    /// Verifies that with_pointers works with complex types.
    #[test]
    fn test_with_pointers_complex_type() {
        #[derive(Debug, Clone, PartialEq)]
        struct Point {
            x: i32,
            y: i32,
        }

        unsafe {
            let node1 = Node::new(Point { x: 0, y: 0 });
            let node2 = Node::new(Point { x: 0, y: 0 });

            let point_data = Point { x: 10, y: 20 };
            let node3 = Node::with_pointers(point_data.clone(), node1, node2);

            assert_eq!(*Node::data_ref(node3), point_data);

            let recovered = Node::dealloc(node3);
            assert_eq!(recovered, point_data);

            Node::dealloc(node1);
            Node::dealloc(node2);
        }
    }

    /// Tests with_pointers followed by pointer updates.
    ///
    /// # Purpose
    ///
    /// Verifies that pointers can be updated after creation.
    #[test]
    fn test_with_pointers_update_after_creation() {
        unsafe {
            let node1 = Node::new(1);
            let node2 = Node::new(2);
            let node3 = Node::new(3);
            let node4 = Node::new(4);

            // Create with initial pointers
            let new_node = Node::with_pointers(100, node1, node2);

            // Verify initial
            assert_eq!(Node::get_next(new_node).as_ptr(), node1.as_ptr());
            assert_eq!(Node::get_prev(new_node).as_ptr(), node2.as_ptr());

            // Update pointers
            Node::set_next(new_node, node3);
            Node::set_prev(new_node, node4);

            // Verify updated
            assert_eq!(Node::get_next(new_node).as_ptr(), node3.as_ptr());
            assert_eq!(Node::get_prev(new_node).as_ptr(), node4.as_ptr());

            // Clean up
            Node::dealloc(node1);
            Node::dealloc(node2);
            Node::dealloc(node3);
            Node::dealloc(node4);
            Node::dealloc(new_node);
        }
    }
}