src.pydasa.structs.lists.ndlt
=============================

.. py:module:: src.pydasa.structs.lists.ndlt

.. autoapi-nested-parse::

   Module ndlt.py
   ===========================================

   Module to represent the **Node** data structure for the **Linked List** and **Doubly Linked List** in *PyDASA*.

   Classes:
       **Node**: Base class for creating Single Linked List Node or **SLNode** and Double Linked List Node or **DLNode**.
       **SLNode**: Implements a single linked list node with data and next node reference.
       **DLNode**: Implements a double linked list node with data, next node, and previous node references.


   *IMPORTANT:* based on the implementations proposed by the following authors/books:

       # . Algorithms, 4th Edition, Robert Sedgewick and Kevin Wayne.
       # . Data Structure and Algorithms in Python, M.T. Goodrich, R. Tamassia, M.H. Goldwasser.



Classes
-------

.. autoapisummary::

   src.pydasa.structs.lists.ndlt.Node
   src.pydasa.structs.lists.ndlt.SLNode
   src.pydasa.structs.lists.ndlt.DLNode


Module Contents
---------------

.. py:class:: Node

   Bases: :py:obj:`Generic`\ [\ :py:obj:`pydasa.structs.types.generics.T`\ ]


   **Node** base class for creating Single Linked List Node or **SLNode** and Double Linked List Node or **DLNode**. Fundamental for the **Linked List** and **Doubly Linked List** data structures.

   :param Generic: Generic type for a Python data structure.
   :type Generic: T

   :returns:

             A node object with the following attributes:
                 - `_data`: The data stored in the node.
   :rtype: Node


   .. py:attribute:: _data
      :type:  Optional[pydasa.structs.types.generics.T]
      :value: None


      data stored in the node. By default, it is set to None.


   .. py:method:: _error_handler(err)

      *_error_handler()* function that handles the errors that can occur in the *Node*.

      if an error occurs in *SingleLinkedList*, it formats the error according to the context (package/module/class), the function (method) that generated it, and sends it to the upper component in the *DataStruct* hierarchy to handle it as the user considers appropriate.

      :param err: Exception that occurred in the *Node*.
      :type err: Exception



   .. py:method:: _validate_type(elm)

      *_validate_type()* function that checks if the type of the element is the same as the type of the *Node*.

      :param elm: element to be processed in the *Node*.
      :type elm: Optional[T]
      :param - *T*: Type of the element to be processed in the *Node*.

      :raises TypeError: error if the type of the element to be added is not the same as the type of the elements already contained in the *Node*.

      :returns: True if the type of the element is the same as the type of the *Node*. False otherwise.
      :rtype: bool



   .. py:property:: data
      :type: pydasa.structs.types.generics.T


      *data* Property to read the data in the *Node*. Acts as a getter (*get()*) for the *_data* attribute.

      :returns: data stored in the *Node*.
      :rtype: T


.. py:class:: SLNode

   Bases: :py:obj:`Node`\ [\ :py:obj:`pydasa.structs.types.generics.T`\ ]


   **SLNode** class for creating a Single Linked List Node. Inherits from the **Node** class. Fundamental for the **Linked List** data structure.

   :param Node: **Node** base class for creating single and double linked nodes.
   :type Node: dataclass
   :param Generic: Generic type for a Python data structure.
   :type Generic: T

   :returns:

             A single linked node object with the following attributes:
                 - `_data`: The data stored in the node.
                 - `_next`: The next node of the same type.
   :rtype: SLNode


   .. py:attribute:: _next
      :type:  Optional[SLNode[T]]
      :value: None


      next node of the same type. By default, it is set to None.


   .. py:property:: next
      :type: Optional[SLNode[T]]


      "*next()* Property to read the next node in the list. Acts as a getter (*get()*) for the *_next* attribute.

      :returns: reference to the next node of the list. If there is no next node, it returns None.
      :rtype: Optional["SLNode[T]"]


.. py:class:: DLNode

   Bases: :py:obj:`SLNode`\ [\ :py:obj:`pydasa.structs.types.generics.T`\ ]


   **DLNode** class for creating a Double Linked List Node. Inherits from the **SLNode** class. Fundamental for the **Doubly Linked List** data structure.

   :param SLNode: **SLNode** class for creating a single linked list node.
   :type SLNode: dataclass
   :param Generic: Generic type for a Python data structure.
   :type Generic: T

   :returns:

             A double linked node object with the following attributes:
                 - `_data`: The data stored in the node.
                 - `_next`: The next node of the same type.
                 - `_prev`: The previous node of the same type.
   :rtype: DLNode


   .. py:attribute:: _prev
      :type:  Optional[DLNode[T]]
      :value: None



   .. py:property:: prev
      :type: Optional[DLNode[T]]


      *prev()* Property to read the previous node in the list. Acts as a getter (*get()*) for the *_prev* attribute.

      :returns: reference to the previous node of the list.
      :rtype: node (Optional["DLNode[T]"])