src.pydasa.structs.lists.sllt ============================= .. py:module:: src.pydasa.structs.lists.sllt .. autoapi-nested-parse:: Module sllt.py =========================================== Module for the custom **SingleLinkedList** data structure in *PyDASA*. Essential for Dimensional Analysis and Data Science operations. Classes: **SingleLinkedList**: Implements a single linked list with methods for insertion, deletion, and traversal. *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.sllt.SingleLinkedList Module Contents --------------- .. py:class:: SingleLinkedList Bases: :py:obj:`Generic`\ [\ :py:obj:`pydasa.structs.types.generics.T`\ ] **SingleLinkedList** implements a single linked list data structure for PyDASA. :param Generic: Generic type for a Python data structure. :type Generic: T :returns: a generic single linked list data structure with the following attributes: - **cmp_function**: function to compare elements in the list. - **key**: key to identify the elements in the list. - **first**: reference to the first node of the list. - **last**: reference to the last node of the list. - **_size**: size of the list. :rtype: SingleLinkedList .. py:attribute:: cmp_function :type: Optional[Callable[[pydasa.structs.types.generics.T, pydasa.structs.types.generics.T], int]] :value: None Customizable comparison function for *SingleLinkedList* elements. Defaults to *dflt_cmp_function_lt()* from *PyDASA*, but can be overridden by the user. .. py:attribute:: _first :type: Optional[pydasa.structs.lists.ndlt.SLNode[pydasa.structs.types.generics.T]] :value: None Reference to the first node of the *SingleLinkedList*. .. py:attribute:: _last :type: Optional[pydasa.structs.lists.ndlt.SLNode[pydasa.structs.types.generics.T]] :value: None Reference to the last node of the *SingleLinkedList*. .. py:attribute:: key :type: Optional[str] :value: '_idx' Customizable key name for identifying elements in the *SingleLinkedList*. Defaults to *DFLT_DICT_KEY = '_id'* from *PyDASA*, but can be overridden by the user. .. py:attribute:: _size :type: int :value: 0 Size of the *SingleLinkedList*, starting at 0 and updated with each modification. .. py:attribute:: iodata :type: Optional[List[pydasa.structs.types.generics.T]] :value: None Optional Python list for loading external data intho the *SingleLinkedList*. Defaults to *None* but can be provided during creation. .. py:method:: default_compare(elm1, elm2) *default_compare()* Default comparison function for *SingleLinkedList* elements. Compares two elements and returns: - 0 if they are equal, - 1 if the first is greater, - -1 if the first is smaller. :param elm1: First element to compare. :type elm1: Any :param elm2: Second element to compare. :type elm2: Any :returns: Comparison result. :rtype: int .. py:property:: size :type: int *size()* Property to retrieve the number of elements in the *SingleLinkedList*. :returns: number of elements in the *SingleLinkedList*. :rtype: int .. py:property:: empty :type: bool *empty()* Property to check if the *SingleLinkedList* is empty. :returns: True if the *SingleLinkedList* is empty, False otherwise. :rtype: bool .. py:method:: clear() *clear()* clears the *SingleLinkedList* by removing all elements and resetting the size to 0. NOTE: This method is used to empty the *SingleLinkedList* without deleting the object itself. .. py:method:: prepend(elm) *prepend()* adds an element to the beginning of the *SingleLinkedList*. :param elm: element to be added to the beginning of the structure. :type elm: T .. py:method:: append(elm) *append()* adds an element to the end of the *SingleLinkedList*. :param elm: element to be added to the end of the structure. :type elm: T .. py:method:: insert(elm, pos) *insert()* adds an element to the *SingleLinkedList* at a specific position. :param elm: element to be added to the structure. :type elm: T :param pos: position where the element will be added. :type pos: int :raises IndexError: error if the structure is empty. :raises IndexError: error if the position is invalid. :raises TypeError: error if the element type is invalid. .. py:property:: first :type: pydasa.structs.types.generics.T *first* Property to read the first element of the *SingleLinkedList*. :raises IndexError: error if the structure is empty. :returns: the first element of the *SingleLinkedList*. :rtype: T .. py:property:: last :type: pydasa.structs.types.generics.T *last* Property to read the last element of the *SingleLinkedList*. :raises Exception: error if the structure is empty. :returns: the last element of the *SingleLinkedList*. :rtype: T .. py:method:: get(pos) *get()* retrieves an element from the *SingleLinkedList* at a specific position. :param pos: position of the element to be retrieved. :type pos: int :raises IndexError: error if the structure is empty. :raises IndexError: error if the position is invalid. :returns: the element at the specified position in the *SingleLinkedList*. :rtype: T .. py:method:: pop_first() *pop_first()* removes the first element from the *SingleLinkedList*. :raises IndexError: error if the structure is empty. :returns: the first element of the *SingleLinkedList*. :rtype: T .. py:method:: pop_last() *pop_last()* removes the last element from the *SingleLinkedList*. :raises IndexError: error if the structure is empty. :returns: the last element of the *SingleLinkedList*. :rtype: T .. py:method:: remove(pos) *remove()* removes an element from the *SingleLinkedList* at a specific position. :param pos: position of the element to be removed. :type pos: int :raises IndexError: error if the structure is empty. :raises IndexError: error if the position is invalid. :returns: the element removed from the *SingleLinkedList*. :rtype: T .. py:method:: compare(elem1, elem2) *compare()* compares two elements using the comparison function defined in the *SingleLinkedList*. :param elem1: first element to compare. :type elem1: T :param elem2: second element to compare. :type elem2: T :raises TypeError: error if the *cmp_function* is not defined. :returns: -1 if elem1 < elem2, 0 if elem1 == elem2, 1 if elem1 > elem2. :rtype: int .. py:method:: index_of(elm) *index_of()* searches for the first occurrence of an element in the *SingleLinkedList*. If the element is found, it returns its index; otherwise, it returns -1. :param elm: element to search for in the *SingleLinkedList*. :type elm: T :returns: index of the element in the *SingleLinkedList* or -1 if not found. :rtype: int .. py:method:: update(new_data, pos) *update()* updates an element in the *SingleLinkedList* at a specific position. :param new_data: new data to be updated in the structure. :type new_data: T :param pos: position of the element to be updated. :type pos: int :raises IndexError: error if the structure is empty. :raises IndexError: error if the position is invalid. .. py:method:: swap(pos1, pos2) *swap()* swaps two elements in the *SingleLinkedList* at specific positions. :param pos1: position of the first element to swap. :type pos1: int :param pos2: position of the second element to swap. :type pos2: int :raises IndexError: error if the structure is empty. :raises IndexError: error if the first position is invalid. :raises IndexError: error if the second position is invalid. .. py:method:: sublist(start, end) *sublist()* creates a new *SingleLinkedList* containing a sublist of elements from the original *SingleLinkedList*. The sublist is defined by the start and end indices. NOTE: The start index is inclusive, and the end index is inclusive. :param start: start index of the sublist. :type start: int :param end: end index of the sublist. :type end: int :raises IndexError: error if the structure is empty. :raises IndexError: error if the start or end index are invalid. :returns: a new *SingleLinkedList* containing the sublist of elements. :rtype: SingleLinkedList[T] .. py:method:: concat(other) *concat()* concatenates two *SingleLinkedList* objects. The elements of the second list are added to the end of the first list. NOTE: The *cmp_function* and *key* attributes of the two lists must be the same. :param other: the second *SingleLinkedList* to be concatenated. :type other: SingleLinkedList[T] :raises TypeError: error if the *other* argument is not an *SingleLinkedList*. :raises TypeError: error if the *key* attributes are not the same. :raises TypeError: error if the *cmp_function* are not the same. :returns: the concatenated *SingleLinkedList* in the first list. :rtype: SingleLinkedList[T] .. py:method:: clone() *clone()* creates a copy of the *SingleLinkedList*. The new list is independent of the original list. NOTE: The elements of the new list are the same as the original list, but they are not references to the same objects. :returns: a new *SingleLinkedList* with the same elements as the original list. :rtype: SingleLinkedList[T] .. py:method:: _error_handler(err) *_error_handler()* to process the context (package/class), function name (method), and the error (exception) that was raised to format a detailed error message and traceback. :param err: Python raised exception. :type err: Exception .. py:method:: _validate_type(elm) *_validate_type()* checks if the type of the element is valid. If the structure is empty, the type is valid. If the structure is not empty, the type must be the same as the first element in the list. This is used to check the type of the element before adding it to the list. :param elm: element to be added to the structure. :type elm: T :raises TypeError: error if the type of the element is not valid. :returns: True if the type is valid, False otherwise. :rtype: bool