github.com/sagernet/sing@v0.4.0-beta.19.0.20240518125136-f67a0988a636/common/x/list/list.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 list implements a doubly linked list. 6 // 7 // To iterate over a list (where l is a *List[T]): 8 // 9 // for e := l.Front(); e != nil; e = e.Next() { 10 // // do something with e.Value 11 // } 12 package list 13 14 // Element is an element of a linked list. 15 type Element[T any] struct { 16 // Next and previous pointers in the doubly-linked list of elements. 17 // To simplify the implementation, internally a list l is implemented 18 // as a ring, such that &l.root is both the next element of the last 19 // list element (l.Back()) and the previous element of the first list 20 // element (l.Front()). 21 next, prev *Element[T] 22 23 // The list to which this element belongs. 24 list *List[T] 25 26 // The value stored with this element. 27 Value T 28 } 29 30 // Next returns the next list element or nil. 31 func (e *Element[T]) Next() *Element[T] { 32 if p := e.next; e.list != nil && p != &e.list.root { 33 return p 34 } 35 return nil 36 } 37 38 // Prev returns the previous list element or nil. 39 func (e *Element[T]) Prev() *Element[T] { 40 if p := e.prev; e.list != nil && p != &e.list.root { 41 return p 42 } 43 return nil 44 } 45 46 // List represents a doubly linked list. 47 // The zero value for List is an empty list ready to use. 48 type List[T any] struct { 49 root Element[T] // sentinel list element, only &root, root.prev, and root.next are used 50 len int // current list length excluding (this) sentinel element 51 } 52 53 // Init initializes or clears list l. 54 func (l *List[T]) Init() *List[T] { 55 l.root.next = &l.root 56 l.root.prev = &l.root 57 l.len = 0 58 return l 59 } 60 61 // Len returns the number of elements of list l. 62 // The complexity is O(1). 63 func (l *List[T]) Len() int { return l.len } 64 65 // Front returns the first element of list l or nil if the list is empty. 66 func (l *List[T]) Front() *Element[T] { 67 if l.len == 0 { 68 return nil 69 } 70 return l.root.next 71 } 72 73 // Back returns the last element of list l or nil if the list is empty. 74 func (l *List[T]) Back() *Element[T] { 75 if l.len == 0 { 76 return nil 77 } 78 return l.root.prev 79 } 80 81 // lazyInit lazily initializes a zero List value. 82 func (l *List[T]) lazyInit() { 83 if l.root.next == nil { 84 l.Init() 85 } 86 } 87 88 // insert inserts e after at, increments l.len, and returns e. 89 func (l *List[T]) insert(e, at *Element[T]) *Element[T] { 90 e.prev = at 91 e.next = at.next 92 e.prev.next = e 93 e.next.prev = e 94 e.list = l 95 l.len++ 96 return e 97 } 98 99 // insertValue is a convenience wrapper for insert(&Element{Value: v}, at). 100 func (l *List[T]) insertValue(v any, at *Element[T]) *Element[T] { 101 e := new(Element[T]) 102 e.Value = v.(T) 103 return l.insert(e, at) 104 } 105 106 // remove removes e from its list, decrements l.len 107 func (l *List[T]) remove(e *Element[T]) { 108 e.prev.next = e.next 109 e.next.prev = e.prev 110 e.next = nil // avoid memory leaks 111 e.prev = nil // avoid memory leaks 112 e.list = nil 113 l.len-- 114 } 115 116 // move moves e to next to at. 117 func (l *List[T]) move(e, at *Element[T]) { 118 if e == at { 119 return 120 } 121 e.prev.next = e.next 122 e.next.prev = e.prev 123 124 e.prev = at 125 e.next = at.next 126 e.prev.next = e 127 e.next.prev = e 128 } 129 130 // Remove removes e from l if e is an element of list l. 131 // It returns the element value e.Value. 132 // The element must not be nil. 133 func (l *List[T]) Remove(e *Element[T]) T { 134 if e.list == l { 135 // if e.list == l, l must have been initialized when e was inserted 136 // in l or l == nil (e is a zero Element) and l.remove will crash 137 l.remove(e) 138 } 139 return e.Value 140 } 141 142 // PushFront inserts a new element e with value v at the front of list l and returns e. 143 func (l *List[T]) PushFront(v T) *Element[T] { 144 l.lazyInit() 145 return l.insertValue(v, &l.root) 146 } 147 148 // PushBack inserts a new element e with value v at the back of list l and returns e. 149 func (l *List[T]) PushBack(v T) *Element[T] { 150 l.lazyInit() 151 return l.insertValue(v, l.root.prev) 152 } 153 154 // InsertBefore inserts a new element e with value v immediately before mark and returns e. 155 // If mark is not an element of l, the list is not modified. 156 // The mark must not be nil. 157 func (l *List[T]) InsertBefore(v T, mark *Element[T]) *Element[T] { 158 if mark.list != l { 159 return nil 160 } 161 // see comment in List.Remove about initialization of l 162 return l.insertValue(v, mark.prev) 163 } 164 165 // InsertAfter inserts a new element e with value v immediately after mark and returns e. 166 // If mark is not an element of l, the list is not modified. 167 // The mark must not be nil. 168 func (l *List[T]) InsertAfter(v T, mark *Element[T]) *Element[T] { 169 if mark.list != l { 170 return nil 171 } 172 // see comment in List.Remove about initialization of l 173 return l.insertValue(v, mark) 174 } 175 176 // MoveToFront moves element e to the front of list l. 177 // If e is not an element of l, the list is not modified. 178 // The element must not be nil. 179 func (l *List[T]) MoveToFront(e *Element[T]) { 180 if e.list != l || l.root.next == e { 181 return 182 } 183 // see comment in List.Remove about initialization of l 184 l.move(e, &l.root) 185 } 186 187 // MoveToBack moves element e to the back of list l. 188 // If e is not an element of l, the list is not modified. 189 // The element must not be nil. 190 func (l *List[T]) MoveToBack(e *Element[T]) { 191 if e.list != l || l.root.prev == e { 192 return 193 } 194 // see comment in List.Remove about initialization of l 195 l.move(e, l.root.prev) 196 } 197 198 // MoveBefore moves element e to its new position before mark. 199 // If e or mark is not an element of l, or e == mark, the list is not modified. 200 // The element and mark must not be nil. 201 func (l *List[T]) MoveBefore(e, mark *Element[T]) { 202 if e.list != l || e == mark || mark.list != l { 203 return 204 } 205 l.move(e, mark.prev) 206 } 207 208 // MoveAfter moves element e to its new position after mark. 209 // If e or mark is not an element of l, or e == mark, the list is not modified. 210 // The element and mark must not be nil. 211 func (l *List[T]) MoveAfter(e, mark *Element[T]) { 212 if e.list != l || e == mark || mark.list != l { 213 return 214 } 215 l.move(e, mark) 216 } 217 218 // PushBackList inserts a copy of another list at the back of list l. 219 // The lists l and other may be the same. They must not be nil. 220 func (l *List[T]) PushBackList(other *List[T]) { 221 l.lazyInit() 222 for i, e := other.Len(), other.Front(); i > 0; i, e = i-1, e.Next() { 223 l.insertValue(e.Value, l.root.prev) 224 } 225 } 226 227 // PushFrontList inserts a copy of another list at the front of list l. 228 // The lists l and other may be the same. They must not be nil. 229 func (l *List[T]) PushFrontList(other *List[T]) { 230 l.lazyInit() 231 for i, e := other.Len(), other.Back(); i > 0; i, e = i-1, e.Prev() { 232 l.insertValue(e.Value, &l.root) 233 } 234 }