algo-dynamic-arrays

name	algo-dynamic-arrays
description	Implement resizable arrays with ctypes-backed doubling/shrinking; prove append is amortized O(1). Use when asked why list.append is O(1), to build a DynamicArray class, or to compare list vs numpy append speed.
tool_type	python
primary_tool	python

Dynamic Arrays

When to Use

• Explaining or proving why list.append() is O(1) amortized (accounting/aggregate method).
• Implementing a resizable array from scratch (interview-style DynamicArray class) with append/insert/delete/pop.
• Choosing or justifying a growth factor (1.5x vs 2x vs Python's ~1.125x) and a shrink threshold to avoid thrashing.
• Comparing list.append vs np.append vs pre-allocated numpy.ndarray for performance.
• Inspecting CPython's actual list over-allocation via sys.getsizeof.

Version Compatibility

Python ≥ 3.9 (uses list[int]-style generics informally; core logic works on any CPython 3.x). NumPy ≥ 1.24 for the ndarray comparison. No non-stdlib dependency is required for the DynamicArray implementation itself (ctypes is stdlib).

Prerequisites

• Comfortable with Big-O notation and worst-case vs amortized cost.
• pip install numpy only needed for the performance-comparison section.
• Related concept: algo-complexity-analysis for amortized-analysis background.

Goal: Implement a dynamic array supporting O(1) amortized append and O(n) insert/delete, with correct grow/shrink thresholds.

Approach: Store elements in a raw ctypes.py_object buffer sized to _capacity. Double capacity on a full append/insert; halve capacity only once size drops to 1/4 of capacity (not 1/2, to avoid resize thrashing when append/pop alternate near a boundary).

import ctypes
from typing import Any, Iterator


class DynamicArray:
    """Resizable array with amortized O(1) append.

    Resize strategy:
      - Grow: double capacity when full (2x growth factor).
      - Shrink: halve capacity only once size <= capacity/4.
    The 2x growth factor makes n appends cost O(n) total (O(1) amortized).
    The 1/4 shrink threshold (rather than 1/2) prevents thrashing when
    append/pop alternate right at a resize boundary.
    """

    GROWTH_FACTOR: float = 2.0
    SHRINK_THRESHOLD: float = 0.25
    MIN_CAPACITY: int = 1

    def __init__(self, initial_capacity: int = 1) -> None:
        self._size: int = 0
        self._capacity: int = max(initial_capacity, self.MIN_CAPACITY)
        self._array: ctypes.Array = self._make_array(self._capacity)

    def __len__(self) -> int:
        return self._size

    def __getitem__(self, index: int) -> Any:
        if index < 0:
            index += self._size
        if   <= index < ._size:
             IndexError()
         ._array[index]

     () -> Iterator[]:
         i  (._size):
             ._array[i]


     () -> :
         ._capacity

     () -> :
        
         ._size == ._capacity:
            ._resize((._capacity * .GROWTH_FACTOR))
        ._array[._size] = value
        ._size += 

     () -> :
        
         index < :
            index += ._size
           <= index <= ._size:
             IndexError()
         ._size == ._capacity:
            ._resize((._capacity * .GROWTH_FACTOR))
         i  (._size, index, -):
            ._array[i] = ._array[i - ]
        ._array[index] = value
        ._size += 

     () -> :
        
         ._size == :
             IndexError()
         index < :
            index += ._size
           <= index < ._size:
             IndexError()
        value = ._array[index]
         i  (index, ._size - ):
            ._array[i] = ._array[i + ]
        ._size -= 
         ._size <= ._capacity * .SHRINK_THRESHOLD  ._capacity > .MIN_CAPACITY:
            ._resize((._capacity // , .MIN_CAPACITY))
         value

     () -> :
        
         .delete(._size - )

     () -> :
        new_array = ._make_array(new_capacity)
         i  (._size):
            new_array[i] = ._array[i]
        ._array = new_array
        ._capacity = new_capacity

     () -> ctypes.Array:
         (capacity * ctypes.py_object)()

Goal: Prove append is O(1) amortized using the accounting/aggregate method.

Approach: Track cumulative cost of n appends with 2x growth: total resize copies are 1 + 2 + 4 + ... + n/2 ≈ n - 1, plus n unit inserts, giving total cost ≤ 2n - 1, so amortized cost per append is O(1).

def demonstrate_amortized_analysis(n: int = 17) -> float:
    """Trace cost of n appends under 2x growth and return amortized cost/op.

    Resize cost = size copied + 1 insert; regular append cost = 1.
    Total cost stays <= 2n - 1, so amortized cost -> O(1).
    """
    size, capacity, total_cost = 0, 1, 0
    for _ in range(1, n + 1):
        if size == capacity:
            cost = size + 1          # copy `size` elements + insert 1
            capacity *= 2
        else:
            cost = 1
        size += 1
        total_cost += cost
    return total_cost / n


amortized_cost = demonstrate_amortized_analysis(1000)
assert amortized_cost < 3.0, "amortized cost per append must stay O(1), i.e. bounded"

Goal: Understand why np.append is O(n^2) total and when to prefer Python list or pre-allocation.

Approach: np.append allocates a brand-new array and copies everything on every call (no capacity headroom), so n appends cost 0+1+2+...+(n-1) = O(n^2). Use a Python list (amortized O(1) append) and convert once, or pre-allocate a numpy.ndarray when the final size is known.

import time
import numpy as np


def time_appends(n: int = 20_000) -> dict[str, float]:
    """Compare append strategies; returns wall-clock seconds per strategy."""
    results = {}

    start = time.perf_counter()
    py_list = []
    for i in range(n):
        py_list.append(i)          # amortized O(1) each -> O(n) total
    results["python_list"] = time.perf_counter() - start

    start = time.perf_counter()
    np_arr = np.array([], dtype=np.int64)
    for i in range(n):
        np_arr = np.append(np_arr, i)   # full copy every call -> O(n^2) total
    results["numpy_append_naive"] = time.perf_counter() - start

    start = time.perf_counter()
    np_fixed = np.empty(n, dtype=np.int64)
    for i in range(n):
        np_fixed[i] = i             # O(1) each, size known upfront
    results["numpy_preallocated"] = time.perf_counter() - start

    return results

Pitfalls

• Shrink at 1/4, not 1/2: shrinking as soon as size drops below 1/2 capacity causes O(n) cost every time append/pop alternate right at that boundary (resize thrashing).
• ctypes.py_object array raises ValueError/garbage on uninitialized access: only ever read slots < self._size; the same applies to numpy.empty, which leaves memory uninitialized — never read beyond the tracked count.
• np.append is not amortized O(1): it always allocates a new buffer and copies everything, giving O(n^2) total cost across n calls — never loop it; use list.append then np.array(...), or pre-allocate.
• list.insert(0, x) is O(n): every element shifts right; use collections.deque (O(1) append/pop from both ends) if you need frequent front operations.
• CPython's real growth factor is ~1.125x, not 2x: don't assume sys.getsizeof(lst) grows by exactly 2x per resize — verify empirically before relying on a specific over-allocation formula.

See Also

• algo-linked-lists — alternative when frequent middle insertion/deletion matters more than O(1) append.
• algo-stacks-queues — deque-based O(1) front/back operations built on dynamic arrays or linked lists.
• algo-complexity-analysis — general amortized-analysis techniques (accounting, potential method).
• algo-hash-tables-bloom — another data structure whose resizing shares the same amortized-doubling analysis.