Merge pull request #4 from tornikegomareli/feature/DSA

Feature: DSA

Author: tornikegomareli

Exercises/20_dsa_queue/README.md

@@ -0,0 +1,125 @@
+# Data Structures: Queue
+
+A Queue is a fundamental data structure that follows the First-In-First-Out (FIFO) principle. Think of it like a line at a coffee shop - the first person to join the line is the first person to be served.
+
+## Official Documentation & References
+- [Swift Algorithm Club - Queue](https://github.com/kodecocodes/swift-algorithm-club/tree/master/Queue)
+- [Apple Developer - Swift Standard Library](https://developer.apple.com/documentation/swift/swift_standard_library)
+- [Data Structures in Swift - Queue Implementation](https://www.kodeco.com/books/data-structures-algorithms-in-swift/v4.0/chapters/8-queues)
+- [Swift Collections Documentation](https://developer.apple.com/documentation/swift/collections)
+- [Generic Programming in Swift](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/generics)
+- [Protocol-Oriented Programming](https://developer.apple.com/videos/play/wwdc2015/408/)
+
+## Queue Characteristics
+
+### Key Properties
+- **FIFO (First-In-First-Out)**: Elements are processed in the order they were added
+- **Two main operations**: Enqueue (add to rear) and Dequeue (remove from front)
+- **Linear data structure**: Elements are arranged in a sequence
+
+### When to Use Queues
+- Task scheduling (process tasks in order received)
+- Breadth-first search algorithms
+- Message queuing systems
+- Print spoolers
+- Call center phone systems
+
+## Core Operations
+
+### Essential Methods
+1. **enqueue(_:)** - Add an element to the rear of the queue
+2. **dequeue()** - Remove and return the element from the front
+3. **peek()** - View the front element without removing it
+4. **isEmpty** - Check if the queue has no elements
+5. **count** - Get the number of elements in the queue
+
+## Implementation Approaches
+
+### Array-Based Queue
+```swift
+struct Queue<Element> {
+    private var elements: [Element] = []
+    
+    mutating func enqueue(_ element: Element) {
+        elements.append(element)
+    }
+    
+    mutating func dequeue() -> Element? {
+        guard !elements.isEmpty else { return nil }
+        return elements.removeFirst()
+    }
+}
+```
+**Pros**: Simple implementation
+**Cons**: O(n) dequeue operation due to array shifting
+
+### Optimized Array-Based Queue
+Uses two arrays or a circular buffer to achieve O(1) amortized operations.
+
+### Linked List-Based Queue
+Uses nodes with references to achieve true O(1) operations for both enqueue and dequeue.
+
+## Time Complexity
+
+| Operation | Array-Based | Optimized | Linked List |
+|-----------|------------|-----------|-------------|
+| Enqueue   | O(1)*      | O(1)      | O(1)        |
+| Dequeue   | O(n)       | O(1)*     | O(1)        |
+| Peek      | O(1)       | O(1)      | O(1)        |
+| Space     | O(n)       | O(n)      | O(n)        |
+
+*Amortized time complexity
+
+## Exercise Progression
+
+1. **queue1.swift** - Basic Structure
+   - Create a Queue struct with storage array
+   - Understand the basic structure
+
+2. **queue2.swift** - Enqueue Operation
+   - Implement adding elements to the queue
+   - Understand rear insertion
+
+3. **queue3.swift** - Dequeue Operation
+   - Implement removing elements from the queue
+   - Handle empty queue cases
+
+4. **queue4.swift** - Peek and Helper Methods
+   - Implement peek to view without removing
+   - Add isEmpty and count properties
+
+5. **queue5.swift** - Generic Queue
+   - Convert to generic implementation
+   - Work with any type, not just Int
+
+6. **queue6.swift** - Protocol Conformance
+   - Make Queue conform to Collection
+   - Enable iteration and standard collection operations
+
+## Tips for Success
+
+1. **Visualize the Queue**: Draw out the queue operations on paper
+2. **Handle Edge Cases**: Always check for empty queue before dequeue/peek
+3. **Think About Efficiency**: Consider time complexity of operations
+4. **Use Optionals**: Return nil for operations on empty queues
+5. **Test Thoroughly**: Try edge cases like single element, empty queue
+
+## Advanced Topics (Beyond These Exercises)
+
+- **Priority Queues**: Elements are dequeued based on priority
+- **Deque (Double-ended Queue)**: Can add/remove from both ends
+- **Circular Queues**: Fixed-size queue that wraps around
+- **Concurrent Queues**: Thread-safe queue implementations
+
+## Real-World Applications
+
+- **iOS Development**: DispatchQueue for managing tasks
+- **Networking**: Request queuing and rate limiting
+- **Gaming**: Turn-based game mechanics
+- **UI**: Animation queues and event handling
+
+## Further Reading
+
+- [Algorithms, 4th Edition - Queues](https://algs4.cs.princeton.edu/13stacks/)
+- [Introduction to Algorithms - CLRS](https://mitpress.mit.edu/books/introduction-algorithms-third-edition)
+- [Swift Forums - Data Structures Discussion](https://forums.swift.org/c/related-projects/swift-collections/72)

Exercises/20_dsa_queue/queue1.swift

@@ -0,0 +1,40 @@
+// queue1.swift
+//
+// Data Structures: Queue - Basic Structure
+// A Queue is a FIFO (First-In-First-Out) data structure.
+// Like a line at a store - first person in line is first to be served.
+//
+// Create a basic Queue structure with storage for integers.
+
+import Foundation
+
+// TODO: Define a Queue struct with:
+// 1. A property called 'elements' that is an array of Int
+// 2. Initialize it as an empty array
+
+struct Queue {
+    // var elements: ??? = ???
+}
+
+func main() {
+    test("Queue initialization") {
+        let queue = Queue()
+        
+        assertEqual(queue.elements.isEmpty, true, 
+                   "Queue should be empty when initialized")
+        assertEqual(queue.elements.count, 0, 
+                   "New queue should have 0 elements")
+    }
+    
+    test("Queue can store elements array") {
+        var queue = Queue()
+        queue.elements = [1, 2, 3]
+        
+        assertEqual(queue.elements, [1, 2, 3],
+                   "Should be able to set elements directly")
+        assertEqual(queue.elements.count, 3,
+                   "Queue should have 3 elements")
+    }
+    
+    runTests()
+}

Exercises/20_dsa_queue/queue2.swift

@@ -0,0 +1,58 @@
+// queue2.swift
+//
+// Data Structures: Queue - Enqueue Operation
+// Enqueue adds elements to the rear (end) of the queue.
+// This is the "getting in line" operation.
+//
+// Implement the enqueue method to add elements to the queue.
+
+import Foundation
+
+struct Queue {
+    var elements: [Int] = []
+    
+    // TODO: Implement the enqueue method
+    // 1. It should be a mutating function (modifies the struct)
+    // 2. Takes an Int parameter called 'element'
+    // 3. Adds the element to the end of the elements array
+    
+    // mutating func enqueue(_ element: ???) {
+    //     ???
+    // }
+}
+
+func main() {
+    test("Enqueue single element") {
+        var queue = Queue()
+        queue.enqueue(10)
+        
+        assertEqual(queue.elements, [10],
+                   "Queue should contain [10] after enqueueing 10")
+    }
+    
+    test("Enqueue multiple elements") {
+        var queue = Queue()
+        queue.enqueue(1)
+        queue.enqueue(2)
+        queue.enqueue(3)
+        
+        assertEqual(queue.elements, [1, 2, 3],
+                   "Elements should be in order [1, 2, 3]")
+        assertEqual(queue.elements.count, 3,
+                   "Queue should have 3 elements")
+    }
+    
+    test("Enqueue maintains FIFO order") {
+        var queue = Queue()
+        queue.enqueue(100)
+        queue.enqueue(200)
+        queue.enqueue(300)
+        
+        assertEqual(queue.elements.first, 100,
+                   "First element should be 100 (first in)")
+        assertEqual(queue.elements.last, 300,
+                   "Last element should be 300 (last in)")
+    }
+    
+    runTests()
+}

Exercises/20_dsa_queue/queue3.swift

@@ -0,0 +1,64 @@
+// queue3.swift
+//
+// Data Structures: Queue - Dequeue Operation
+// Dequeue removes and returns the element from the front of the queue.
+// This is the "being served and leaving the line" operation.
+//
+// Implement the dequeue method to remove elements from the queue.
+
+import Foundation
+
+struct Queue {
+    var elements: [Int] = []
+    
+    mutating func enqueue(_ element: Int) {
+        elements.append(element)
+    }
+    
+    // TODO: Implement the dequeue method
+    // 1. It should be a mutating function
+    // 2. Returns an Optional Int (Int?)
+    // 3. If queue is empty, return nil
+    // 4. Otherwise, remove and return the first element
+    
+    // mutating func dequeue() -> ??? {
+    //     guard !elements.??? else { return ??? }
+    //     return elements.???
+    // }
+}
+
+func main() {
+    test("Dequeue from empty queue") {
+        var queue = Queue()
+        let result = queue.dequeue()
+        
+        assertEqual(result, nil,
+                   "Dequeue from empty queue should return nil")
+    }
+    
+    test("Dequeue single element") {
+        var queue = Queue()
+        queue.enqueue(42)
+        
+        let result = queue.dequeue()
+        assertEqual(result, 42,
+                   "Should dequeue 42")
+        assertEqual(queue.elements.isEmpty, true,
+                   "Queue should be empty after dequeuing last element")
+    }
+    
+    test("Dequeue maintains FIFO order") {
+        var queue = Queue()
+        queue.enqueue(1)
+        queue.enqueue(2)
+        queue.enqueue(3)
+        
+        assertEqual(queue.dequeue(), 1, "First dequeue should return 1")
+        assertEqual(queue.dequeue(), 2, "Second dequeue should return 2")
+        assertEqual(queue.elements, [3], "Queue should contain [3]")
+        assertEqual(queue.dequeue(), 3, "Third dequeue should return 3")
+        assertEqual(queue.dequeue(), nil, "Fourth dequeue should return nil")
+    }
+    
+    runTests()
+}

Exercises/20_dsa_queue/queue4.swift

@@ -0,0 +1,94 @@
+// queue4.swift
+//
+// Data Structures: Queue - Peek and Helper Methods
+// Peek lets you see what's at the front without removing it.
+// isEmpty and count are helpful utilities for queue management.
+//
+// Implement peek, isEmpty, and count for the Queue.
+
+import Foundation
+
+struct Queue {
+    var elements: [Int] = []
+    
+    mutating func enqueue(_ element: Int) {
+        elements.append(element)
+    }
+    
+    mutating func dequeue() -> Int? {
+        guard !elements.isEmpty else { return nil }
+        return elements.removeFirst()
+    }
+    
+    // TODO: Implement peek method
+    // 1. Returns an Optional Int (Int?)
+    // 2. Returns the first element without removing it
+    // 3. Returns nil if queue is empty
+    
+    // func peek() -> ??? {
+    //     return elements.???
+    // }
+    
+    // TODO: Implement isEmpty computed property
+    // Returns true if the queue has no elements
+    
+    // var isEmpty: Bool {
+    //     return elements.???
+    // }
+    
+    // TODO: Implement count computed property
+    // Returns the number of elements in the queue
+    
+    // var count: Int {
+    //     return ???
+    // }
+}
+
+func main() {
+    test("Peek on empty queue") {
+        let queue = Queue()
+        
+        assertEqual(queue.peek(), nil,
+                   "Peek on empty queue should return nil")
+    }
+    
+    test("Peek doesn't remove element") {
+        var queue = Queue()
+        queue.enqueue(10)
+        queue.enqueue(20)
+        
+        assertEqual(queue.peek(), 10, "Peek should return 10")
+        assertEqual(queue.peek(), 10, "Peek again should still return 10")
+        assertEqual(queue.elements, [10, 20], "Elements should remain unchanged")
+    }
+    
+    test("isEmpty property") {
+        var queue = Queue()
+        
+        assertEqual(queue.isEmpty, true, "New queue should be empty")
+        
+        queue.enqueue(1)
+        assertEqual(queue.isEmpty, false, "Queue with element should not be empty")
+        
+        _ = queue.dequeue()
+        assertEqual(queue.isEmpty, true, "Queue should be empty after dequeuing last element")
+    }
+    
+    test("Count property") {
+        var queue = Queue()
+        
+        assertEqual(queue.count, 0, "Empty queue should have count 0")
+        
+        queue.enqueue(1)
+        assertEqual(queue.count, 1, "Count should be 1")
+        
+        queue.enqueue(2)
+        queue.enqueue(3)
+        assertEqual(queue.count, 3, "Count should be 3")
+        
+        _ = queue.dequeue()
+        assertEqual(queue.count, 2, "Count should be 2 after dequeue")
+    }
+    
+    runTests()
+}