Concurrency-Safe Ring-Methods | GoFrame - A powerful framework for faster, easier, and more efficient project development

Version: 2.10.x(Latest)

The following list includes common methods. Documentation updates may lag behind code features. For more methods and examples, please refer to the code documentation: https://pkg.go.dev/github.com/gogf/gf/v2/container/gring

Constructor Methods

`New`

Description: New creates and returns a ring structure with cap elements. Optional parameter safe specifies whether to use this structure in concurrency-safe mode, defaults to false.
Format:

New(cap int, safe ...bool) *Ring

Example:

func ExampleNew() {
    // Non concurrent safety
    gring.New(10)

    // Concurrent safety
    gring.New(10, true)

    // Output:
}

`NewTRing`

tip

Version requirement: v2.10.0

Description: NewTRing creates and returns a generic ring structure. Optional parameter safe specifies whether to use this structure in concurrency-safe mode, defaults to false.
Format:

NewTRing[T any](cap int, safe ...bool) *TRing[T]

Example:

func ExampleNewTRing() {
    // Create a non-concurrent-safe ring with type int
    r1 := gring.NewTRing[int](10)
    
    // Create a concurrent-safe ring with type string
    r2 := gring.NewTRing[string](10, true)
    
    // Create a ring with custom type
    type User struct {
        ID   int
        Name string
    }
    r3 := gring.NewTRing[*User](10)

    // Output:
}

Basic Methods

`Val`

Description: Val returns the value of the item at the current position.
Format:

// Traditional approach
Val() interface{}

// Generic approach (v2.10.0+)
Val() T

Example:

func ExampleRing_Val() {
    r := gring.New(10)
    r.Set(1)
    fmt.Println("Val:", r.Val())

    r.Next().Set("GoFrame")
    fmt.Println("Val:", r.Val())

    // Output:
    // Val: 1
    // Val: GoFrame
}

// Generic approach
func ExampleTRing_Val() {
    r := gring.NewTRing[int](10)
    r.Set(100)
    fmt.Println("Val:", r.Val()) // No type assertion needed

    // Output:
    // Val: 100
}

`Len`

Description: Len returns the size of the ring (number of used elements).
Format:

Len() int

Example:

func ExampleRing_Len() {
    r1 := gring.New(10)
    for i := 0; i < 5; i++ {
        r1.Set(i).Next()
    }
    fmt.Println("Len:", r1.Len())

    r2 := gring.New(10, true)
    for i := 0; i < 10; i++ {
        r2.Set(i).Next()
    }
    fmt.Println("Len:", r2.Len())

    // Output:
    // Len: 5
    // Len: 10
}

`Cap`

Description: Cap returns the capacity of the ring (maximum number of elements).
Format:

Cap() int

Example:

func ExampleRing_Cap() {
    r1 := gring.New(10)
    for i := 0; i < 5; i++ {
        r1.Set(i).Next()
    }
    fmt.Println("Cap:", r1.Cap())

    r2 := gring.New(10, true)
    for i := 0; i < 10; i++ {
        r2.Set(i).Next()
    }
    fmt.Println("Cap:", r2.Cap())

    // Output:
    // Cap: 10
    // Cap: 10
}

Setter Methods

`Set`

Description: Set sets a value to the item at the current position.
Format:

// Traditional approach
Set(value interface{}) *Ring

// Generic approach (v2.10.0+)
Set(value T) *TRing[T]

Example:

func ExampleRing_Set() {
    r := gring.New(10)
    r.Set(1)
    fmt.Println("Val:", r.Val())

    r.Next().Set("GoFrame")
    fmt.Println("Val:", r.Val())

    // Output:
    // Val: 1
    // Val: GoFrame
}

// Generic approach
func ExampleTRing_Set() {
    r := gring.NewTRing[string](10)
    r.Set("Hello")
    fmt.Println("Val:", r.Val())

    r.Next().Set("World")
    fmt.Println("Val:", r.Val())

    // Output:
    // Val: Hello
    // Val: World
}

`Put`

Description: Put sets value to the current ring item and moves the position to the next item.
Format:

// Traditional approach
Put(value interface{}) *Ring

// Generic approach (v2.10.0+)
Put(value T) *TRing[T]

Example:

func ExampleRing_Put() {
    r := gring.New(10)
    r.Put(1)
    fmt.Println("Val:", r.Val())
    fmt.Println("Val:", r.Prev().Val())

    // Output:
    // Val: <nil>
    // Val: 1
}

