diff --git a/README.rst b/README.rst index 306db7c..f00d001 100644 --- a/README.rst +++ b/README.rst @@ -1,3 +1,106 @@ -This is currently a work in progress. +Algorithms: a module of useful algorithms for Python +==================================================== -inspired by: https://github.com/kanwei/algorithms +This is an attempt to build a cohesive module of algorithms for Python. + +The purpose of this repo is to be a learning tool for myself and others. + +I used psuedo code from various sources and I have listed them as references in the source code of each algorithm. + +Algorithms implemented so far: +------------------------------ + +**Sorting:** + - Bubble Sort + - Comb Sort + - Heap Sort + - Insertion Sort + - Quick Sort + - Selection Sort + - Shell Sort + +**Searching:** + - Binary Search + - Knuth-Morris-Pratt + +Installation: +------------- + +Requirements are listed in :code:`requirements.txt`. + +If you are using pip and virtualenv you can simply do: :: + $ pip install -r requirements.txt + +To clone the repository simply: :: + $ git clone https://github.com/nryoung/algorithms.git + +in to your working directory. + +Usage: +------ + +Once cloned you can simply do the following in your program: + +.. code:: python + + from algorithms.sorting import bubble_sort + + my_list = bubble_sort.sort(my_list) + +All prequisites for the algorithms are listed in the source code for each algorithm. + +Tests: +------------------------ + +Nose is used as the main test runner and all Unit Tests can be run by: :: + $ python algorithms/run_tests.py + +TODO: +----- + +Below is an ever changing list of things that I would like to accomplish or implement. If you feel something needs to be added simply do a pull request. + +**Algorithms to implement:** + - Rabin-Karp + - Mersenne Twister + - UUID Generator + - Bloom Filters + +**Misc.:** + - Performance Tests + +License: +-------- + +Copyright (c) 2012 by Nic Young and contributors. + +Some rights reserved. + +Redistribution and use in source and binary forms of the software as well +as documentation, with or without modification, are permitted provided +that the following conditions are met: + +* Redistributions of source code must retain the above copyright +notice, this list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above +copyright notice, this list of conditions and the following +disclaimer in the documentation and/or other materials provided +with the distribution. + +* The names of the contributors may not be used to endorse or +promote products derived from this software without specific +prior written permission. + +THIS SOFTWARE AND DOCUMENTATION IS PROVIDED BY THE COPYRIGHT HOLDERS AND +CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT +NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER +OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, +EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, +PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR +PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +SOFTWARE AND DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +DAMAGE. diff --git a/algorithms/searching/binary_search.py b/algorithms/searching/binary_search.py index ee16a65..147e24b 100644 --- a/algorithms/searching/binary_search.py +++ b/algorithms/searching/binary_search.py @@ -1,4 +1,23 @@ -""" Implementation of Binary Search """ +""" + binary_search.py + + This module implements binary search on a sorted list. + + Binary Search Overview: + ------------------------ + Recursively partitions the list until the key is found. + + Pre: a sorted list[0,...n,] integers and the key to search for. + + Post: returns the index of where the first element that matches the key. + + Time Complexity: O(lg n) + + Psuedo Code: http://en.wikipedia.org/wiki/Binary_search + + binary_search.search(sorted_list) -> integer + binary_search.search(sorted_list) -> False +""" def search(seq, key): imin = 0 @@ -17,4 +36,4 @@ def search(seq, key): return search(seq[mid+1:], key) else: - return True + return mid diff --git a/algorithms/searching/kmp_search.py b/algorithms/searching/kmp_search.py index a5ed73c..2bac276 100644 --- a/algorithms/searching/kmp_search.py +++ b/algorithms/searching/kmp_search.py @@ -1,4 +1,22 @@ -""" Implementation of KMP search """ +""" + kmp_search.py + + This module implements kmp search on a sorted list. + + KMP Search Overview: + ------------------------ + Uses a prefix function to reduce the searching time. + + Pre: a sorted list[0,...n,] integers and the key to search for. + + Post: returns the index of where the first element that matches the key. + + Time Complexity: O(n + k), where k is the substring to be found + + Psuedo Code: CLRS. Introduction to Algorithms. 3rd ed. + kmp_search.search(sorted_list) -> integer + kmp_search.search(sorted_list) -> False +""" def search(string, word): n = len(string) diff --git a/algorithms/sorting/bubble_sort.py b/algorithms/sorting/bubble_sort.py index e21ba28..9a12fe6 100644 --- a/algorithms/sorting/bubble_sort.py +++ b/algorithms/sorting/bubble_sort.py @@ -1,5 +1,27 @@ -""" Implementation of Bubble Sort. """ +""" + bubble_sort.py + This module implements bubble sort on an unsorted list and returns the sorted list. + + Bubble Sort Overview: + --------------------- + A naive sorting that compares and swaps adjacent elements from 0,1,2,...,n. + + Pre: an unsorted list[0,...,n] of integers. + + Post: returns a sorted list[0,...,n] in ascending order. + + Time Complexity: O(n^2) + + Space Complexity: O(n) total + + Stable: Yes + + Psuedo code: http://en.wikipedia.org/wiki/Bubble_sort + + bubble_sort.sort(list) -> sorted_list + +""" def sort(seq): for x in seq: diff --git a/algorithms/sorting/comb_sort.py b/algorithms/sorting/comb_sort.py index 7c298c3..02403b1 100644 --- a/algorithms/sorting/comb_sort.py +++ b/algorithms/sorting/comb_sort.py @@ -1,6 +1,27 @@ -""" Implementation of Comb Sort """ +""" + comb_sort.py + This module implements comb sort on an unsorted list and returns a sorted list. + Comb Sort Overview: + ------------------- + Improves on bubble sort by using a gap sequence to remove turtles. + + Pre: an unsorted list[0,...,n] of integers. + + Post: returns a sorted list[0,...,n] in ascending order. + + Time Complexity: O(n^2) + + Space Complexity: O(n) total + + Stable: Yes + + Psuedo code: http://en.wikipedia.org/wiki/Comb_sort + + comb_sort.sort(list) -> sorted_list + +""" def sort(seq): gap = len(seq) swap = True diff --git a/algorithms/sorting/heap_sort.py b/algorithms/sorting/heap_sort.py index f3e2496..c8ec97a 100644 --- a/algorithms/sorting/heap_sort.py +++ b/algorithms/sorting/heap_sort.py @@ -1,5 +1,27 @@ -""" Implementation of Heap Sort """ +""" + heap_sort.py + + This module implements heap sort on an unsorted list and returns a sorted list. + + Heap Sort Overview: + ------------------- + Uses a the max heap data structure implemented in a list. + + Pre: an unsorted list[0,...,n] of integers. + + Post: returns a sorted list[0,...,n] in ascending order. + + Time Complexity: O(n^2) + + Space Complexity: O(n) total + + Stable: Yes + + Psuedo Code: CLRS. Introduction to Algorithms. 3rd ed. + + heap_sort.sort(list) -> sorted_list +""" def max_heapify(seq, i, n): l = i + 1 r = i + 2 diff --git a/algorithms/sorting/insertion_sort.py b/algorithms/sorting/insertion_sort.py index 8ebf277..76f2a3c 100644 --- a/algorithms/sorting/insertion_sort.py +++ b/algorithms/sorting/insertion_sort.py @@ -1,5 +1,26 @@ -""" Implementation of Insertion Sort """ +""" + insertion_sort.py + + This module implements insertion sort on an unsorted list and returns a sorted list. + + Insertion Sort Overview: + ------------------------ + Uses insertion of elements in to the list to sort the list. + + Pre: an unsorted list[0,...,n] of integers. + Post: returns a sorted list[0,...,n] in ascending order. + + Time Complexity: O(n^2) + + Space Complexity: O(n) total + + Stable: Yes + + Psuedo Code: CLRS. Introduction to Algorithms. 3rd ed. + + insertion_sort.sort(list) -> sorted_list +""" def sort(seq): for n in range(1, len(seq)): item = seq[n] diff --git a/algorithms/sorting/merge_sort.py b/algorithms/sorting/merge_sort.py index d4e56cc..d388eb0 100644 --- a/algorithms/sorting/merge_sort.py +++ b/algorithms/sorting/merge_sort.py @@ -1,4 +1,26 @@ -""" Implementation of Merge Sort. """ +""" + merge_sort.py + + This module implements merge sort on an unsorted list and returns a sorted list. + + Merge Sort Overview: + ------------------------ + Uses divide and conquer to recursively divide and sort the list + + Pre: an unsorted list[0,...,n] of integers. + + Post: returns a sorted list[0,...,n] in ascending order. + + Time Complexity: O(n log n) average, O(n log n) worst case + + Space Complexity: O(n) + + Stable: Yes + + Psuedo Code: CLRS. Introduction to Algorithms. 3rd ed. + + merge_sort.sort(list) -> sorted_list +""" def merge(left, right): result = [] diff --git a/algorithms/sorting/quick_sort.py b/algorithms/sorting/quick_sort.py index ee7b3b0..8a80e57 100644 --- a/algorithms/sorting/quick_sort.py +++ b/algorithms/sorting/quick_sort.py @@ -1,4 +1,26 @@ -""" Implementation of Quick Sort """ +""" + quick_sort.py + + This module implements quick sort on an unsorted list and returns a sorted list. + + Quick Sort Overview: + ------------------------ + Uses partitioning to recursively divide and sort the list + + Pre: an unsorted list[0,...,n] of integers. + + Post: returns a sorted list[0,...,n] in ascending order. + + Time Complexity: O(n log n) average, O(n^2) worst case + + Space Complexity: O(n) + + Stable: No + + Psuedo Code: CLRS. Introduction to Algorithms. 3rd ed. + + quick_sort.sort(list) -> sorted_list +""" def sort(seq): diff --git a/algorithms/sorting/selection_sort.py b/algorithms/sorting/selection_sort.py index 1cba9de..775ff3a 100644 --- a/algorithms/sorting/selection_sort.py +++ b/algorithms/sorting/selection_sort.py @@ -1,4 +1,26 @@ -""" Implementation of Selection Sort. """ +""" + selection_sort.py + + This module implements selection sort on an unsorted list and returns a sorted list. + + Selection Sort Overview: + ------------------------ + Uses in-place comparision to sort the list + + Pre: an unsorted list[0,...,n] of integers. + + Post: returns a sorted list[0,...,n] in ascending order. + + Time Complexity: O(n^2) + + Space Complexity: O(n) + + Stable: Yes + + Psuedo Code: http://en.wikipedia.org/wiki/Selection_sort + + selection_sort.sort(list) -> sorted_list +""" def sort(seq): diff --git a/algorithms/sorting/shell_sort.py b/algorithms/sorting/shell_sort.py index 82fdf45..43de482 100644 --- a/algorithms/sorting/shell_sort.py +++ b/algorithms/sorting/shell_sort.py @@ -1,4 +1,26 @@ -""" Implementation of Shell Sort """ +""" + shell_sort.py + + This module implements shell sort on an unsorted list and returns a sorted list. + + Shell Sort Overview: + ------------------------ + Comparision sort that sorts far away elements first to sort the list + + Pre: an unsorted list[0,...,n] of integers. + + Post: returns a sorted list[0,...,n] in ascending order. + + Time Complexity: O(n^2) + + Space Complexity: O(n) + + Stable: Yes + + Psuedo Code: http://en.wikipedia.org/wiki/Shell_sort + + shell_sort.sort(list) -> sorted_list +""" def sort(seq): diff --git a/algorithms/tests/test_searching.py b/algorithms/tests/test_searching.py index 47d63f1..ff13600 100644 --- a/algorithms/tests/test_searching.py +++ b/algorithms/tests/test_searching.py @@ -12,8 +12,8 @@ def test_binarysearch(self): rv2 = binary_search.search(self.seq, 9) rv3 = binary_search.search(self.seq, -1) rv4 = binary_search.search(self.seq, 10) - self.assertTrue(rv1) - self.assertTrue(rv2) + self.assertIs(rv1, 0) + self.assertIs(rv2, 0) self.assertFalse(rv3) self.assertFalse(rv4)