Add Doubly Linked List and other generics (#20)

Author: Dean Karn

README.md

@@ -1,6 +1,6 @@
 # pkg
 
-![Project status](https://img.shields.io/badge/version-5.11.0-green.svg)
+![Project status](https://img.shields.io/badge/version-5.12.0-green.svg)
 [![Build Status](https://travis-ci.org/go-playground/pkg.svg?branch=master)](https://travis-ci.org/go-playground/pkg)
 [![Coverage Status](https://coveralls.io/repos/github/go-playground/pkg/badge.svg?branch=master)](https://coveralls.io/github/go-playground/pkg?branch=master)
 [![GoDoc](https://godoc.org/github.com/go-playground/pkg?status.svg)](https://pkg.go.dev/mod/github.com/go-playground/pkg/v5)
@@ -16,6 +16,19 @@ This is a place to put common reusable code that is not quite a library but exte
 
 `go get -u github.com/go-playground/pkg/v5`
 
+
+## Highlights
+- Generic Doubly Linked List.
+- Result & Option types
+- Generic Mutex and RWMutex.
+- Bytes helper placeholders units eg. MB, MiB, GB, ...
+- Detachable context.
+- Error retryable helper functions.
+- Proper RFC3339Nano definition.
+- unsafe []byte->string & string->[]byte helper functions.
+- HTTP helper functions and constant placeholders.
+- And much, much more.
+
 ## How to Contribute
 
 Make a pull request... can't guarantee it will be added, going to strictly vet what goes in.

constraints/constraints.go

@@ -0,0 +1,34 @@
+//go:build go1.18
+// +build go1.18
+
+package constraintsext
+
+// Number represents any non-complex number eg. Integer and Float.
+type Number interface {
+	Integer | Float
+}
+
+// Integer represents any integer type both signed and unsigned.
+type Integer interface {
+	Signed | Unsigned
+}
+
+// Float represents any float type.
+type Float interface {
+	~float32 | ~float64
+}
+
+// Signed represents any signed integer.
+type Signed interface {
+	~int | ~int8 | ~int16 | ~int32 | ~int64
+}
+
+// Unsigned represents any unsigned integer.
+type Unsigned interface {
+	~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr
+}
+
+// Complex represents any complex number type.
+type Complex interface {
+	~complex64 | ~complex128
+}

container/list/doubly_linked.go

@@ -0,0 +1,249 @@
+//go:build go1.18
+// +build go1.18
+
+package listext
+
+// Node is an element of the doubly linked list.
+type Node[V any] struct {
+	next, prev *Node[V]
+	value      V
+}
+
+// Value returns the underlying nodes value.
+func (n *Node[V]) Value() V {
+	return n.value
+}
+
+// Next returns the nodes next value or nil if it is at the tail.
+func (n *Node[V]) Next() *Node[V] {
+	return n.next
+}
+
+// Prev returns the nodes previous value or nil if it is at the head.
+func (n *Node[V]) Prev() *Node[V] {
+	return n.prev
+}
+
+// DoublyLinkedList is a doubly linked list
+type DoublyLinkedList[V any] struct {
+	head, tail *Node[V]
+	len        int
+}
+
+// NewDoublyLinked creates a DoublyLinkedList for use.
+func NewDoublyLinked[V any]() *DoublyLinkedList[V] {
+	return new(DoublyLinkedList[V])
+}
+
+// PushFront adds an element first in the list.
+func (d *DoublyLinkedList[V]) PushFront(v V) *Node[V] {
+	node := &Node[V]{
+		value: v,
+	}
+	d.pushFront(node)
+	return d.head
+}
+
+func (d *DoublyLinkedList[V]) pushFront(node *Node[V]) {
+	node.next = d.head
+	node.prev = nil
+
+	if d.head == nil {
+		d.tail = node
+	} else {
+		d.head.prev = node
+	}
+	d.head = node
+	d.len++
+}
+
+// PopFront removes the first element and returns it or nil.
+func (d *DoublyLinkedList[V]) PopFront() *Node[V] {
+	if d.IsEmpty() {
+		return nil
+	}
+
+	node := d.head
+	d.head = node.next
+	if d.head == nil {
+		d.tail = nil
+	} else {
+		d.head.prev = nil
+	}
+	d.len--
+	// ensure no leakage
+	node.next, node.prev = nil, nil
+	return node
+}
+
+// PushBack appends an element to the back of a list.
+func (d *DoublyLinkedList[V]) PushBack(v V) *Node[V] {
+	node := &Node[V]{
+		value: v,
+	}
+	d.pushBack(node)
+	return d.tail
+}
+
+func (d *DoublyLinkedList[V]) pushBack(node *Node[V]) {
+	node.prev = d.tail
+	node.next = nil
+
+	if d.tail == nil {
+		d.head = node
+	} else {
+		d.tail.next = node
+	}
+	d.tail = node
+	d.len++
+}
+
+// PushAfter pushes the supplied value after the supplied node.
+//
+// The supplied node must be attached to the current list otherwise undefined behaviour could occur.
+func (d *DoublyLinkedList[V]) PushAfter(node *Node[V], v V) *Node[V] {
+	newNode := &Node[V]{
+		value: v,
+	}
+	d.MoveAfter(node, newNode)
+	return newNode
+}
+
+// MoveAfter moves the `moving` node after the supplied `node`.
+//
+// The supplied `node` must be attached to the current list and the `moving` node must either be attached to the
+// current list or not attached to any other otherwise undefined behaviour could occur.
+func (d *DoublyLinkedList[V]) MoveAfter(node *Node[V], moving *Node[V]) {
+	// first detach node were moving after, in case it was already attached somewhere else in the list.
+	d.Remove(moving)
+	next := node.next
+
+	// no next means node == d.tail
+	if next == nil {
+		d.pushBack(moving)
+	} else {
+		node.next = moving
+		moving.prev = node
+		moving.next = next
+		next.prev = moving
+		d.len++
+	}
+}
+
+// PushBefore pushes the supplied value before the supplied node.
+//
+// The supplied node must be attached to the current list otherwise undefined behaviour could occur.
+func (d *DoublyLinkedList[V]) PushBefore(node *Node[V], v V) *Node[V] {
+	newNode := &Node[V]{
+		value: v,
+	}
+	d.MoveBefore(node, newNode)
+	return newNode
+}
+
+// MoveBefore moves the `moving` node before the supplied `node`.
+//
+// The supplied `node` must be attached to the current list and the `moving` node must either be attached to the
+// current list or not attached to any other otherwise undefined behaviour could occur.
+func (d *DoublyLinkedList[V]) MoveBefore(node *Node[V], moving *Node[V]) {
+	// first detach node were moving after, in case it was already attached somewhere else in the list.
+	d.Remove(moving)
+	prev := node.prev
+
+	// no prev means node == d.head
+	if prev == nil {
+		d.pushFront(moving)
+	} else {
+		node.prev = moving
+		moving.next = node
+		moving.prev = prev
+		prev.next = moving
+		d.len++
+	}
+}
+
+// PopBack removes the last element from a list and returns it or nil.
+func (d *DoublyLinkedList[V]) PopBack() *Node[V] {
+	if d.IsEmpty() {
+		return nil
+	}
+
+	node := d.tail
+	d.tail = node.prev
+
+	if d.tail == nil {
+		d.head = nil
+	} else {
+		d.tail.next = nil
+	}
+	d.len--
+	// ensure no leakage
+	node.next, node.prev = nil, nil
+	return node
+}
+
+// Front returns the front/head element for use without removing it or nil list is empty.
+func (d *DoublyLinkedList[V]) Front() *Node[V] {
+	return d.head
+}
+
+// Back returns the end/tail element for use without removing it or nil list is empty.
+func (d *DoublyLinkedList[V]) Back() *Node[V] {
+	return d.tail
+}
+
+// Remove removes the provided element from the Linked List.
+func (d *DoublyLinkedList[V]) Remove(node *Node[V]) {
+	if node.prev == nil && node.next == nil {
+		// is a detached node, early exit
+		return
+	}
+
+	if node.prev == nil {
+		// is head node
+		_ = d.PopFront()
+	} else if node.next == nil {
+		// is tail node
+		_ = d.PopBack()
+	} else {
+		// is both head and tail nodes, must remap
+		node.next.prev = node.prev
+		node.prev.next = node.next
+		// ensure no leakage
+		node.next, node.prev = nil, nil
+		d.len--
+	}
+}
+
+// MoveToFront moves the provided node to the front/head.
+func (d *DoublyLinkedList[V]) MoveToFront(node *Node[V]) {
+	d.Remove(node)
+	d.pushFront(node)
+}
+
+// MoveToBack moves the provided node to the end/tail.
+func (d *DoublyLinkedList[V]) MoveToBack(node *Node[V]) {
+	d.Remove(node)
+	d.pushBack(node)
+}
+
+// IsEmpty returns true if the list is empty.
+func (d *DoublyLinkedList[V]) IsEmpty() bool {
+	return d.len == 0
+}
+
+// Len returns length of the Linked List.
+func (d *DoublyLinkedList[V]) Len() int {
+	return d.len
+}
+
+// Clear removes all elements from the Linked List.
+func (d *DoublyLinkedList[V]) Clear() {
+	// must loop and clean up references to each other.
+	for {
+		if d.PopBack() == nil {
+			break
+		}
+	}
+	d.head, d.tail, d.len = nil, nil, 0
+}