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:: _elements :type: List[pydasa.structs.types.generics.T] :value: [] Native Python list storing the elements of the ArrayList. .. 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:: _size :type: int :value: 0 Size of the *ArrayList*, 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 *ArrayList*. Defaults to *None* but can be provided during 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:: 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:: _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