github.com/shogo82148/std@v1.22.1-0.20240327122250-4e474527810c/container/ring/ring.go (about)

     1  // Copyright 2009 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package ring implements operations on circular lists.
     6  package ring
     7  
     8  // A Ring is an element of a circular list, or ring.
     9  // Rings do not have a beginning or end; a pointer to any ring element
    10  // serves as reference to the entire ring. Empty rings are represented
    11  // as nil Ring pointers. The zero value for a Ring is a one-element
    12  // ring with a nil Value.
    13  type Ring struct {
    14  	next, prev *Ring
    15  	Value      any
    16  }
    17  
    18  // Next returns the next ring element. r must not be empty.
    19  func (r *Ring) Next() *Ring
    20  
    21  // Prev returns the previous ring element. r must not be empty.
    22  func (r *Ring) Prev() *Ring
    23  
    24  // Move moves n % r.Len() elements backward (n < 0) or forward (n >= 0)
    25  // in the ring and returns that ring element. r must not be empty.
    26  func (r *Ring) Move(n int) *Ring
    27  
    28  // New creates a ring of n elements.
    29  func New(n int) *Ring
    30  
    31  // Link connects ring r with ring s such that r.Next()
    32  // becomes s and returns the original value for r.Next().
    33  // r must not be empty.
    34  //
    35  // If r and s point to the same ring, linking
    36  // them removes the elements between r and s from the ring.
    37  // The removed elements form a subring and the result is a
    38  // reference to that subring (if no elements were removed,
    39  // the result is still the original value for r.Next(),
    40  // and not nil).
    41  //
    42  // If r and s point to different rings, linking
    43  // them creates a single ring with the elements of s inserted
    44  // after r. The result points to the element following the
    45  // last element of s after insertion.
    46  func (r *Ring) Link(s *Ring) *Ring
    47  
    48  // Unlink removes n % r.Len() elements from the ring r, starting
    49  // at r.Next(). If n % r.Len() == 0, r remains unchanged.
    50  // The result is the removed subring. r must not be empty.
    51  func (r *Ring) Unlink(n int) *Ring
    52  
    53  // Len computes the number of elements in ring r.
    54  // It executes in time proportional to the number of elements.
    55  func (r *Ring) Len() int
    56  
    57  // Do calls function f on each element of the ring, in forward order.
    58  // The behavior of Do is undefined if f changes *r.
    59  func (r *Ring) Do(f func(any))