ring

Documentation

Overview

Package ring implements a doubly-linked circular chain of data items, called a "ring".

Index

• type Ring
  • func New[T any](n int) *Ring[T]
  • func Of[T any](vs ...T) *Ring[T]
  • func (r *Ring[T]) At(n int) *Ring[T]
  • func (r *Ring[T]) Each(f func(v T) bool)
  • func (r *Ring[T]) IsEmpty() bool
  • func (r *Ring[T]) Join(s *Ring[T]) *Ring[T]
  • func (r *Ring[T]) Len() int
  • func (r *Ring[T]) Next() *Ring[T]
  • func (r *Ring[T]) Peek(n int) (T, bool)
  • func (r *Ring[T]) Pop() *Ring[T]
  • func (r *Ring[T]) Prev() *Ring[T]
  • func (r *Ring[T]) String() string

Examples

• Ring

Types

type Ring

type Ring[T any] struct {
	Value T
	// contains filtered or unexported fields
}

A Ring is a doubly-linked circular chain of data items. There is no designated beginning or end of a ring; each element is a valid entry point for the entire ring. A ring with no elements is represented as nil.

Example

package main

import (
	"fmt"

	"github.com/creachadair/mds/ring"
)

func main() {
	r := ring.Of("time", "flies", "like", "an", "arrow")

	// Set the value of an existing element.
	r.Value = "fruit"

	// Splice new elements into a ring.
	s := r.At(2).Join(ring.Of("a", "banana"))

	// Splice existing elements out of a ring.
	s.Prev().Join(r)

	// Iterate over the elements of a ring.
	for s := range r.Each {
		fmt.Println(s)
	}

}

Output:

fruit
flies
like
a
banana

func New

func New[T any](n int) *Ring[T]

New constructs a new ring with n zero-valued elements. If n ≤ 0, New returns nil.

func Of

func Of[T any](vs ...T) *Ring[T]

Of constructs a new ring containing the given elements.

func (*Ring[T]) At

func (r *Ring[T]) At(n int) *Ring[T]

At returns the entry at offset n from r. Negative values of n are permitted, and r.At(0) == r. If r == nil or the absolute value of n is greater than the length of the ring, At returns nil.

func (*Ring[T]) Each

func (r *Ring[T]) Each(f func(v T) bool)

Each is a range function that calls f with each value of r in circular order. If f returns false, Each returns immediately.

func (*Ring[T]) IsEmpty

func (r *Ring[T]) IsEmpty() bool

IsEmpty reports whether r is the empty ring.

func (*Ring[T]) Join

func (r *Ring[T]) Join(s *Ring[T]) *Ring[T]

Join splices ring s into a non-empty ring r. There are two cases:

If r and s belong to different rings, [r1 ... rn] and [s1 ... sm], the elements of s are spliced in after r1 and the resulting ring is:

[r1 s1 ... sm r2 ... rn]
    ^^^^^^^^^

In this case Join returns the ring [r2 ... rn r1 ... sm].

If r and s belong to the same ring, [r1 r2 ... ri s1 ... sm ... rn], then the loop of the ring from r2 ... ri is spliced out of r and the resulting ring is:

[r1 s1 ... sm ... rn]

In this case Join returns the ring [r2 ... ri] that was spliced out. This may be empty (nil) if there were no elements between r1 and s1.

func (*Ring[T]) Len

func (r *Ring[T]) Len() int

Len reports the number of elements in r. If r == nil, Len is 0. This operation takes time proportional to the size of the ring.

func (*Ring[T]) Next

func (r *Ring[T]) Next() *Ring[T]

Next returns the successor of r (which may be r itself). This will panic if r == nil.

func (*Ring[T]) Peek

func (r *Ring[T]) Peek(n int) (T, bool)

Peek reports whether the ring has a value at offset n from r, and if so returns its value. Negative values of n are permitted. If the absolute value of n is greater than the length of the ring, Peek reports a zero value.

func (*Ring[T]) Pop

func (r *Ring[T]) Pop() *Ring[T]

Pop detaches r from its ring, leaving it linked only to itself. It returns r to permit method chaining.

func (*Ring[T]) Prev

func (r *Ring[T]) Prev() *Ring[T]

Prev returns the predecessor of r (which may be r itself). This will panic if r == nil.

func (*Ring[T]) String

func (r *Ring[T]) String() string