并发安全环-方法介绍 | GoFrame官网 - 类似PHP-Laravel,Java-SpringBoot的Go语言开发框架

版本：2.10.x(Latest)

以下常用方法列表，文档更新可能滞后于代码新特性，更多的方法及示例请参考代码文档：https://pkg.go.dev/github.com/gogf/gf/v2/container/gring

构造方法

`New`

说明：New 创建并返回 cap 元素的环形结构。可选参数 safe 指定是否在并发安全中使用此结构，默认情况下为 false。
格式：

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

示例：

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

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

    // Output:
}

`NewTRing`

提示

版本要求：v2.10.0

说明：NewTRing 创建并返回泛型环形结构。可选参数 safe 指定是否在并发安全中使用此结构，默认情况下为 false。
格式：

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

示例：

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:
}

基本方法

`Val`

说明：Val 返回当前位置的项值。
格式：

// 传统方式
Val() interface{}

// 泛型方式 (v2.10.0+)
Val() T

示例：

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
}

// 泛型方式
func ExampleTRing_Val() {
    r := gring.NewTRing[int](10)
    r.Set(100)
    fmt.Println("Val:", r.Val()) // 无需类型断言

    // Output:
    // Val: 100
}

`Len`

说明：Len 返回环的大小（已使用元素数量）。
格式：

Len() int

示例：

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`

说明：Cap 返回环的容量（最大元素数量）。
格式：

Cap() int

示例：

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
}

设置方法

`Set`

说明：Set 将值设置到当前位置的项。
格式：

// 传统方式
Set(value interface{}) *Ring

// 泛型方式 (v2.10.0+)
Set(value T) *TRing[T]

示例：

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
}

// 泛型方式
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`

说明：Put 将 value 设置到当前环的项，并将位置移到下一项。
格式：

// 传统方式
Put(value interface{}) *Ring

// 泛型方式 (v2.10.0+)
Put(value T) *TRing[T]

示例：

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
}

// 泛型方式
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`

说明：Move 在环中向后（n < 0）或向前（n >= 0）移动 n % r.Len() 个元素，并返回该环元素。r 不能为空。
格式：

// 传统方式
Move(n int) *Ring

// 泛型方式 (v2.10.0+)
Move(n int) *TRing[T]

示例：

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`

说明：Prev 返回上一个环元素。r 不能为空。
格式：

// 传统方式
Prev() *Ring

// 泛型方式 (v2.10.0+)
Prev() *TRing[T]

示例：

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`

说明：Next 返回下一个环元素。r 不能为空。
格式：

// 传统方式
Next() *Ring

// 泛型方式 (v2.10.0+)
Next() *TRing[T]

示例：

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`

说明：Link 连接环 r 与环 s，使得 r.Next() 变为 s 并返回 r.Next() 的原始值。r 不能为空。
- 如果 r 和 s 指向同一个环，则连接它们会从环中删除 r 和 s 之间的元素。删除的元素形成一个子环，结果是对该子环的引用（如果没有删除元素，则结果仍然是 r.Next() 的原始值，而不是 nil）。
- 如果 r 和 s 指向不同的环，则将它们连接起来会创建一个单环，其中 s 的元素插入到 r 之后。结果指向插入 s 的最后一个元素之后的元素。
格式：

// 传统方式
Link(s *Ring) *Ring

// 泛型方式 (v2.10.0+)
Link(s *TRing[T]) *TRing[T]

示例：

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`

说明：Unlink 从环 r 中删除 n % r.Len() 个元素，从 r.Next() 开始。如果 n % r.Len() == 0，则 r 保持不变。结果是删除的子环。r 不能为空。
格式：

// 传统方式
Unlink(n int) *Ring

// 泛型方式 (v2.10.0+)
Unlink(n int) *TRing[T]

示例：

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
}

遍历方法

`RLockIteratorNext`

说明：RLockIteratorNext 使用给定的回调函数 f 在 RWMutex.RLock 内向前迭代并锁定读取。如果 f 返回 true，则继续迭代；或者返回 false 停止。
格式：

// 传统方式
RLockIteratorNext(f func(value interface{}) bool)

// 泛型方式 (v2.10.0+)
RLockIteratorNext(f func(value T) bool)

示例：

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
}

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

    // 无需类型断言
    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`

说明：RLockIteratorPrev 使用给定的回调函数 f 在 RWMutex.RLock 内向后迭代并锁定读取。如果 f 返回 true，则继续迭代；或者返回 false 停止。
格式：

// 传统方式
RLockIteratorPrev(f func(value interface{}) bool)

// 泛型方式 (v2.10.0+)
RLockIteratorPrev(f func(value T) bool)

示例：

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
}

切片方法

`SliceNext`

说明：SliceNext 从当前位置开始向前返回所有项值的副本作为切片。
格式：

// 传统方式
SliceNext() []interface{}

// 泛型方式 (v2.10.0+)
SliceNext() []T

示例：

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]
}

// 泛型方式
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`

说明：SlicePrev 从当前位置开始向后返回所有项值的副本作为切片。
格式：

// 传统方式
SlicePrev() []interface{}

// 泛型方式 (v2.10.0+)
SlicePrev() []T

示例：

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]
}

// 泛型方式
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]
}

构造方法​

New​

NewTRing​

基本方法​

Val​

Len​

Cap​

设置方法​

Set​

Put​

移动方法​

Move​

Prev​

Next​

链接方法​

Link​

Unlink​

遍历方法​

RLockIteratorNext​

RLockIteratorPrev​

切片方法​

SliceNext​

SlicePrev​

构造方法

`New`

`NewTRing`

基本方法

`Val`

`Len`

`Cap`

设置方法

`Set`

`Put`

移动方法

`Move`

`Prev`

`Next`

链接方法

`Link`

`Unlink`

遍历方法

`RLockIteratorNext`

`RLockIteratorPrev`

切片方法

`SliceNext`

`SlicePrev`