// Generic approach
func ExampleTRing_Put() {
    r := gring.NewTRing[int](10)
    r.Put(100)
    fmt.Println("Val:", r.Val())
    fmt.Println("Val:", r.Prev().Val())

    // Output:
    // Val: 0
    // Val: 100
}

Move Methods

`Move`

Description: Move moves backward (n < 0) or forward (n >= 0) by n % r.Len() elements in the ring and returns that ring element. r must not be empty.
Format:

// Traditional approach
Move(n int) *Ring

// Generic approach (v2.10.0+)
Move(n int) *TRing[T]

Example:

func ExampleRing_Move() {
    r := gring.New(10)
    for i := 0; i < 10; i++ {
        r.Set(i).Next()
    }
    // ring at Pos 0
    fmt.Println("CurVal:", r.Val())

    r.Move(5)

    // ring at Pos 5
    fmt.Println("CurVal:", r.Val())

    // Output:
    // CurVal: 0
    // CurVal: 5
}

`Prev`

Description: Prev returns the previous ring element. r must not be empty.
Format:

// Traditional approach
Prev() *Ring

// Generic approach (v2.10.0+)
Prev() *TRing[T]

Example:

func ExampleRing_Prev() {
    r := gring.New(10)
    for i := 0; i < 5; i++ {
        r.Set(i).Next()
    }

    fmt.Println("Prev:", r.Prev().Val())
    fmt.Println("Prev:", r.Prev().Val())

    // Output:
    // Prev: 4
    // Prev: 3
}

`Next`

Description: Next returns the next ring element. r must not be empty.
Format:

// Traditional approach
Next() *Ring

// Generic approach (v2.10.0+)
Next() *TRing[T]

Example:

func ExampleRing_Next() {
    r := gring.New(10)
    for i := 5; i > 0; i-- {
        r.Set(i).Prev()
    }

    fmt.Println("Next:", r.Next().Val())
    fmt.Println("Next:", r.Next().Val())

    // Output:
    // Next: 1
    // Next: 2
}

Link Methods

`Link`

Description: Link connects ring r with ring s such that r.Next() becomes s and returns the original value of r.Next(). r must not be empty.
- If r and s point to the same ring, linking them removes the elements between r and s from the ring. The removed elements form a sub-ring, and the result is a reference to that sub-ring (if no elements were removed, the result is still the original value of r.Next(), not nil).
- If r and s point to different rings, linking them creates a single ring with the elements of s inserted after r. The result points to the element after the last element of s that was inserted.
Format:

// Traditional approach
Link(s *Ring) *Ring

// Generic approach (v2.10.0+)
Link(s *TRing[T]) *TRing[T]

Example:

func ExampleRing_Link() {
    r := gring.New(10)
    for i := 0; i < 5; i++ {
        r.Set(i).Next()
    }

    s := gring.New(10)
    for i := 0; i < 10; i++ {
        val := i + 5
        s.Set(val).Next()
    }

    r.Link(s) // Link Ring s to Ring r

    fmt.Println("Len:", r.Len())
    fmt.Println("Cap:", r.Cap())

    // Output:
    // Len: 15
    // Cap: 20
}

`Unlink`

Description: Unlink removes n % r.Len() elements from ring r, starting from r.Next(). If n % r.Len() == 0, r remains unchanged. The result is the removed sub-ring. r must not be empty.
Format:

// Traditional approach
Unlink(n int) *Ring

// Generic approach (v2.10.0+)
Unlink(n int) *TRing[T]

Example:

func ExampleRing_Unlink() {
    r := gring.New(10)
    for i := 0; i < 10; i++ {
        r.Set(i).Next()
    }

    fmt.Println("Before Unlink, Len:", r.Len())
    fmt.Println("Before Unlink, Cap:", r.Cap())

    r.Unlink(7)

    fmt.Println("After Unlink, Len:", r.Len())
    fmt.Println("After Unlink, Cap:", r.Cap())

    // Output:
    // Before Unlink, Len: 10
    // Before Unlink, Cap: 10
    // After Unlink, Len: 3
    // After Unlink, Cap: 3
}

Iterator Methods

`RLockIteratorNext`

Description: RLockIteratorNext iterates forward and locks for reading with RWMutex.RLock using the given callback function f. If f returns true, iteration continues; otherwise it stops when f returns false.
Format:

// Traditional approach
RLockIteratorNext(f func(value interface{}) bool)

