container/ring: add examples for various Ring functions

Change-Id: I6b16cfcbe824f999c9b64df539deea567e327db7
Reviewed-on: https://go-review.googlesource.com/73090
Reviewed-by: Gabriel Aszalos <gabriel.aszalos@gmail.com>
Reviewed-by: Jason Wangsadinata <jwangsadinata@gmail.com>
Reviewed-by: Ian Lance Taylor <iant@golang.org>
Run-TryBot: Gabriel Aszalos <gabriel.aszalos@gmail.com>

src/container/ring/example_test.go

@@ -0,0 +1,174 @@
+// Copyright 2017 The Go 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 ring_test
+
+import (
+	"container/ring"
+	"fmt"
+)
+
+func ExampleRing_Len() {
+	// Create a new ring of size 4
+	r := ring.New(4)
+
+	// Print out its length
+	fmt.Println(r.Len())
+
+	// Output:
+	// 4
+}
+
+func ExampleRing_Next() {
+	// Create a new ring of size 5
+	r := ring.New(5)
+
+	// Initialize the ring with some integer values
+	for i := 0; i < r.Len(); i++ {
+		r.Value = i
+		r = r.Next()
+	}
+
+	// Iterate through the ring and print its contents
+	for j := 0; j < r.Len(); j++ {
+		fmt.Println(r.Value)
+		r = r.Next()
+	}
+
+	// Output:
+	// 0
+	// 1
+	// 2
+	// 3
+	// 4
+}
+
+func ExampleRing_Prev() {
+	// Create a new ring of size 5
+	r := ring.New(5)
+
+	// Initialize the ring with some integer values
+	for i := 0; i < r.Len(); i++ {
+		r.Value = i
+		r = r.Next()
+	}
+
+	// Iterate through the ring backwards and print its contents
+	for j := 0; j < r.Len(); j++ {
+		r = r.Prev()
+		fmt.Println(r.Value)
+	}
+
+	// Output:
+	// 4
+	// 3
+	// 2
+	// 1
+	// 0
+}
+
+func ExampleRing_Do() {
+	// Create a new ring of size 5
+	r := ring.New(5)
+
+	// Initialize the ring with some integer values
+	for i := 0; i < r.Len(); i++ {
+		r.Value = i
+		r = r.Next()
+	}
+
+	// Iterate through the ring and print its contents
+	r.Do(func(p interface{}) {
+		fmt.Println(p.(int))
+	})
+
+	// Output:
+	// 0
+	// 1
+	// 2
+	// 3
+	// 4
+}
+
+func ExampleRing_Move() {
+	// Create a new ring of size 5
+	r := ring.New(5)
+
+	// Initialize the ring with some integer values
+	for i := 0; i < r.Len(); i++ {
+		r.Value = i
+		r = r.Next()
+	}
+
+	// Move the pointer forward by three steps
+	r = r.Move(3)
+
+	// Iterate through the ring and print its contents
+	r.Do(func(p interface{}) {
+		fmt.Println(p.(int))
+	})
+
+	// Output:
+	// 3
+	// 4
+	// 0
+	// 1
+	// 2
+}
+
+func ExampleRing_Link() {
+	// Create two rings, r and s, of size 2
+	r := ring.New(2)
+	s := ring.New(2)
+
+	// Initialize r with 0s
+	for i := 0; i < r.Len(); i++ {
+		r.Value = 0
+		r = r.Next()
+	}
+
+	// Initialize s with 1s
+	for j := 0; j < s.Len(); j++ {
+		s.Value = 1
+		s = s.Next()
+	}
+
+	// Link ring r and ring s
+	rs := r.Link(s)
+
+	// Iterate through the combined ring and print its contents
+	rs.Do(func(p interface{}) {
+		fmt.Println(p.(int))
+	})
+
+	// Output:
+	// 0
+	// 0
+	// 1
+	// 1
+}
+
+func ExampleRing_Unlink() {
+	// Create a new ring of size 6
+	r := ring.New(6)
+
+	// Initialize the ring with some integer values
+	for i := 0; i < r.Len(); i++ {
+		r.Value = i
+		r = r.Next()
+	}
+
+	// Unlink three elements from r, starting from r.Next()
+	r.Unlink(3)
+
+	// Iterate through the remaining ring and print its contents
+	r.Do(func(p interface{}) {
+		fmt.Println(p.(int))
+	})
+
+	// Output:
+	// 0
+	// 4
+	// 5
+}