github.com/shogo82148/std@v1.22.1-0.20240327122250-4e474527810c/container/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):
     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 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
    22  
    23  	// The list to which this element belongs.
    24  	list *List
    25  
    26  	// The value stored with this element.
    27  	Value any
    28  }
    29  
    30  // Next returns the next list element or nil.
    31  func (e *Element) Next() *Element
    32  
    33  // Prev returns the previous list element or nil.
    34  func (e *Element) Prev() *Element
    35  
    36  // List represents a doubly linked list.
    37  // The zero value for List is an empty list ready to use.
    38  type List struct {
    39  	root Element
    40  	len  int
    41  }
    42  
    43  // Init initializes or clears list l.
    44  func (l *List) Init() *List
    45  
    46  // New returns an initialized list.
    47  func New() *List
    48  
    49  // Len returns the number of elements of list l.
    50  // The complexity is O(1).
    51  func (l *List) Len() int
    52  
    53  // Front returns the first element of list l or nil if the list is empty.
    54  func (l *List) Front() *Element
    55  
    56  // Back returns the last element of list l or nil if the list is empty.
    57  func (l *List) Back() *Element
    58  
    59  // Remove removes e from l if e is an element of list l.
    60  // It returns the element value e.Value.
    61  // The element must not be nil.
    62  func (l *List) Remove(e *Element) any
    63  
    64  // PushFront inserts a new element e with value v at the front of list l and returns e.
    65  func (l *List) PushFront(v any) *Element
    66  
    67  // PushBack inserts a new element e with value v at the back of list l and returns e.
    68  func (l *List) PushBack(v any) *Element
    69  
    70  // InsertBefore inserts a new element e with value v immediately before mark and returns e.
    71  // If mark is not an element of l, the list is not modified.
    72  // The mark must not be nil.
    73  func (l *List) InsertBefore(v any, mark *Element) *Element
    74  
    75  // InsertAfter inserts a new element e with value v immediately after mark and returns e.
    76  // If mark is not an element of l, the list is not modified.
    77  // The mark must not be nil.
    78  func (l *List) InsertAfter(v any, mark *Element) *Element
    79  
    80  // MoveToFront moves element e to the front of list l.
    81  // If e is not an element of l, the list is not modified.
    82  // The element must not be nil.
    83  func (l *List) MoveToFront(e *Element)
    84  
    85  // MoveToBack moves element e to the back of list l.
    86  // If e is not an element of l, the list is not modified.
    87  // The element must not be nil.
    88  func (l *List) MoveToBack(e *Element)
    89  
    90  // MoveBefore moves element e to its new position before mark.
    91  // If e or mark is not an element of l, or e == mark, the list is not modified.
    92  // The element and mark must not be nil.
    93  func (l *List) MoveBefore(e, mark *Element)
    94  
    95  // MoveAfter moves element e to its new position after mark.
    96  // If e or mark is not an element of l, or e == mark, the list is not modified.
    97  // The element and mark must not be nil.
    98  func (l *List) MoveAfter(e, mark *Element)
    99  
   100  // PushBackList inserts a copy of another list at the back of list l.
   101  // The lists l and other may be the same. They must not be nil.
   102  func (l *List) PushBackList(other *List)
   103  
   104  // PushFrontList inserts a copy of another list at the front of list l.
   105  // The lists l and other may be the same. They must not be nil.
   106  func (l *List) PushFrontList(other *List)