feat(datastructures, nested iterator): nested iterator data structure

Author: BrianLusina

datastructures/nested_iterator/README.md

@@ -0,0 +1,179 @@
+# Flatten Nested List Iterator
+
+You are given a nested list of integers nestedList. Each element is either an integer or a list whose elements may also
+be integers or other lists. Implement an iterator to flatten it.
+
+Implement the NestedIterator class:
+
+- NestedIterator(List<NestedInteger> nestedList) Initializes the iterator with the nested list nestedList.
+- int next() Returns the next integer in the nested list.
+- boolean hasNext() Returns true if there are still some integers in the nested list and false otherwise.
+
+Your code will be tested with the following pseudocode:
+
+> initialize iterator with nestedList
+> res = []
+> while iterator.hasNext()
+    append iterator.next() to the end of res
+> return res
+
+If `res` matches the expected flattened list, then your code will be judged as correct.
+
+## Examples
+
+Example 1:
+
+```text
+Input: nestedList = [[1,1],2,[1,1]]
+Output: [1,1,2,1,1]
+Explanation: By calling next repeatedly until hasNext returns false, the order of elements returned by next should be:
+[1,1,2,1,1].
+```
+
+Example 2:
+```text
+Input: nestedList = [1,[4,[6]]]
+Output: [1,4,6]
+Explanation: By calling next repeatedly until hasNext returns false, the order of elements returned by next should be:
+[1,4,6].
+```
+
+## Constraints
+
+- 1 <= nestedList.length <= 500
+- The values of the integers in the nested list is in the range [-10^6, 10^6].
+
+## Topics
+
+- Stack
+- Tree
+- Depth-First Search
+- Design
+- Queue
+- Iterator
+
+## Solution(s)
+
+1. [Depth-First Search Approach](#depth-first-search-approach)
+2. [Stack Approach](#stack-approach)
+
+### Depth-first Search Approach
+
+When we look at this nested list structure, we're essentially dealing with a tree where each node can either be a leaf
+(integer) or a branch (nested list). The challenge is to visit every integer in the correct order, just like reading a
+book - we read each word sequentially, even though the book has a hierarchical structure of chapters, sections, and
+paragraphs.
+
+The key insight is recognizing that we need to "flatten" this hierarchical structure into a linear sequence. Think of it
+like unpacking nested boxes - we open the main box, and for each item inside, if it's another box, we open that too,
+continuing until we find all the actual items (integers).
+
+Since we need to access elements one by one through next() calls, we have two main strategies:
+
+- Lazy evaluation: Only flatten elements when needed during next() or hasNext() calls
+- Eager evaluation: Flatten everything upfront during initialization
+
+The eager approach is simpler and more intuitive here. Why? Because:
+
+- We're going to visit all elements anyway (the iterator will traverse the entire structure)
+- Pre-flattening makes next() and hasNext() operations trivial - just array indexing
+- We avoid the complexity of maintaining state about partially explored nested lists
+
+The DFS pattern naturally fits this problem because it mirrors how we'd manually flatten the list: when we encounter a
+nested list, we immediately dive into it, process all its contents, then continue with the next element at the current
+level. This is exactly what DFS does - it goes as deep as possible before backtracking.
+
+The recursive nature of DFS perfectly matches the recursive structure of nested lists. Each recursive call handles one
+level of nesting, and the base case (finding an integer) is where we actually collect the values into our flattened
+result.
+
+#### Complexity Analysis
+
+##### Time Complexity
+
+- Constructor: `O(n)` where n is the total number of integers in the nested list structure. The DFS traversal visits
+  each element exactly once, whether it's an integer or a nested list. For each integer element, we perform an `O(1)`
+  append operation.
+- next(): `O(1)` - Simply increments the index and returns the element at that position in the flattened list.
+- hasNext(): `O(1) `- Just compares the current index with the length of the list.
+
+##### Space Complexity
+
+- `O(n + d)` where n is the total number of integers in the nested structure and d is the maximum depth of nesting.
+  - `O(n)` for storing all integers in `self.flattened_list` list after flattening.
+  - `O(d)` for the recursive call stack during DFS traversal, where d represents the maximum nesting depth.
+  - In the worst case where the structure is deeply nested (like `[[[[...[[1]]...]]]`), the space complexity would be
+    `O(n)` for both the storage and call stack combined.
+
+Analysis: The approach flattens the entire nested structure upfront during initialization using DFS. This trades
+initialization time for constant-time iteration operations. All integers are extracted and stored in a simple list,
+making subsequent next() and hasNext() operations very efficient at O(1) each.
+
+---
+
+### Stack Approach
+
+We’ll use a stack to solve this problem. The stack will be used to store the integer and list of integers on the iterator
+object. We’ll push all the nested list data in the stack in reverse order in the constructor. The elements are pushed in
+reverse order because the iterator is implemented using a stack. In order to process the nested list correctly, the
+elements need to be accessed in the order they appear in the original nested list.
+
+Here is how we implement the NestedIterator class methods to solve the above problem:
+
+**Constructor**
+
+1. The constructor initializes an empty stack of NestedInteger objects.
+2. The constructor iterates through the input nestedList, starting from the last element to the first element
+   (reverse order). It pushes each element onto the stack using stack.push().
+
+**`hasNext()` method**
+
+The hasNext() method checks if there is a next integer to return from the stack, iterating through nested lists if
+necessary.
+
+1. The top element of the stack is retrieved using stack.peek().
+2. The top element is checked using the method top.isInteger():
+   - If it is an integer, the method returns TRUE because the next element is an integer.
+   - The top element must be a nested list if it is not an integer. In this case:
+     - The top element is popped from the stack using stack.pop().
+     - The list is retrieved using top.getList().
+     - The elements of this nested list are pushed onto the stack in reverse order using stack.push(). This ensures that
+       the first element of the nested list will be processed first.
+3. If the stack is empty, the method returns FALSE.
+
+**`next()` method**
+
+The next() method returns the next integer from the stack.
+1. The method calls hasNext() to check if more integers are available. If hasNext() returns true, the method pops the
+   top element of the stack using stack.pop(), which will be an integer because hasNext() ensures that any nested lists
+   are flattened and only integers remain in the stack.
+2. If hasNext() returns false, the method returns 0.
+
+#### Complexity Analysis
+
+##### Time Complexity
+
+Assume 
+- n is the number of elements, 
+- l is the number of nested lists, and 
+- d is the maximum nesting depth (maximum number of lists inside each other).
+
+**Constructor**: Since the constructor pushes all of the elements from the nested list into the stack, the total time
+will be the size of that list. Therefore, the time complexity will be `O(n+l)`.
+
+**Has Next ()**: This function will be called several times. During all of these calls, the function will iterate over
+all the lists exactly once (the while loop) and process every integer exactly once. Thus, a total of `O(n+l)` effort is
+spent. The iterator will be progressed for every integer in the nested list. Thus, there will be a total of `O(n)` calls.
+Accordingly, the running time for one call to Has Next is `O((n+l)/n)=O(l/n)`.
+
+Next (): This function calls the Has Next function every time. So, its complexity will be the same as that of the Has
+Next function, that is, `O(l/n)`.
+
+##### Space Complexity
+
+The space complexity will be `O(n+l)`
+
+In the worst-case scenario, whereby the outermost list contains 
+n integers or l empty sub-lists, it will cost `O(n+l)` space. Other expensive cases occur when the nesting is very deep.
+It’s useful to remember that d≤l (because each layer of nesting requires another list), but we don’t need to consider
+this for our case.

datastructures/nested_iterator/__init__.py

@@ -0,0 +1,143 @@
+from typing import List, Optional
+
+
+class NestedInteger:
+    # Constructor initializes a single integer if a value has been passed
+    # else it initializes an empty list
+    def __init__(self, integer=None):
+        if integer:
+            self.integer = integer
+        else:
+            self.n_list = []
+            self.integer = 0
+
+    # If this NestedIntegers holds a single integer rather
+    # than a nested list, returns TRUE, else, returns FALSE
+    def is_integer(self):
+        if self.integer:
+            return True
+        return False
+
+    # Returns the single integer, if this NestedIntegers holds a single integer
+    # Returns null if this NestedIntegers holds a nested list
+    def get_integer(self):
+        return self.integer
+
+    #  Sets this NestedIntegers to hold a single integer.
+    def set_integer(self, value):
+        self.n_list = None
+        self.integer = value
+
+    # Sets this NestedIntegers to hold a nested list and adds a nested
+    # integer to it.
+    def add(self, ni):
+        if self.integer:
+            self.n_list = []
+            self.n_list.append(NestedInteger(self.integer))
+            self.integer = None
+        self.n_list.append(ni)
+
+    # Returns the nested list, if this NestedIntegers holds a nested list
+    # Returns null if this NestedIntegers holds a single integer
+    def get_list(self):
+        return self.n_list
+
+
+class NestedIterator:
+    def __init__(self, nested_list: List[NestedInteger]):
+        """
+        Initialize the iterator with a nested list
+        Flatten the nested structure into a simple list of integers
+        Args:
+            nested_list (List[NestedInteger]): A list of NestedInteger objects that may contain integers or nested lists
+        """
+
+        def flatten_nested_list(nested: List[NestedInteger]) -> None:
+            """
+            Recursively flatten a nested list structure using depth first search. This is the core of the solution
+            Args:
+                nested: List[NestedInteger]: A list of nested integer objects to flatten
+            """
+            for nested_integer in nested:
+                if nested_integer.is_integer():
+                    # If it is a single integer, add it to the flattened list
+                    self.flattened_list.append(nested_integer.get_integer())
+                else:
+                    flatten_nested_list(nested_integer.get_list())
+
+        # Initialize the flattened list to store all integers
+        self.flattened_list = []
+        # Initialize the current index pointer (starts at -1, will be incremented before first access
+        self.current_index = -1
+        # Flatten the entire nested list structure
+        flatten_nested_list(nested_list)
+
+    def next(self) -> int:
+        """
+        Return the next integer in the iteration
+        Returns:
+            int: The next integer in the iteration
+        """
+        # Move to the next position
+        self.current_index += 1
+        # Return the integer at the current position
+        return self.flattened_list[self.current_index]
+
+    def has_next(self) -> bool:
+        """
+        Check if there are more integers to iterate over.
+        Returns:
+            bool: True if there are more integers to iterate over
+        """
+        # Check if the next position is within bounds
+        return self.current_index + 1 < len(self.flattened_list)
+
+
+class NestedIteratorV2:
+    """
+    This version uses a stack and iterator approach to flatten the list of NestedInteger objects
+    """
+
+    def __init__(self, nested_list: List[NestedInteger]):
+        """
+        Initialize the iterator with a nested list.
+        Flatten the nested structure into a simple list of integers
+        Args:
+            nested_list (List[NestedInteger]): A list of NestedInteger objects that may contain integers or nested lists
+        """
+        self.nested_list_stack = list(reversed(nested_list))
+
+    def next(self) -> Optional[int]:
+        """
+        Return the next integer in the iteration
+        Returns:
+            int: The next integer in the iteration
+        """
+        if self.has_next():
+            return self.nested_list_stack.pop().get_integer()
+        return None
+
+    def has_next(self) -> bool:
+        """
+        Check if there are more integers to iterate over.
+        Returns:
+            bool: True if there are more integers to iterate over
+        """
+        # Iterate through the stack while the stack is not empty
+        while len(self.nested_list_stack) > 0:
+            # Save the top value of the stack
+            top = self.nested_list_stack[-1]
+            # If the top value is an integer, if true, return True. If not continue
+            if top.is_integer():
+                return True
+
+            # if the top is not an integer, it must be the list of integers. Ppop the list from the stack and save it in
+            # the top_list
+            top_list = self.nested_list_stack.pop().get_list()
+            # Save the length of the top_list in i and iterate in the list
+            i = len(top_list) - 1
+            while i >= 0:
+                # Append the values of the nested list into the stack
+                self.nested_list_stack.append(top_list[i])
+                i -= 1
+        return False

datastructures/nested_iterator/test_nested_iterator.py

@@ -0,0 +1,72 @@
+import unittest
+from typing import List
+from parameterized import parameterized
+from datastructures.nested_iterator import (
+    NestedIterator,
+    NestedInteger,
+    NestedIteratorV2,
+)
+from utils.test_utils import custom_test_name_func
+
+
+NESTED_ITERATOR_TEST_CASES = [
+    ([1, [2, 3], 4], [1, 2, 3, 4]),
+    ([3, [2, 3, 4], 4, [2, 3]], [3, 2, 3, 4, 4, 2, 3]),
+    ([[2, 3], 3, [2, 3], 4, [2, 3, 4, 5]], [2, 3, 3, 2, 3, 4, 2, 3, 4, 5]),
+    ([1, [3, [4, [5, 6], 7], 8], 9], [1, 3, 4, 5, 6, 7, 8, 9]),
+    ([[2, 3, [2, 3]]], [2, 3, 2, 3]),
+]
+
+
+def create_nested_iterator_structure(input_list):
+    def parse_input(nested, input_list):
+        if isinstance(input_list, int):
+            nested.set_integer(input_list)
+        else:
+            for item in input_list:
+                child = NestedInteger()
+                nested.add(child)
+                parse_input(child, item)
+
+    nested_structure = NestedInteger()
+    parse_input(nested_structure, input_list)
+    return nested_structure
+
+
+def create_nested_iterator_from_structure(nested_structure):
+    return NestedIterator(nested_structure.get_list())
+
+
+def create_nested_iterator_v2_from_structure(nested_structure):
+    return NestedIteratorV2(nested_structure.get_list())
+
+
+def flatten_list(nested_iterator_object):
+    result = []
+    while nested_iterator_object.has_next():
+        result.append(nested_iterator_object.next())
+    return result
+
+
+class NestedIteratorTestCase(unittest.TestCase):
+    @parameterized.expand(NESTED_ITERATOR_TEST_CASES, name_func=custom_test_name_func)
+    def test_nested_iterator_dfs(
+        self, nested_list: List[List[int]], expected: List[int]
+    ):
+        nested_integer = create_nested_iterator_structure(nested_list)
+        nested_iterator = create_nested_iterator_from_structure(nested_integer)
+        actual = flatten_list(nested_iterator)
+        self.assertEqual(expected, actual)
+
+    @parameterized.expand(NESTED_ITERATOR_TEST_CASES, name_func=custom_test_name_func)
+    def test_nested_iterator_stack(
+        self, nested_list: List[List[int]], expected: List[int]
+    ):
+        nested_integer = create_nested_iterator_structure(nested_list)
+        nested_iterator = create_nested_iterator_v2_from_structure(nested_integer)
+        actual = flatten_list(nested_iterator)
+        self.assertEqual(expected, actual)
+
+
+if __name__ == "__main__":
+    unittest.main()