Updated README, Added documentation for each algorithm, and fixed bin…

…ary_search tests

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.

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

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)

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:

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

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

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]

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 = []

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):
 

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):
 

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):