- test iterator end on reverse-iterable data structures

- fix red-black tree iteration with explicit begin and end states
- examples for iterators (with index and key) (with forward and reverse iteration)

README.md

@@ -649,8 +649,9 @@ All ordered containers have stateful iterators. Typically an iterator is obtaine
 
 #### IteratorWithIndex
 
-A [iterator](#iterator) whose elements are referenced by an index. Typical usage:
+An [iterator](#iterator) whose elements are referenced by an index.
 
+Typical usage:
 ```go
 it := list.Iterator()
 for it.Next() {
@@ -659,44 +660,89 @@ for it.Next() {
 }
 ```
 
+Other usages:
+```go
+if it.First() {
+	firstIndex, firstValue := it.Index(), it.Value()
+	...
+}
+```
+
+```go
+for it.Begin(); it.Next(); {
+	...
+}
+```
+
 #### IteratorWithKey
 
-A [iterator](#iterator) whose elements are referenced by a key. Typical usage:
+An [iterator](#iterator) whose elements are referenced by a key.
 
+Typical usage:
 ```go
-it := map.Iterator()
+it := tree.Iterator()
 for it.Next() {
 	key, value := it.Key(), it.Value()
     ...
 }
 ```
 
+Other usages:
+```go
+if it.First() {
+	firstKey, firstValue := it.Key(), it.Value()
+	...
+}
+```
+
+```go
+for it.Begin(); it.Next(); {
+	...
+}
+```
+
 #### ReverseIteratorWithIndex
 
-A [iterator](#iterator) whose elements are referenced by an index. Typical usage:
+An [iterator](#iterator) whose elements are referenced by an index. Provides all functions as [IteratorWithIndex](#iteratorwithindex), but can also be used for reverse iteration.
 
+Typical usage of iteration in reverse:
 ```go
 it := list.Iterator()
-for it.Next() { /* Move to end */ }
+for it.End(); it.Prev(); {
-for it.Prev() {
 	index, value := it.Index(), it.Value()
     ...
 }
 ```
 
+Other usages:
+```go
+if it.Last() {
+	lastIndex, lastValue := it.Index(), it.Value()
+	...
+}
+```
+
 #### ReverseIteratorWithKey
 
-A [iterator](#iterator) whose elements are referenced by a key. Typical usage:
+An [iterator](#iterator) whose elements are referenced by a key. Provides all functions as [IteratorWithKey](#iteratorwithkey), but can also be used for reverse iteration.
 
+Typical usage of iteration in reverse:
 ```go
-it := map.Iterator()
+it := tree.Iterator()
-for it.Next() { /* Move to end */ }
+for it.End(); it.Prev(); {
-for it.Prev() {
 	key, value := it.Key(), it.Value()
     ...
 }
 ```
 
+Other usages:
+```go
+if it.Last() {
+	lastKey, lastValue := it.Key(), it.Value()
+	...
+}
+```
+
 ### Enumerable
 
 Enumerable functions for ordered containers that implement [EnumerableWithIndex](#enumerablewithindex) or [EnumerableWithKey](#enumerablewithkey) interfaces.

examples/iteratorwithindex.go

@@ -24,7 +24,7 @@ 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 main
+package examples
 
 import (
 	"fmt"
@@ -32,24 +32,42 @@ import (
 )
 
 // IteratorWithIndexExample to demonstrate basic usage of IteratorWithIndex
-//func IteratorWithIndexExample() {
+func IteratorWithIndexExample() {
-func main() {
+	set := treeset.NewWithStringComparator()
-	set := treeset.NewWithIntComparator()
+	set.Add("a", "b", "c")
-	set.Add(1, 2, 3)
-
-	// Forward iteration
 	it := set.Iterator()
+
+	fmt.Print("\nForward iteration\n")
 	for it.Next() {
 		index, value := it.Index(), it.Value()
-		fmt.Println("Index: ", index, "Value: ", value)
+		fmt.Print("[", index, ":", value, "]") // [0:a][1:b][2:c]
+	}
+
+	fmt.Print("\nForward iteration (again)\n")
+	for it.Begin(); it.Next(); {
+		index, value := it.Index(), it.Value()
+		fmt.Print("[", index, ":", value, "]") // [0:a][1:b][2:c]
 	}
 
-	// Backward iteration (reverse)
+	fmt.Print("\nBackward iteration\n")
-	for it.Last(); ; {
+	for it.Prev() {
 		index, value := it.Index(), it.Value()
-		fmt.Println("Index: ", index, "Value: ", value)
+		fmt.Print("[", index, ":", value, "]") // [2:c][1:b][0:a]
-		if !it.Prev() {
-			break
 	}
+
+	fmt.Print("\nBackward iteration (again)\n")
+	for it.End(); it.Prev(); {
+		index, value := it.Index(), it.Value()
+		fmt.Print("[", index, ":", value, "]") // [2:c][1:b][0:a]
+	}
+
+	if it.First() {
+		fmt.Print("\nFirst index: ", it.Index()) // First index: 0
+		fmt.Print("\nFirst value: ", it.Value()) // First value: a
+	}
+
+	if it.Last() {
+		fmt.Print("\nLast index: ", it.Index()) // Last index: 3
+		fmt.Print("\nLast value: ", it.Value()) // Last value: c
 	}
 }

examples/iteratorwithkey.go

@@ -0,0 +1,75 @@
+/*
+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"
+	"github.com/emirpasic/gods/maps/treemap"
+)
+
+// IteratorWithKeyExample to demonstrate basic usage of IteratorWithKey
+func IteratorWithKeyExample() {
+	m := treemap.NewWithIntComparator()
+	m.Put(1, "a")
+	m.Put(2, "b")
+	m.Put(3, "a")
+	it := m.Iterator()
+
+	fmt.Print("\nForward iteration\n")
+	for it.Next() {
+		key, value := it.Key(), it.Value()
+		fmt.Print("[", key, ":", value, "]") // [0:a][1:b][2:c]
+	}
+
+	fmt.Print("\nForward iteration (again)\n")
+	for it.Begin(); it.Next(); {
+		key, value := it.Key(), it.Value()
+		fmt.Print("[", key, ":", value, "]") // [0:a][1:b][2:c]
+	}
+
+	fmt.Print("\nBackward iteration\n")
+	for it.Prev() {
+		key, value := it.Key(), it.Value()
+		fmt.Print("[", key, ":", value, "]") // [2:c][1:b][0:a]
+	}
+
+	fmt.Print("\nBackward iteration (again)\n")
+	for it.End(); it.Prev(); {
+		key, value := it.Key(), it.Value()
+		fmt.Print("[", key, ":", value, "]") // [2:c][1:b][0:a]
+	}
+
+	if it.First() {
+		fmt.Print("\nFirst key: ", it.Key())     // First key: 0
+		fmt.Print("\nFirst value: ", it.Value()) // First value: a
+	}
+
+	if it.Last() {
+		fmt.Print("\nLast key: ", it.Key())     // Last key: 3
+		fmt.Print("\nLast value: ", it.Value()) // Last value: c
+	}
+}