feat(arrays): Add in-place array reversal algorithm (#13370)

* feat(arrays): Add in-place array reversal algorithm

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Enhance docstring for reverse_array function

Updated docstring to clarify that the function returns the reversed list.

* Clarify return value in reverse_array function

Updated docstring to clarify that the function returns the reversed list. Modified example usage to display the reversed array correctly.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Christian Clauss <cclauss@me.com>

Author: 3 people

data_structures/arrays/reverse_array.py

@@ -0,0 +1,72 @@
+"""
+In-place array reversal that also returns the reversed list to the caller.
+This algorithm reverses the elements of a list without using extra space.
+"""
+
+from typing import Any
+
+
+def reverse_array(arr: list[Any]) -> list[Any]:
+    """
+    Reverses a list in-place.
+
+    This function takes a list and reverses its elements using a two-pointer
+    approach. The left pointer starts at the beginning of the list, and the
+    right pointer starts at the end. The elements at these two pointers are
+    swapped, and the pointers move towards the center until they meet or cross.
+
+    Args:
+        arr: The list to be reversed.
+
+    Returns:
+        The same list, now reversed. This allows for method chaining.
+
+    Doctests:
+    >>> reverse_array([1, 2, 3, 4, 5])
+    [5, 4, 3, 2, 1]
+    >>> reverse_array(['a', 'b', 'c', 'd'])
+    ['d', 'c', 'b', 'a']
+    >>> reverse_array([10.5, 20.2, 30.8])
+    [30.8, 20.2, 10.5]
+    >>> reverse_array(["apple", "banana", "cherry"])
+    ['cherry', 'banana', 'apple']
+    >>> reverse_array([1])
+    [1]
+    >>> reverse_array([])
+    []
+    >>> reverse_array(list(range(5)))
+    [4, 3, 2, 1, 0]
+    >>> reverse_array(tuple(range(5)))
+    Traceback (most recent call last):
+        ...
+    TypeError: 'tuple' object does not support item assignment
+    >>> reverse_array(range(5))
+    Traceback (most recent call last):
+        ...
+    TypeError: 'range' object does not support item assignment
+    """
+    left = 0
+    right = len(arr) - 1
+
+    while left < right:
+        # Swap the elements at the left and right pointers
+        arr[left], arr[right] = arr[right], arr[left]
+        # Move the pointers towards the center
+        left += 1
+        right -= 1
+    return arr
+
+
+if __name__ == "__main__":
+    # The doctest module runs the tests embedded in the function's docstring.
+    # To run the tests, execute this script from the command line:
+    # python -m doctest -v reverse_array.py
+    import doctest
+
+    doctest.testmod()
+
+    # Example usage:
+    print("\n--- Example Usage ---")
+    sample_array = [10, 20, 30, 40, 50, 60]
+    print(f"{sample_array = }")
+    print(f"{reverse_array(sample_array) = }")