[Doc] Export priority and standardize documentation

Author: Nikola Yurukov

fibheap/fibheap.go

@@ -17,56 +17,54 @@ for the algorithm implementation.
 http://www.keithschwarz.com/interesting/code/?dir=fibonacci-heap
 */
 
-/*
-* An implementation of a priority queue backed by a Fibonacci heap,
-* as described by Fredman and Tarjan.  Fibonacci heaps are interesting
-* theoretically because they have asymptotically good runtime guarantees
-* for many operations.  In particular, insert, peek, and decrease-key all
-* run in amortized O(1) time.  dequeueMin and delete each run in amortized
-* O(lg n) time.  This allows algorithms that rely heavily on decrease-key
-* to gain significant performance boosts.  For example, Dijkstra's algorithm
-* for single-source shortest paths can be shown to run in O(m + n lg n) using
-* a Fibonacci heap, compared to O(m lg n) using a standard binary or binomial
-* heap.
-*
-* Internally, a Fibonacci heap is represented as a circular, doubly-linked
-* list of trees obeying the min-heap property.  Each node stores pointers
-* to its parent (if any) and some arbitrary child.  Additionally, every
-* node stores its degree (the number of children it has) and whether it
-* is a "marked" node.  Finally, each Fibonacci heap stores a pointer to
-* the tree with the minimum value.
-*
-* To insert a node into a Fibonacci heap, a singleton tree is created and
-* merged into the rest of the trees.  The merge operation works by simply
-* splicing together the doubly-linked lists of the two trees, then updating
-* the min pointer to be the smaller of the minima of the two heaps.  Peeking
-* at the smallest element can therefore be accomplished by just looking at
-* the min element.  All of these operations complete in O(1) time.
-*
-* The tricky operations are dequeueMin and decreaseKey.  dequeueMin works
-* by removing the root of the tree containing the smallest element, then
-* merging its children with the topmost roots.  Then, the roots are scanned
-* and merged so that there is only one tree of each degree in the root list.
-* This works by maintaining a dynamic array of trees, each initially null,
-* pointing to the roots of trees of each dimension.  The list is then scanned
-* and this array is populated.  Whenever a conflict is discovered, the
-* appropriate trees are merged together until no more conflicts exist.  The
-* resulting trees are then put into the root list.  A clever analysis using
-* the potential method can be used to show that the amortized cost of this
-* operation is O(lg n), see "Introduction to Algorithms, Second Edition" by
-* Cormen, Rivest, Leiserson, and Stein for more details.
-*
-* The other hard operation is decreaseKey, which works as follows.  First, we
-* update the key of the node to be the new value.  If this leaves the node
-* smaller than its parent, we're done.  Otherwise, we cut the node from its
-* parent, add it as a root, and then mark its parent.  If the parent was
-* already marked, we cut that node as well, recursively mark its parent,
-* and continue this process.  This can be shown to run in O(1) amortized time
-* using yet another clever potential function.  Finally, given this function,
-* we can implement delete by decreasing a key to -\infty, then calling
-* dequeueMin to extract it.
- */
-
+/*Package fibheap is an implementation of a priority queue backed by a Fibonacci heap,
+as described by Fredman and Tarjan.  Fibonacci heaps are interesting
+theoretically because they have asymptotically good runtime guarantees
+for many operations.  In particular, insert, peek, and decrease-key all
+run in amortized O(1) time.  dequeueMin and delete each run in amortized
+O(lg n) time.  This allows algorithms that rely heavily on decrease-key
+to gain significant performance boosts.  For example, Dijkstra's algorithm
+for single-source shortest paths can be shown to run in O(m + n lg n) using
+a Fibonacci heap, compared to O(m lg n) using a standard binary or binomial
+heap.
+
+Internally, a Fibonacci heap is represented as a circular, doubly-linked
+list of trees obeying the min-heap property.  Each node stores pointers
+to its parent (if any) and some arbitrary child.  Additionally, every
+node stores its degree (the number of children it has) and whether it
+is a "marked" node.  Finally, each Fibonacci heap stores a pointer to
+the tree with the minimum value.
+
+To insert a node into a Fibonacci heap, a singleton tree is created and
+merged into the rest of the trees.  The merge operation works by simply
+splicing together the doubly-linked lists of the two trees, then updating
+the min pointer to be the smaller of the minima of the two heaps.  Peeking
+at the smallest element can therefore be accomplished by just looking at
+the min element.  All of these operations complete in O(1) time.
+
+The tricky operations are dequeueMin and decreaseKey.  dequeueMin works
+by removing the root of the tree containing the smallest element, then
+merging its children with the topmost roots.  Then, the roots are scanned
+and merged so that there is only one tree of each degree in the root list.
+This works by maintaining a dynamic array of trees, each initially null,
+pointing to the roots of trees of each dimension.  The list is then scanned
+and this array is populated.  Whenever a conflict is discovered, the
+appropriate trees are merged together until no more conflicts exist.  The
+resulting trees are then put into the root list.  A clever analysis using
+the potential method can be used to show that the amortized cost of this
+operation is O(lg n), see "Introduction to Algorithms, Second Edition" by
+Cormen, Rivest, Leiserson, and Stein for more details.
+
+The other hard operation is decreaseKey, which works as follows.  First, we
+update the key of the node to be the new value.  If this leaves the node
+smaller than its parent, we're done.  Otherwise, we cut the node from its
+parent, add it as a root, and then mark its parent.  If the parent was
+already marked, we cut that node as well, recursively mark its parent,
+and continue this process.  This can be shown to run in O(1) amortized time
+using yet another clever potential function.  Finally, given this function,
+we can implement delete by decreasing a key to -\infty, then calling
+dequeueMin to extract it.
+*/
 package fibheap
 
 import (
@@ -78,27 +76,28 @@ import (
  ************** INTERFACE *****************
  ******************************************/
 
-// The FloatingFibonacciHeap is an implementation of a fibonacci heap
+// FloatingFibonacciHeap is an implementation of a fibonacci heap
 // with only floating-point priorities and no user data attached.
 type FloatingFibonacciHeap interface {
-	// Adds and element to the heap
+	// Enqueue adds and element to the heap
 	Enqueue(priority float64) *Entry
-	// Returns the minimum element in the heap
+	// Min returns the minimum element in the heap
 	Min() (*Entry, error)
-	// Is the heap empty?
+	// IsEmpty answers: is the heap empty?
 	IsEmpty() bool
-	// The number of elements in the heap
+	// Size gives the number of elements in the heap
 	Size() uint
-	// Removes and returns the minimal element
-	// in the heap
+	// DequeueMin removes and returns the
+	// minimal element in the heap
 	DequeueMin() (*Entry, error)
-	// Decreases the key of the given element
-	// and sets it to the new given priority
-	// returns the node if succesfully set
+	// DecreaseKey decreases the key of the
+	// given element, sets it to the new
+	// given priority and returns the node
+	// if successfully set
 	DecreaseKey(node *Entry, newPriority float64) (*Entry, error)
-	// Deletes the given element in the heap
+	// Delete deletes the given element in the heap
 	Delete(node *Entry) error
-	// Will merge two heaps
+	// Merge merges two heaps
 	Merge(otherHeap FloatingFibonacciHeap) (FloatingFibonacciHeap, error)
 }
 
@@ -108,7 +107,8 @@ type Entry struct {
 	degree                    int
 	marked                    bool
 	next, prev, child, parent *Entry
-	priority                  float64
+	// Priority is the numerical priority of the node
+	Priority float64
 }
 
 /******************************************
@@ -132,20 +132,18 @@ func newEntry(priority float64) *Entry {
 	result.parent = nil
 	result.next = result
 	result.prev = result
-	result.priority = priority
+	result.Priority = priority
 	return result
 }
 
 // ***********
 // ACTUAL CODE
 // ***********
 
-/*
-NewFloatFibHeap creates a new, empty, Fibonacci heap object.
+// Remember that it's actually *fibHeap and not fibHeap
+// that fulfills the contract of the interface.
 
-Remember that it's actually *fibHeap and not fibHeap
-that fulfills the contract of the interface.
-*/
+// NewFloatFibHeap creates a new, empty, Fibonacci heap object.
 func NewFloatFibHeap() FloatingFibonacciHeap { return &fibHeap{nil, 0} }
 
 func (heap *fibHeap) Enqueue(priority float64) *Entry {
@@ -229,7 +227,7 @@ func (heap *fibHeap) DequeueMin() (*Entry, error) {
 
 			// Determine which of two trees has the smaller root
 			var minT, maxT *Entry
-			if other.priority < curr.priority {
+			if other.Priority < curr.Priority {
 				minT = other
 				maxT = curr
 			} else {
@@ -266,7 +264,7 @@ func (heap *fibHeap) DequeueMin() (*Entry, error) {
 		 * priority, we need to make sure that the min pointer points to
 		 * the root-level one.
 		 */
-		if curr.priority <= heap.min.priority {
+		if curr.Priority <= heap.min.Priority {
 			heap.min = curr
 		}
 	}
@@ -277,7 +275,7 @@ func (heap *fibHeap) DequeueMin() (*Entry, error) {
 
 func (heap *fibHeap) DecreaseKey(node *Entry, newPriority float64) (*Entry, error) {
 
-	if newPriority > node.priority {
+	if newPriority > node.Priority {
 		return nil, fmt.Errorf("The given new priority is larger than the old")
 	}
 
@@ -334,21 +332,21 @@ func mergeLists(one, two *Entry) *Entry {
 	two.next = oneNext
 	two.next.prev = two
 
-	if one.priority < two.priority {
+	if one.Priority < two.Priority {
 		return one
 	}
 	return two
 
 }
 
 func decreaseKeyUnchecked(heap *fibHeap, node *Entry, priority float64) {
-	node.priority = priority
+	node.Priority = priority
 
-	if node.parent != nil && node.priority <= node.parent.priority {
+	if node.parent != nil && node.Priority <= node.parent.Priority {
 		cutNode(heap, node)
 	}
 
-	if node.priority <= heap.min.priority {
+	if node.Priority <= heap.min.Priority {
 		heap.min = node
 	}
 }

fibheap/fibheap_examples_test.go

@@ -15,7 +15,7 @@ func ExampleFloatingFibonacciHeap_Enqueue() {
 	// The function returns a pointer
 	// to the node that contains the new value
 	node := heap.Enqueue(SomeNumber)
-	fmt.Println(node.priority)
+	fmt.Println(node.Priority)
 	// Output: 15.5
 }
 
@@ -24,7 +24,7 @@ func ExampleFloatingFibonacciHeap_Min() {
 	heap.Enqueue(SomeNumber)
 	heap.Enqueue(SomeLargerNumber)
 	min, _ := heap.Min()
-	fmt.Println(min.priority)
+	fmt.Println(min.Priority)
 	// Output: 15.5
 }
 
@@ -52,7 +52,7 @@ func ExampleFloatingFibonacciHeap_DequeueMin() {
 	heap := NewFloatFibHeap()
 	heap.Enqueue(SomeNumber)
 	node, _ := heap.DequeueMin()
-	fmt.Printf("Dequeueing minimal element: %v\n", node.priority)
+	fmt.Printf("Dequeueing minimal element: %v\n", node.Priority)
 	// Output:
 	// Dequeueing minimal element: 15.5
 }
@@ -61,10 +61,10 @@ func ExampleFloatingFibonacciHeap_DecreaseKey() {
 	heap := NewFloatFibHeap()
 	node := heap.Enqueue(SomeNumber)
 	min, _ := heap.Min()
-	fmt.Printf("Minimal element before decreasing key: %v\n", min.priority)
+	fmt.Printf("Minimal element before decreasing key: %v\n", min.Priority)
 	heap.DecreaseKey(node, SomeSmallerNumber)
 	min, _ = heap.Min()
-	fmt.Printf("Minimal element after decreasing key: %v\n", min.priority)
+	fmt.Printf("Minimal element after decreasing key: %v\n", min.Priority)
 	// Output:
 	// Minimal element before decreasing key: 15.5
 	// Minimal element after decreasing key: -10.1
@@ -75,10 +75,10 @@ func ExampleFloatingFibonacciHeap_Delete() {
 	node := heap.Enqueue(SomeNumber)
 	heap.Enqueue(SomeLargerNumber)
 	min, _ := heap.Min()
-	fmt.Printf("Minimal element before deletion: %v\n", min.priority)
+	fmt.Printf("Minimal element before deletion: %v\n", min.Priority)
 	heap.Delete(node)
 	min, _ = heap.Min()
-	fmt.Printf("Minimal element after deletion: %v\n", min.priority)
+	fmt.Printf("Minimal element after deletion: %v\n", min.Priority)
 	// Output:
 	// Minimal element before deletion: 15.5
 	// Minimal element after deletion: 112.211
@@ -91,12 +91,12 @@ func ExampleFloatingFibonacciHeap_Merge() {
 	heap1.Enqueue(SomeLargerNumber)
 	heap2.Enqueue(SomeSmallerNumber)
 	min, _ := heap1.Min()
-	fmt.Printf("Minimal element of heap 1: %v\n", min.priority)
+	fmt.Printf("Minimal element of heap 1: %v\n", min.Priority)
 	min, _ = heap2.Min()
-	fmt.Printf("Minimal element of heap 2: %v\n", min.priority)
+	fmt.Printf("Minimal element of heap 2: %v\n", min.Priority)
 	heap, _ := heap1.Merge(heap2)
 	min, _ = heap.Min()
-	fmt.Printf("Minimal element of merged heap: %v\n", min.priority)
+	fmt.Printf("Minimal element of merged heap: %v\n", min.Priority)
 	// Output:
 	// Minimal element of heap 1: 15.5
 	// Minimal element of heap 2: -10.1

fibheap/fibheap_single_example_test.go

@@ -1,6 +1,6 @@
 package fibheap
 
-// Example Test for the Fibonacci heap with floats
+// Example usage of the Fibonacci heap
 
 import (
 	"fmt"
@@ -15,15 +15,15 @@ func Example() {
 	heap1 := NewFloatFibHeap()
 	fmt.Println("Created heap 1.")
 	nodeh1_1 := heap1.Enqueue(SomeLargerNumberAround15)
-	fmt.Printf("Heap 1 insert: %v\n", nodeh1_1.priority)
+	fmt.Printf("Heap 1 insert: %v\n", nodeh1_1.Priority)
 
 	heap2 := NewFloatFibHeap()
 	fmt.Println("Created heap 2.")
 	fmt.Printf("Heap 2 is empty? %v\n", heap2.IsEmpty())
 	nodeh2_1 := heap2.Enqueue(SomeNumberAroundMinus1000)
-	fmt.Printf("Heap 2 insert: %v\n", nodeh2_1.priority)
+	fmt.Printf("Heap 2 insert: %v\n", nodeh2_1.Priority)
 	nodeh2_2 := heap2.Enqueue(SomeNumberAround0)
-	fmt.Printf("Heap 2 insert: %v\n", nodeh2_2.priority)
+	fmt.Printf("Heap 2 insert: %v\n", nodeh2_2.Priority)
 	fmt.Printf("Heap 1 size: %v\n", heap1.Size())
 	fmt.Printf("Heap 2 size: %v\n", heap2.Size())
 	fmt.Printf("Heap 1 is empty? %v\n", heap1.IsEmpty())
@@ -36,15 +36,15 @@ func Example() {
 
 	mergedHeap.DecreaseKey(nodeh2_1, SomeNumberAroundMinus1003)
 	min, _ := mergedHeap.DequeueMin()
-	fmt.Printf("Dequeue minimum of merged heap: %v\n", min.priority)
+	fmt.Printf("Dequeue minimum of merged heap: %v\n", min.Priority)
 	fmt.Printf("Merged heap size: %v\n", mergedHeap.Size())
 
 	fmt.Printf("Delete from merged heap: %v\n", SomeNumberAround0)
 	mergedHeap.Delete(nodeh2_2)
 	fmt.Printf("Merged heap size: %v\n", mergedHeap.Size())
 
 	min, _ = mergedHeap.DequeueMin()
-	fmt.Printf("Extracting minimum of merged heap: %v\n", min.priority)
+	fmt.Printf("Extracting minimum of merged heap: %v\n", min.Priority)
 	fmt.Printf("Merged heap size: %v\n", mergedHeap.Size())
 	fmt.Printf("Merged heap is empty? %v\n", mergedHeap.IsEmpty())
 

fibheap/fibheap_test.go

@@ -134,16 +134,16 @@ func TestEnqueueDequeueMin(t *testing.T) {
 		min, err = heap.DequeueMin()
 		assert.NoError(t, err)
 		if heap.Size() == 199 {
-			assert.Equal(t, Seq1FirstMinimum, min.priority)
+			assert.Equal(t, Seq1FirstMinimum, min.Priority)
 		}
 		if heap.Size() == 197 {
-			assert.Equal(t, Seq1ThirdMinimum, min.priority)
+			assert.Equal(t, Seq1ThirdMinimum, min.Priority)
 		}
 		if heap.Size() == 195 {
-			assert.Equal(t, Seq1FifthMinimum, min.priority)
+			assert.Equal(t, Seq1FifthMinimum, min.Priority)
 		}
 		if heap.Size() == 0 {
-			assert.Equal(t, Seq1LastMinimum, min.priority)
+			assert.Equal(t, Seq1LastMinimum, min.Priority)
 		}
 	}
 }
@@ -176,7 +176,7 @@ func TestEnqueueDecreaseKey(t *testing.T) {
 	for i := 0; i < len(NumberSequence2Sorted); i++ {
 		min, err = heap.DequeueMin()
 		assert.NoError(t, err)
-		assert.Equal(t, NumberSequence2Sorted[i], min.priority)
+		assert.Equal(t, NumberSequence2Sorted[i], min.Priority)
 	}
 }
 
@@ -209,7 +209,7 @@ func TestEnqueueDelete(t *testing.T) {
 	for i := 0; i < len(NumberSequence2Deleted3ElemSorted); i++ {
 		min, err = heap.DequeueMin()
 		assert.NoError(t, err)
-		assert.Equal(t, NumberSequence2Deleted3ElemSorted[i], min.priority)
+		assert.Equal(t, NumberSequence2Deleted3ElemSorted[i], min.Priority)
 	}
 }
 
@@ -231,7 +231,7 @@ func TestMerge(t *testing.T) {
 	for i := 0; i < len(NumberSequenceMerged3And4Sorted); i++ {
 		min, err = heap.DequeueMin()
 		assert.NoError(t, err)
-		assert.Equal(t, NumberSequenceMerged3And4Sorted[i], min.priority)
+		assert.Equal(t, NumberSequenceMerged3And4Sorted[i], min.Priority)
 	}
 }