- update documentation to account for changes in the red-black tree (exposing root)

README.md

@@ -39,19 +39,18 @@ type Interface interface {
 	Clear()
 	Values() []interface{}
 }
-
 ```
 
 Container specific operations:
 
 ```go
-// Returns sorted container's elements with respect to the passed comparator. 
+// Returns sorted container's elements with respect to the passed comparator.
 // Does not effect the ordering of elements within the container.
 // Uses timsort.
 func GetSortedValues(container Interface, comparator utils.Comparator) []interface{} {
 ```
 
-####Sets 
+####Sets
 
 A set is a data structure that can store elements and no repeated values. It is a computer implementation of the mathematical concept of a finite set. Unlike most other collection types, rather than retrieving a specific element from a set, one typically tests an element for membership in a set. This structed is often used to ensure that no duplicates are present in a collection.
 
@@ -96,8 +95,6 @@ func main() {
 	set.Empty()            // true
 	set.Size()             // 0
 }
-
-	
 ```
 
 #####TreeSet
@@ -125,7 +122,6 @@ func main() {
 	set.Empty()                           // true
 	set.Size()                            // 0
 }
-
 ```
 
 ####Lists
@@ -220,8 +216,6 @@ func main() {
 	list.Add("a")                         // ["a"]
 	list.Clear()                          // []
 }
-
-
 ```
 
 #####DoublyLinkedList
@@ -257,8 +251,6 @@ func main() {
 	list.Add("a")                         // ["a"]
 	list.Clear()                          // []
 }
-
-
 ```
 
 
@@ -279,14 +271,13 @@ type Interface interface {
 	// Clear()
 	// Values() []interface{}
 }
-
 ```
 
 #####LinkedListStack
 
-This stack structure is based on a linked list, i.e. each previous element has a point to the next. 
+This stack structure is based on a linked list, i.e. each previous element has a point to the next.
 
-All operations are guaranted constant time performance, except _Values()_, which is as always of linear time performance.
+All operations are guaranteed constant time performance, except _Values()_, which is as always of linear time performance.
 
 ```go
 package main
@@ -307,7 +298,6 @@ func main() {
 	stack.Empty()       // true
 	stack.Size()        // 0
 }
-
 ```
 
 #####ArrayStack
@@ -335,8 +325,6 @@ func main() {
 	stack.Empty()             // true
 	stack.Size()              // 0
 }
-
-
 ```
 
 ####Maps
@@ -361,7 +349,7 @@ type Interface interface {
 
 #####HashMap
 
-Map structure based on hash tables, more exactly, Go's map. Keys are unordered. 
+Map structure based on hash tables, more exactly, Go's map. Keys are unordered.
 
 All operations are guaranted constant time performance, except _Key()_ and _Values()_ retrieval that of linear time performance.
 
@@ -384,12 +372,11 @@ func main() {
 	m.Empty()          // true
 	m.Size()           // 0
 }
-
 ```
 
 #####TreeMap
 
-Map structure based on our red-black tree implementation. Keys are ordered with respect to the passed comparator. 
+Map structure based on our red-black tree implementation. Keys are ordered with respect to the passed comparator.
 
 _Put()_, _Get()_ and _Remove()_ are guaranteed log(n) time performance.
 
@@ -414,8 +401,6 @@ func main() {
 	m.Empty()                           // true
 	m.Size()                            // 0
 }
-
-
 ```
 
 ####Trees
@@ -432,7 +417,7 @@ type Interface interface {
 	// Values() []interface{}
 }
 ```
- 
+
 #####RedBlackTree
 
 A red–black tree is a binary search tree with an extra bit of data per node, its color, which can be either red or black. The extra bit of storage ensures an approximately balanced tree by constraining how nodes are colored from any path from the root to the leaf. Thus, it is a data structure which is a type of self-balancing binary search tree.
@@ -487,9 +472,10 @@ func main() {
 	tree.Empty() // true
 	tree.Size()  // 0
 }
-
 ```
 
+Extending the red-black tree's functionality  has been demonstrated in the following [example](https://github.com/emirpasic/gods/blob/master/examples/redblacktreeextended.go).
+
 #####BinaryHeap
 
 A binary heap is a heap data structure created using a binary tree. It can be seen as a binary tree with two additional constraints:
@@ -558,7 +544,7 @@ Return values:
   -1, if a < b
    0, if a == b
    1, if a > b
-     
+
 Comparator signature:
 
   type Comparator func(a, b interface{}) int
@@ -640,13 +626,13 @@ func byID(a, b interface{}) int {
 }
 
 func main() {
-	set := treeset.NewWith(byID) 
+	set := treeset.NewWith(byID)
 
 	set.Add(User{2, "Second"})
 	set.Add(User{3, "Third"})
 	set.Add(User{1, "First"})
 	set.Add(User{4, "Fourth"})
-	
+
 	fmt.Println(set) // {1 First}, {2 Second}, {3 Third}, {4 Fourth}
 }
 ```
@@ -670,38 +656,37 @@ func main() {
 	strings = append(strings, "c")              // ["d","a",b","c"]
 	utils.Sort(strings, utils.StringComparator) // ["a","b","c","d"]
 }
-
 ```
 
 ## Motivations
 
-Collections and data structures found in other languages: Java Collections, C++ Standard Template Library (STL) containers, Qt Containers, etc. 
+Collections and data structures found in other languages: Java Collections, C++ Standard Template Library (STL) containers, Qt Containers, etc.
 
 ## Goals
 
-**Fast algorithms**: 
+**Fast algorithms**:
 
   - Based on decades of knowledge and experiences of other libraries mentioned above.
 
-**Memory efficient algorithms**: 
-  
+**Memory efficient algorithms**:
+
   - Avoiding to consume memory by using optimal algorithms and data structures for the given set of problems, e.g. red-black tree in case of TreeMap to avoid keeping redundant sorted array of keys in memory.
 
-**Easy to use library**: 
-  
-  - Well-structued library with minimalistic set of atomic operations from which more complex operations can be crafted.
+**Easy to use library**:
+
+  - Well-structured library with minimalistic set of atomic operations from which more complex operations can be crafted.
+
+**Stable library**:
 
-**Stable library**: 
-  
   - Only additions are permitted keeping the library backward compatible.
 
-**Solid documentation and examples**: 
-  
+**Solid documentation and examples**:
+
   - Learning by example.
 
-**Production ready**: 
+**Production ready**:
 
-  - Still waiting for the project to mature and be used in some heavy back-end tasks.
+  - Used in production.
 
 There is often a tug of war between speed and memory when crafting algorithms. We choose to optimize for speed in most cases within reasonable limits on memory consumption.
 

examples/redblacktree.go

@@ -31,7 +31,7 @@ import (
 	rbt "github.com/emirpasic/gods/trees/redblacktree"
 )
 
-func RedBlacTtreeExample() {
+func RedBlackTreeExample() {
 	tree := rbt.NewWithIntComparator() // empty(keys are of type int)
 
 	tree.Put(1, "x") // 1->x
@@ -46,11 +46,11 @@ func RedBlacTtreeExample() {
 	//
 	//  RedBlackTree
 	//  │           ┌── 6
-	//	│       ┌── 5
-	//	│   ┌── 4
-	//	│   │   └── 3
-	//	└── 2
-	//		└── 1
+	//  │       ┌── 5
+	//  │   ┌── 4
+	//  │   │   └── 3
+	//  └── 2
+	//       └── 1
 
 	_ = tree.Values() // []interface {}{"a", "b", "c", "d", "e", "f"} (in order)
 	_ = tree.Keys()   // []interface {}{1, 2, 3, 4, 5, 6} (in order)

examples/redblacktreeextended.go

@@ -0,0 +1,135 @@
+/*
+Copyright (c) 2015, Emir Pasic
+All rights reserved.
+
+Redistribution and use in source and binary forms, 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.
+
+THIS SOFTWARE 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 HOLDER 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, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+*/
+
+package examples
+
+import (
+	"fmt"
+	rbt "github.com/emirpasic/gods/trees/redblacktree"
+)
+
+type RedBlackTreeExtended struct {
+	*rbt.Tree
+}
+
+func (tree *RedBlackTreeExtended) GetMin() (value interface{}, found bool) {
+	node, found := tree.getMinFromNode(tree.Root)
+	if node != nil {
+		return node.Value, found
+	} else {
+		return nil, false
+	}
+}
+
+func (tree *RedBlackTreeExtended) GetMax() (value interface{}, found bool) {
+	node, found := tree.getMaxFromNode(tree.Root)
+	if node != nil {
+		return node.Value, found
+	} else {
+		return nil, false
+	}
+}
+
+func (tree *RedBlackTreeExtended) RemoveMin() (value interface{}, deleted bool) {
+	node, found := tree.getMinFromNode(tree.Root)
+	if found {
+		tree.Remove(node.Key)
+		return node.Value, found
+	} else {
+		return nil, false
+	}
+}
+
+func (tree *RedBlackTreeExtended) RemoveMax() (value interface{}, deleted bool) {
+	node, found := tree.getMaxFromNode(tree.Root)
+	if found {
+		tree.Remove(node.Key)
+		return node.Value, found
+	} else {
+		return nil, false
+	}
+}
+
+func (tree *RedBlackTreeExtended) getMinFromNode(node *rbt.Node) (foundNode *rbt.Node, found bool) {
+	if node == nil {
+		return nil, false
+	}
+	if node.Left == nil {
+		return node, true
+	} else {
+		return tree.getMinFromNode(node.Left)
+	}
+}
+
+func (tree *RedBlackTreeExtended) getMaxFromNode(node *rbt.Node) (foundNode *rbt.Node, found bool) {
+	if node == nil {
+		return nil, false
+	}
+	if node.Right == nil {
+		return node, true
+	} else {
+		return tree.getMaxFromNode(node.Right)
+	}
+}
+
+func print(tree *RedBlackTreeExtended) {
+	max, _ := tree.GetMax()
+	min, _ := tree.GetMin()
+	fmt.Printf("Value for max key: %v \n", max)
+	fmt.Printf("Value for min key: %v \n", min)
+	fmt.Println(tree)
+}
+
+func RedBlackTreeExtendedExample() {
+	tree := RedBlackTreeExtended{rbt.NewWithIntComparator()}
+
+	tree.Put(1, "a") // 1->x (in order)
+	tree.Put(2, "b") // 1->x, 2->b (in order)
+	tree.Put(3, "c") // 1->x, 2->b, 3->c (in order)
+	tree.Put(4, "d") // 1->x, 2->b, 3->c, 4->d (in order)
+	tree.Put(5, "e") // 1->x, 2->b, 3->c, 4->d, 5->e (in order)
+
+	print(&tree)
+	// Value for max key: e
+	// Value for min key: a
+	// RedBlackTree
+	// │       ┌── 5
+	// │   ┌── 4
+	// │   │   └── 3
+	// └── 2
+	//     └── 1
+
+	tree.RemoveMin() // 2->b, 3->c, 4->d, 5->e (in order)
+	tree.RemoveMax() // 2->b, 3->c, 4->d (in order)
+	tree.RemoveMin() // 3->c, 4->d (in order)
+	tree.RemoveMax() // 3->c (in order)
+
+	print(&tree)
+	// Value for max key: c
+	// Value for min key: c
+	// RedBlackTree
+	// └── 3
+}