go.charczuk.com@v0.0.0-20240327042549-bc490516bd1a/sdk/collections/linked_list.go

/*

Copyright (c) 2023 - Present. Will Charczuk. All rights reserved.
Use of this source code is governed by a MIT license that can be found in the LICENSE file at the root of the repository.

*/

package collections

// LinkedList is an implementation of a fifo buffer using nodes and poitners.
// Remarks; it is not threadsafe. It is constant(ish) time in all ops.
type LinkedList[T any] struct {
	// head is the "first" element in the list
	head *LinkedListNode[T]
	// tail is the "last" element in the list
	tail *LinkedListNode[T]
	// len is the overall length of the list
	len int
}

// Len returns the length of the list in constant time.
func (l *LinkedList[T]) Len() int {
	return l.len
}

// PushBack adds a new value to the front of the list.
func (l *LinkedList[T]) PushFront(value T) *LinkedListNode[T] {
	item := &LinkedListNode[T]{Value: value}
	l.len++
	if l.head == nil {
		l.head = item
		l.tail = item
		return item
	}

	l.head.Previous = item
	item.Next = l.head
	item.Previous = nil
	l.head = item
	return item
}

// Push appends a node to the end, or tail, of the list.
func (l *LinkedList[T]) Push(value T) *LinkedListNode[T] {
	item := &LinkedListNode[T]{
		Value: value,
	}

	l.len++
	if l.head == nil {
		l.head = item
		l.tail = item
		return item
	}

	l.tail.Next = item
	item.Previous = l.tail
	item.Next = nil
	l.tail = item
	return item
}

// Pop removes the head element from the list.
func (l *LinkedList[T]) Pop() (out T, ok bool) {
	if l.head == nil {
		return
	}

	out = l.head.Value
	ok = true

	l.len--
	if l.head == l.tail {
		l.head = nil
		l.tail = nil
		return
	}

	next := l.head.Next
	next.Previous = nil
	l.head = next
	return
}

// PopBack removes the last, or tail, element of the list.
func (l *LinkedList[T]) PopBack() (out T, ok bool) {
	if l.tail == nil {
		return
	}

	out = l.tail.Value
	ok = true

	l.len--
	if l.tail == l.head {
		l.head = nil
		l.tail = nil
		return
	}

	previous := l.tail.Previous
	previous.Next = nil
	l.tail = previous
	return
}

// PopAll removes all the elements, returning a slice.
func (l *LinkedList[T]) PopAll() (output []T) {
	ptr := l.head
	for ptr != nil {
		output = append(output, ptr.Value)
		ptr = ptr.Next
	}
	l.head = nil
	l.tail = nil
	l.len = 0
	return
}

// Peek returns the first element of the list but does not remove it.
func (q *LinkedList[T]) Peek() (out T, ok bool) {
	if q.head == nil {
		return
	}
	out = q.head.Value
	ok = true
	return
}

// PeekBack returns the last element of the list.
func (q *LinkedList[T]) PeekBack() (out T, ok bool) {
	if q.tail == nil {
		return
	}
	out = q.tail.Value
	ok = true
	return
}

// Clear clears the linked list.
func (l *LinkedList[T]) Clear() {
	l.tail = nil
	l.head = nil
	l.len = 0
}

// Each calls the consumer for each element of the linked list.
func (q *LinkedList[T]) Each(consumer func(value T)) {
	if q.head == nil {
		return
	}

	nodePtr := q.head
	for nodePtr != nil {
		consumer(nodePtr.Value)
		nodePtr = nodePtr.Next
	}
}

func (l *LinkedList[T]) Remove(i *LinkedListNode[T]) {
	l.len--

	// three possibilities
	// - i is both the head and the tail
	// 		- nil out both
	// - i is the head
	// 		- set the head to i's next
	// - i is the tail
	//		- set the tail to i's previous
	// - i is neither
	//		- if i has a next, set its previous to i's previous
	//		- if i has a previous, set its previous to i's next

	if l.head == i && l.tail == i {
		l.head = nil
		l.tail = nil
		return
	}
	if l.head == i {
		l.head = i.Next
		return
	}
	if l.tail == i {
		l.tail = i.Previous
		return
	}

	next := i.Next
	if next != nil {
		next.Previous = i.Previous
	}
	previous := i.Previous
	if previous != nil {
		previous.Next = i.Next
	}
}

// LinkedListNode is a linked list node.
type LinkedListNode[T any] struct {
	// Value holds the value of the node.
	Value T
	// Next points towards the tail.
	Next *LinkedListNode[T]
	// Previous points towards the head.
	Previous *LinkedListNode[T]
}