Merge pull request #86 from eeshannarula29/clean-up

Clean up and distribute algorithms and data structures

Algorithms/SearchingAlgorithms/README.md

@@ -0,0 +1,152 @@
+# Searching and Path Finding Algorithms
+
+## Searching Lists
+
+The list seaching algorithms can be used with `Lists`, `LinkedLists`, and `DoublyLinkedLists`
+
+### Linear Search
+
+```python
+from structlinks.algorithms.searching_algorithms import linear_search
+
+# initalize a list
+lst = [1, 100, 4, -1, 5]
+
+print(linear_search(lst, -1))
+# Output: True
+
+print(linear_search(lst, 0))
+# Output: False
+```
+
+### Binary Search
+
+Note that for binary search the list to be searched , should be `sorted`
+
+```python
+from structlinks.algorithms.searching_algorithms import binary_search
+
+# initalize a sorted list
+lst = [-1, 1, 4, 5, 100]
+
+print(binary_search(lst, -1))
+# Output: True
+
+print(binary_search(lst, 0))
+# Output: False
+```
+
+## Path Finding in Graphs
+
+### Algorithms For Un-Weighted Graphs
+
+#### Breadth First Search
+
+```python
+from structlinks.structures import Graph
+from structlinks.algorithms.searching_algorithms import breadth_first_search
+
+graph = Graph()
+
+graph.add_vertices([1, 2, 3, 5, 7])
+graph.add_edges([(1, 2), (2, 3), (3, 1), (3, 5)])
+
+path = breadth_first_search(graph, origin = 1, target = 5)
+
+print(path)
+# Output: [(1, 3), (3, 5)]  # <---- Return the edges of the path (1 -> 3 -> 5)
+
+non_existing_path = breadth_first_search(graph, origin = 1, target = 7)  # <-- 1 and 7 are not connected
+
+print(non_existing_path)
+# Output: None
+```
+
+#### Depth First Search
+
+```python
+from structlinks.structures import Graph
+from structlinks.algorithms.searching_algorithms import depth_first_search
+
+graph = Graph()
+
+graph.add_vertices([1, 2, 3, 5])
+graph.add_edges([(1, 2), (2, 3), (3, 1), (3, 5)])
+
+path = depth_first_search(graph, origin = 1, target = 5)
+
+print(path)
+# Output: [(1, 3), (3, 5)]  # <---- Return the edges of the path (1 -> 3 -> 5)
+
+non_existing_path = depth_first_search(graph, origin = 1, target = 7)  # <-- 1 and 7 are not connected
+
+print(non_existing_path)
+# Output: None
+```
+
+### Algorithms For Weighted Graphs
+
+```python
+from structlinks.structures import Graph
+
+graph = Graph()
+
+graph.add_vertices([1, 2, 3, 5, 6, 7])
+
+graph.add_edges([(0, 1, {'weight': 4}),
+                 (2, 1, {'weight': 8}),
+                 (2, 3, {'weight': 7}),
+                 (3, 4, {'weight': 9}),
+                 (4, 5, {'weight': 10}),
+                 (5, 6, {'weight': 2}),
+                 (6, 7, {'weight': 1}),
+                 (7, 0, {'weight': 8}),
+                 (7, 1, {'weight': 11}),
+                 (7, 8, {'weight': 7}),
+                 (6, 8, {'weight': 6}),
+                 (8, 2, {'weight': 2}),
+                 (2, 5, {'weight': 4}),
+                 (3, 5, {'weight': 14})])
+
+```
+
+##### This is how the graph looks:
+
+![Graph](https://github.com/eeshannarula29/structlinks/blob/gh-pages/Fig-11.jpg)
+
+#### Dijkstra's Search Algorithm For Single Path
+
+This is Dijkstra's Search Algorithm for getting a path from an `origin` to a specific `target`
+
+```python
+from structlinks.algorithms.searching_algorithms import dijkstra_search_target
+
+path = dijkstra_search_target(graph, origin = 0, target: 4, metric: 'weight')
+
+print(path)
+# Output: [(0, 7), (7, 6), (6, 5), (5, 4)]  # 0 -> 7 -> 6 -> 5 -> 4
+```
+
+#### Dijkstra's Search Algorithm
+
+This is Dijkstra's Search Algorithm for getting a path from an `origin` to all the other vertices.
+
+```python
+from structlinks.algorithms.searching_algorithms import dijkstra_search_target
+
+paths = dijkstra_search_all(graph, origin = 0, metric: 'weight')
+
+print(paths)
+# Output:
+{
+  1: [(0, 1)],
+  2: [(0, 1), (1, 2)],
+  3: [(0, 1), (1, 2), (2, 3)],
+  4: [(0, 7), (7, 6), (6, 5), (5, 4)],
+  5: [(0, 7), (7, 6), (6, 5)],
+  6: [(0, 7), (7, 6)],
+  7: [(0, 7)],
+  8: [(0, 1), (1, 2), (2, 8)]
+}
+
+```

SearchingAlgorithms.py → Algorithms/SearchingAlgorithms/SearchingAlgorithms.py

@@ -11,11 +11,11 @@
 
 import math
 
-from structlinks.Graph import Graph
-from structlinks.Queue import Queue
-from structlinks.Stack import Stack
-from structlinks.LinkedList import LinkedList
-from structlinks.DoublyLinkedList import DoublyLinkedList
+from structlinks.DataStructures.LinkedList.LinkedList import LinkedList
+from structlinks.DataStructures.DoublyLinkedList.DoublyLinkedList import DoublyLinkedList
+from structlinks.DataStructures.Graph.Graph import Graph
+from structlinks.DataStructures.Queue.Queue import *
+from structlinks.DataStructures.Stack.Stack import Stack
 
 
 def linear_search(lst: Union[list, LinkedList, DoublyLinkedList], item: Any) -> bool:

Algorithms/SearchingAlgorithms/__init__.py

@@ -0,0 +1 @@
+import structlinks.Algorithms.SearchingAlgorithms.SearchingAlgorithms as SearchingAlgorithms

Algorithms/SortingAlgorithms/README.md

@@ -0,0 +1,158 @@
+# Sorting Algorithms
+
+All the sorting algorithms in this module work with `lists`, `LinkedLists` and `DoublyLinkedLists`
+
+## MergeSort-InPlace
+
+Use an inplace mergesort algorithm to return a sorted list.
+This version is inferior (in terms of running time) to the non-mutating implementation of mergesort.
+
+```python
+from structlinks.algorithms.sorting_algorithms import mergesort
+
+# initialize a list
+lst = [1, 100, 50, 20, 4]
+# make a sorted list
+return_value = mergesort(lst)
+
+print(lst)
+# Output:
+# [1, 4, 20, 50, 100]
+
+print(return_value)
+# Output:
+# None
+```
+
+## MergeSort-NonMutating
+
+Use mergesort algorithm to return a sorted list.
+
+```python
+from structlinks.algorithms.sorting_algorithms import no_mut_mergesort
+
+# initialize a list
+lst = [1, 100, 50, 20, 4]
+# make a sorted list
+sorted_lst = no_mut_mergesort(lst)
+
+print(lst)
+# Output:
+# [1, 100, 50, 20, 4]
+
+print(sorted_lst)
+# Output:
+# [1, 4, 20, 50, 100]
+```
+
+## QuickSort-InPlace
+
+Use quicksort algorithm to return a sorted list. This is a _mutating_ method: it modifies the input instead of returning an output.
+
+```python
+from structlinks.algorithms.sorting_algorithms import quicksort
+
+# initialize a list
+lst = [1, 100, 50, 20, 4]
+# make a sorted list
+return_value = quicksort(lst)
+
+print(lst)
+# Output:
+# [1, 4, 20, 50, 100]
+
+print(return_value)
+# Output:
+# None
+```
+
+## QuickSort-NonMutating
+
+Use quicksort algorithm to return a sorted list. This is a _non-mutating_ method: the input list will be preserved.
+Note that the runtime of this version is technically inferior to the mutating version of quicksort, above.
+
+```python
+from structlinks.algorithms.sorting_algorithms import no_mut_quicksort
+
+# initialize a list
+lst = [1, 100, 50, 20, 4]
+# make a sorted list
+sorted_lst = no_mut_quicksort(lst)
+
+print(lst)
+# Output:
+# [1, 100, 50, 20, 4]
+
+print(sorted_lst)
+# Output:
+# [1, 4, 20, 50, 100]
+```
+
+## SelectionSort
+
+Use the selection sort algorithm to return a sorted list. This is a mutating method that changes the input list.
+
+```python
+from structlinks.algorithms.sorting_algorithms import selection_sort
+
+# initialize a list
+lst = [1, 100, 50, 20, 4]
+# make a sorted list
+return_value = selection_sort(lst)
+
+print(lst)
+# Output:
+# [1, 4, 20, 50, 100]
+
+print(return_value)
+# Output:
+# None
+```
+
+## InsertionSort
+
+Use the insertion sort algorithm to return a sorted list. Like selection sort, this is a mutating algorithm that modifies it's input
+
+```python
+from structlinks.algorithms.sorting_algorithms import insertion_sort
+
+# initialize a list
+lst = [1, 100, 50, 20, 4]
+# make a sorted list
+return_value = insertion_sort(lst)
+
+print(lst)
+# Output:
+# [1, 4, 20, 50, 100]
+
+print(return_value)
+# Output:
+# None
+```
+
+# Sorting Algorithms: The Key Parameter
+
+Each sorting algorithm accepts an optional `key` parameter: pass in a function to adjust the weighting scheme (or control the values of) of the elements in the list.
+
+For example, if we wanted to sort the list from largest to smallest (rather than smallest to largest, as is default), we can:
+
+```python
+from structlinks.algorithms.sorting_algorithms import insertion_sort
+
+# Define a function that reverses the weighting of integers
+def invert(x: int) -> int:
+    return -x
+
+# initialize a list
+lst = [1, 100, 50, 20, 4]
+# Sort the list, passing in the function as a key
+return_value = insertion_sort(lst, key=invert)
+
+print(lst)
+# Output:
+# [100, 50, 20, 4, 1]
+
+print(sorted_lst)
+# Output:
+# None
+```

SortingAlgorithms.py → Algorithms/SortingAlgorithms/SortingAlgorithms.py

@@ -14,8 +14,8 @@
         has a default value for key, (lambda x: x) which does not modify it's input
 """
 from typing import Any, Callable, Union
-from structlinks.DoublyLinkedList import DoublyLinkedList
-from structlinks.LinkedList import LinkedList
+from structlinks.DataStructures.LinkedList.LinkedList import LinkedList
+from structlinks.DataStructures.DoublyLinkedList.DoublyLinkedList import DoublyLinkedList
 
 
 ########################################

Algorithms/SortingAlgorithms/__init__.py

@@ -0,0 +1 @@
+import structlinks.Algorithms.SortingAlgorithms.SortingAlgorithms as SortingAlgorithms

Algorithms/__init__.py

@@ -0,0 +1,2 @@
+import structlinks.Algorithms.SearchingAlgorithms.SearchingAlgorithms as searching_algorithms
+import structlinks.Algorithms.SortingAlgorithms.SortingAlgorithms as sorting_algorithms