// Generic approach (v2.10.0+)
RLockIteratorNext(f func(value T) bool)

Example:

func ExampleRing_RLockIteratorNext() {
    r := gring.New(10)
    for i := 0; i < 10; i++ {
        r.Set(i).Next()
    }

    r.RLockIteratorNext(func(value interface{}) bool {
        if value.(int) < 5 {
            fmt.Println("IteratorNext Success, Value:", value)
            return true
        }
        return false
    })

    // Output:
    // IteratorNext Success, Value: 0
    // IteratorNext Success, Value: 1
    // IteratorNext Success, Value: 2
    // IteratorNext Success, Value: 3
    // IteratorNext Success, Value: 4
}

// Generic approach
func ExampleTRing_RLockIteratorNext() {
    r := gring.NewTRing[int](10)
    for i := 0; i < 10; i++ {
        r.Set(i).Next()
    }

    // No type assertion needed
    r.RLockIteratorNext(func(value int) bool {
        if value < 5 {
            fmt.Println("IteratorNext Success, Value:", value)
            return true
        }
        return false
    })

    // Output:
    // IteratorNext Success, Value: 0
    // IteratorNext Success, Value: 1
    // IteratorNext Success, Value: 2
    // IteratorNext Success, Value: 3
    // IteratorNext Success, Value: 4
}

`RLockIteratorPrev`

Description: RLockIteratorPrev iterates backward and locks for reading with RWMutex.RLock using the given callback function f. If f returns true, iteration continues; otherwise it stops when f returns false.
Format:

// Traditional approach
RLockIteratorPrev(f func(value interface{}) bool)

// Generic approach (v2.10.0+)
RLockIteratorPrev(f func(value T) bool)

Example:

func ExampleRing_RLockIteratorPrev() {
    r := gring.New(10)
    for i := 0; i < 10; i++ {
        r.Set(i).Next()
    }

    // move r to pos 9
    r.Prev()

    r.RLockIteratorPrev(func(value interface{}) bool {
        if value.(int) >= 5 {
            fmt.Println("IteratorPrev Success, Value:", value)
            return true
        }
        return false
    })

    // Output:
    // IteratorPrev Success, Value: 9
    // IteratorPrev Success, Value: 8
    // IteratorPrev Success, Value: 7
    // IteratorPrev Success, Value: 6
    // IteratorPrev Success, Value: 5
}

Slice Methods

`SliceNext`

Description: SliceNext returns a copy of all item values as a slice starting from the current position moving forward.
Format:

// Traditional approach
SliceNext() []interface{}

// Generic approach (v2.10.0+)
SliceNext() []T

Example:

func ExampleRing_SliceNext() {
    r := gring.New(10)
    for i := 0; i < 10; i++ {
        r.Set(i).Next()
    }

    fmt.Println(r.SliceNext())

    // Output:
    // [0 1 2 3 4 5 6 7 8 9]
}

// Generic approach
func ExampleTRing_SliceNext() {
    r := gring.NewTRing[string](5)
    words := []string{"Go", "Frame", "is", "awesome", "!"}
    
    for _, word := range words {
        r.Put(word)
    }
    
    r.Move(-5)
    fmt.Println(r.SliceNext())

    // Output:
    // [Go Frame is awesome !]
}

`SlicePrev`

Description: SlicePrev returns a copy of all item values as a slice starting from the current position moving backward.
Format:

// Traditional approach
SlicePrev() []interface{}

// Generic approach (v2.10.0+)
SlicePrev() []T

Example:

func ExampleRing_SlicePrev() {
    r := gring.New(10)
    for i := 0; i < 10; i++ {
        r.Set(i).Next()
    }

    fmt.Println(r.SlicePrev())

    // Output:
    // [0 9 8 7 6 5 4 3 2 1]
}

// Generic approach
func ExampleTRing_SlicePrev() {
    r := gring.NewTRing[int](10)
    for i := 0; i < 10; i++ {
        r.Set(i).Next()
    }

    fmt.Println(r.SlicePrev())

    // Output:
    // [0 9 8 7 6 5 4 3 2 1]
}

Constructor Methods​

New​

NewTRing​

Basic Methods​

Val​

Len​

Cap​

Setter Methods​

Set​

Put​

Move Methods​

Move​

Prev​

Next​

Link Methods​

Link​

Unlink​

Iterator Methods​

RLockIteratorNext​

RLockIteratorPrev​

Slice Methods​

SliceNext​

SlicePrev​