src.pydasa.structs.lists.arlt ============================= .. py:module:: src.pydasa.structs.lists.arlt .. autoapi-nested-parse:: Module arlt.py =========================================== Module to represent the **ArrayList** data structure in *PyDASA*. Fundamental for the rest of the Dimensional Analysis and Data Science Library. classes: **ArrayList**: Implements a dynamic array data structure with customizable comparison and key functions. *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.arlt.ArrayList Module Contents --------------- .. py:class:: ArrayList Bases: :py:obj:`Generic`\ [\ :py:obj:`pydasa.structs.types.generics.T`\ ] *ArrayList* implements a dynamic array data structure for PyDASA. :param Generic: Generic type for a Python data structure. :type Generic: T :returns: a generic data structure of type *ArrayList* or Dynamic Array with the following attributes: - `cmp_function`: Customizable comparison function for the elements in the *ArrayList*. - `_elements`: Native Python list that contains the elements of the structure. - `key`: Customizable key name for the elements in the *ArrayList*. - `_size`: Number of elements in the structure. - `iodata`: Customizable native Python list to initialize the structure. :rtype: ArrayList .. py:attribute:: cmp_function :type: Optional[Callable[[pydasa.structs.types.generics.T, pydasa.structs.types.generics.T], int]] :value: None Customizable comparison function for *ArrayList* 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 *ArrayList*. 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 *ArrayList*. Defaults to *None* but can be provided during creation. .. py:method:: __post_init__() *__post_init__()* Initializes the *ArrayList* after creation by setting attributes like *cmp_function*, *key*, and *iodata*. *NOTE:* Special method called automatically after object creation. .. py:method:: default_compare(elm1, elm2) *default_compare()* Default comparison function for *ArrayList* 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 *ArrayList*. :returns: number of elements in the *ArrayList*. :rtype: int .. py:property:: empty :type: bool *empty()* Property to check if the *ArrayList* is empty. :returns: True if the *ArrayList* is empty, False otherwise. :rtype: bool .. py:method:: clear() *clear()* reset the *ArrayList* by removing all elements and resetting the size to 0. NOTE: This method is used to empty the *ArrayList* without deleting the object itself. .. py:method:: prepend(elm) *prepend()* adds an element to the beginning of the *ArrayList*. :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 *ArrayList*. :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 a specific position in the *ArrayList*. :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 *ArrayList*. :raises Exception: error if the structure is empty. :returns: the first element of the *ArrayList*. :rtype: T .. py:property:: last :type: pydasa.structs.types.generics.T *last* Property to read the last element of the *ArrayList*. :raises Exception: error if the structure is empty. :returns: the last element of the *ArrayList*. :rtype: T .. py:method:: get(pos) *get()* reads an element from a specific position in the *ArrayList*. :param pos: position of the element to be read. :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 *ArrayList*. :rtype: T .. py:method:: __getitem__(pos) *__getitem__()* reads an element from a specific position in the *ArrayList*. Equivelent to *get()* method. NOTE: This method is used to access the elements of the *ArrayList* using the square brackets notation. :param pos: position of the element to be read. :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 *ArrayList*. :rtype: T .. py:method:: pop_first() *pop_first()* removes the first element from the *ArrayList*. :raises IndexError: error if the structure is empty. :returns: the first element removed from the *ArrayList*. :rtype: T .. py:method:: pop_last() *pop_last()* removes the last element from the *ArrayList*. :raises IndexError: error if the structure is empty. :returns: the last element removed from the *ArrayList*. :rtype: T .. py:method:: remove(pos) *remove()* removes an element from a specific position in the *ArrayList*. :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 *ArrayList*. :rtype: T .. py:method:: compare(elem1, elem2) *compare()* compares two elements using the *cmp_function* defined in the *ArrayList*. :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 *ArrayList*. If the element is found, it returns its index; otherwise, it returns -1. :param elm: element to search for in the *ArrayList*. :type elm: T :returns: index of the element in the *ArrayList* or -1 if not found. :rtype: int .. py:method:: update(new_data, pos) *update()* updates an element in the *ArrayList* at a specific position. :param new_data: new data to be updated in the *ArrayList*. :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 *ArrayList* at specified 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 *ArrayList* containing a sublist of elements from the original *ArrayList*. 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 *ArrayList* containing the sublist of elements. :rtype: ArrayList[T] .. py:method:: concat(other) *concat()* concatenates two *ArrayList* 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 *ArrayList* to be concatenated. :type other: ArrayList[T] :raises TypeError: error if the *other* argument is not an *ArrayList*. :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 *ArrayList* in the first list. :rtype: ArrayList[T] .. py:method:: clone() *clone()* creates a new structure with the copy of the *ArrayList*. The new list is independent of the original list. NOTE: we named the method *clone()* instead of *copy()* to avoid confusion with the native Python *copy()* method. :returns: a new *ArrayList* with the same elements as the original list. :rtype: ArrayList[T] .. py:method:: __iter__() *__iter__()* to iterate over the elements of the *ArrayList*. 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 elements of the list using a for loop. :returns: an iterator object that can be used to iterate over the elements of the list. :rtype: Iterator[T] .. py:method:: __len__() *__len__()* to get the number of elements in the *ArrayList*. This method returns the size of the list. :returns: the number of elements in the *ArrayList*. :rtype: int .. py:method:: __str__() *__str__()* get the string representation of the *ArrayList*. This method returns a string with the elements of the list. :returns: the string representation of the *ArrayList*. :rtype: str .. py:method:: __repr__() *__repr__()* get the string representation of the *ArrayList*. This method returns a string representation. :returns: the string representation of the *ArrayList*. :rtype: str