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:: 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:: 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:: __post_init__() *__post_init__()* Initializes the *SingleLinkedList* after creation by setting attributes like *cmp_function*, *key*, *first*, *last*, and *iodata*. *NOTE:* Special method called automatically after object 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:: __getitem__(pos) *__getitem__()* retrieves an element from the *SingleLinkedList* at a specific position. NOTE: This method is used to access the elements of the *SingleLinkedList* using the square brackets notation. :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: Optional[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:: __iter__() *__iter__()* to iterate over the elements of the *SingleLinkedList*. This method returns an iterator object that can be used to iterate over the elements of the list. NOTE: This is used to iterate over the nodes of the list using a for loop. :returns: an iterator object that can be used to iterate over the nodes of the list. :rtype: Iterator[T] .. py:method:: __len__() *__len__()* to get the number of elements in the *SingleLinkedList*. This method returns the size of the list. :returns: the number of elements in the *SingleLinkedList*. :rtype: int .. py:method:: __str__() *__str__()* to get the string representation of the *SingleLinkedList*. This method returns a string with the elements of the list separated by commas. :returns: string representation of the *SingleLinkedList*. :rtype: str .. py:method:: __repr__() *__repr__()* get the string representation of the *SingleLinkedList*. This method returns a string representation, :returns: string representation of the *SingleLinkedList*. :rtype: str