feat: (#8) Initialize stack module and define Stack interface for various implementations

Author: brandoniscoding-dev

stack/.gitignore

@@ -0,0 +1,35 @@
+target/
+!.mvn/wrapper/maven-wrapper.jar
+!**/src/main/**/target/
+!**/src/test/**/target/
+
+### IntelliJ IDEA ###
+.idea/
+*.iws
+*.iml
+*.ipr
+
+### Eclipse ###
+.apt_generated
+.classpath
+.factorypath
+.project
+.settings
+.springBeans
+.sts4-cache
+
+### NetBeans ###
+/nbproject/private/
+/nbbuild/
+/dist/
+/nbdist/
+/.nb-gradle/
+build/
+!**/src/main/**/build/
+!**/src/test/**/build/
+
+### VS Code ###
+.vscode/
+
+### Mac OS ###
+.DS_Store

stack/README.md

@@ -0,0 +1,90 @@
+# Sorting Algorithms
+
+This project demonstrates the implementation of multiple sorting algorithms. Sorting algorithms are essential in computer science for ordering data, making it easier to analyze, search, or optimize resources.
+
+## Overview
+
+Sorting algorithms take a collection of items (often numbers or strings) and arrange them in a specific order. In this project, each algorithm is implemented in a generic way to allow for sorting different types of data, provided that they implement the `Comparable` interface.
+
+The key sorting algorithms included are:
+
+- **Bubble Sort**
+- **Selection Sort**
+- **Insertion Sort**
+- **Merge Sort**
+- **Quick Sort**
+
+Each algorithm is analyzed in terms of its:
+- **Time Complexity**: How fast it performs relative to the input size.
+- **Space Complexity**: The amount of additional memory it uses.
+- **Stability**: Whether it preserves the order of equal elements.
+
+## Algorithms
+
+### 1. Bubble Sort
+A simple, comparison-based algorithm that repeatedly steps through the list, compares adjacent items, and swaps them if they are out of order.
+
+- **Time Complexity**: O(n^2) in the worst and average cases, O(n) in the best case when the array is already sorted.
+- **Space Complexity**: O(1)
+- **Stability**: Stable
+
+### 2. Selection Sort
+Selects the minimum element from the unsorted portion of the list and swaps it with the first unsorted element.
+
+- **Time Complexity**: O(n^2) for all cases.
+- **Space Complexity**: O(1)
+- **Stability**: Not stable (may require modifications for stability)
+
+### 3. Insertion Sort
+Builds the final sorted list one element at a time by comparing each new element to the sorted elements and inserting it in the correct position.
+
+- **Time Complexity**: O(n^2) in the worst and average cases, O(n) in the best case.
+- **Space Complexity**: O(1)
+- **Stability**: Stable
+
+### 4. Merge Sort
+A divide-and-conquer algorithm that divides the list into halves, sorts each half, and then merges the two sorted halves together.
+
+- **Time Complexity**: O(n log n) for all cases.
+- **Space Complexity**: O(n) due to the need for temporary arrays.
+- **Stability**: Stable
+
+### 5. Quick Sort
+A highly efficient divide-and-conquer algorithm that selects a "pivot" element, partitions the list around the pivot, and then recursively sorts the partitions.
+
+- **Time Complexity**: O(n log n) on average, O(n^2) in the worst case (can be optimized with random pivots).
+- **Space Complexity**: O(log n) on average due to recursion, O(n) in the worst case.
+- **Stability**: Not stable
+
+## Running the Project
+
+1. **Compile the Code**: Make sure you have Java and Maven installed, and then compile the code using Maven with the following command:
+
+   ```bash
+   mvn compile
+   ```
+
+2. **Run the Sorting Algorithms**: To run the main program, use Maven with the following command:
+
+   ```bash
+   mvn exec:java -Dexec.mainClass="com.brandoniscoding.Main"
+   ```
+
+3. **Run the Tests**: To execute the unit tests for the sorting algorithms, run the following Maven command:
+
+   ```bash
+   mvn test
+   ```
+
+   This will execute all the tests defined in the project and show the results in the terminal.
+
+
+## Contributing
+
+1. **Fork the Repository**: Make your changes in a branch from `master`.
+2. **Commit Messages**: Follow conventions, e.g., `feat: add new sorting algorithm` or `fix: optimize quicksort partition`.
+3. **Pull Requests**: Ensure your code passes all tests before opening a pull request.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

stack/pom.xml

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <groupId>com.brandoniscoding</groupId>
+    <artifactId>sorts</artifactId>
+    <version>1.0-SNAPSHOT</version>
+
+    <properties>
+        <maven.compiler.source>22</maven.compiler.source>
+        <maven.compiler.target>22</maven.compiler.target>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-api</artifactId>
+            <version>5.11.2</version>
+            <scope>test</scope>
+        </dependency>
+
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-engine</artifactId>
+            <version>5.11.2</version>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <version>3.5.1</version>
+            </plugin>
+
+        </plugins>
+    </build>
+    
+</project>

stack/src/main/java/com/brandoniscoding/algorithms/StackImpl.java

@@ -0,0 +1,28 @@
+package com.brandoniscoding.algorithms;
+
+public interface StackImpl<T> {
+
+    // Method to push an element onto the stack
+    void push(T value);
+
+    // Method to pop an element onto the stack
+    T pop();
+
+    // Method to pop at the top element without remove it 
+    T peek();
+
+    // Method ti check if the is empty
+    boolean isEmpty();
+
+    // Method to get a current size of the stack
+    int size();
+
+    // Method to clear all elements from the stack
+    void clear();
+
+    // Method to search for an element in the stack and return its position from the top (1-based index)
+    int search(T element);
+
+    // Method to check if a specific element is present in the stack
+    boolean contains(T element);
+}