add ExampleIterator and ExampleIterator_SeekGE

Add examples of basic iteration and using `Iterator.SeekGE`.

Fixes cockroachdb#1112

example_test.go

@@ -35,50 +35,3 @@ func Example() {
 	// Output:
 	// hello world
 }
-
-func Example_prefixiteration() {
-	db, err := pebble.Open("", &pebble.Options{FS: vfs.NewMem()})
-	if err != nil {
-		log.Fatal(err)
-	}
-
-	keyUpperBound := func(b []byte) []byte {
-		end := make([]byte, len(b))
-		copy(end, b)
-		for i := len(end) - 1; i >= 0; i-- {
-			end[i] = end[i] + 1
-			if end[i] != 0 {
-				return end[:i+1]
-			}
-		}
-		return nil // no upper-bound
-	}
-
-	prefixIterOptions := func(prefix []byte) *pebble.IterOptions {
-		return &pebble.IterOptions{
-			LowerBound: prefix,
-			UpperBound: keyUpperBound(prefix),
-		}
-	}
-
-	keys := []string{"hello", "world", "hello world"}
-	for _, key := range keys {
-		if err := db.Set([]byte(key), nil, pebble.Sync); err != nil {
-			log.Fatal(err)
-		}
-	}
-
-	iter := db.NewIter(prefixIterOptions([]byte("hello")))
-	for iter.First(); iter.Valid(); iter.Next() {
-		fmt.Printf("%s\n", iter.Key())
-	}
-	if err := iter.Close(); err != nil {
-		log.Fatal(err)
-	}
-	if err := db.Close(); err != nil {
-		log.Fatal(err)
-	}
-	// Output:
-	// hello
-	// hello world
-}

iterator.go

@@ -658,7 +658,7 @@ func (i *Iterator) SeekGEWithLimit(key []byte, limit []byte) IterValidityState {
 //    // Only keys beginning with "prefix" will be visited.
 //  }
 //
-// See Example_prefixiteration for a working example.
+// See ExampleIterator_SeekPrefixGE for a working example.
 func (i *Iterator) SeekPrefixGE(key []byte) bool {
 	lastPositioningOp := i.lastPositioningOp
 	// Set it to unknown, since this operation may not succeed, in which case

iterator_example_test.go

@@ -0,0 +1,124 @@
+// Copyright 2021 The LevelDB-Go and Pebble Authors. All rights reserved. Use
+// of this source code is governed by a BSD-style license that can be found in
+// the LICENSE file.
+
+package pebble_test
+
+import (
+	"fmt"
+	"log"
+
+	"github.com/cockroachdb/pebble"
+	"github.com/cockroachdb/pebble/vfs"
+)
+
+func ExampleIterator() {
+	db, err := pebble.Open("", &pebble.Options{FS: vfs.NewMem()})
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	keys := []string{"hello", "world", "hello world"}
+	for _, key := range keys {
+		if err := db.Set([]byte(key), nil, pebble.Sync); err != nil {
+			log.Fatal(err)
+		}
+	}
+
+	iter := db.NewIter(nil)
+	for iter.First(); iter.Valid(); iter.Next() {
+		fmt.Printf("%s\n", iter.Key())
+	}
+	if err := iter.Close(); err != nil {
+		log.Fatal(err)
+	}
+	if err := db.Close(); err != nil {
+		log.Fatal(err)
+	}
+	// Output:
+	// hello
+	// hello world
+	// world
+}
+
+func ExampleIterator_prefixIteration() {
+	db, err := pebble.Open("", &pebble.Options{FS: vfs.NewMem()})
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	keyUpperBound := func(b []byte) []byte {
+		end := make([]byte, len(b))
+		copy(end, b)
+		for i := len(end) - 1; i >= 0; i-- {
+			end[i] = end[i] + 1
+			if end[i] != 0 {
+				return end[:i+1]
+			}
+		}
+		return nil // no upper-bound
+	}
+
+	prefixIterOptions := func(prefix []byte) *pebble.IterOptions {
+		return &pebble.IterOptions{
+			LowerBound: prefix,
+			UpperBound: keyUpperBound(prefix),
+		}
+	}
+
+	keys := []string{"hello", "world", "hello world"}
+	for _, key := range keys {
+		if err := db.Set([]byte(key), nil, pebble.Sync); err != nil {
+			log.Fatal(err)
+		}
+	}
+
+	iter := db.NewIter(prefixIterOptions([]byte("hello")))
+	for iter.First(); iter.Valid(); iter.Next() {
+		fmt.Printf("%s\n", iter.Key())
+	}
+	if err := iter.Close(); err != nil {
+		log.Fatal(err)
+	}
+	if err := db.Close(); err != nil {
+		log.Fatal(err)
+	}
+	// Output:
+	// hello
+	// hello world
+}
+
+func ExampleIterator_SeekGE() {
+	db, err := pebble.Open("", &pebble.Options{FS: vfs.NewMem()})
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	keys := []string{"hello", "world", "hello world"}
+	for _, key := range keys {
+		if err := db.Set([]byte(key), nil, pebble.Sync); err != nil {
+			log.Fatal(err)
+		}
+	}
+
+	iter := db.NewIter(nil)
+	if iter.SeekGE([]byte("a")); iter.Valid() {
+		fmt.Printf("%s\n", iter.Key())
+	}
+	if iter.SeekGE([]byte("hello w")); iter.Valid() {
+		fmt.Printf("%s\n", iter.Key())
+	}
+	if iter.SeekGE([]byte("w")); iter.Valid() {
+		fmt.Printf("%s\n", iter.Key())
+	}
+	if err := iter.Close(); err != nil {
+		log.Fatal(err)
+	}
+	if err := db.Close(); err != nil {
+		log.Fatal(err)
+	}
+	// Output:
+	// hello
+	// hello world
+	// world
+}