Add #unshift, #pop and #pop? to Crystal::PointerLinkedList (#16287)

Adds methods to **add and remove from any end of the list**, while the current implementation only allows a FIFO behavior (add to tail, remove from head).

For example in the [fdlock pull request](https://github.com/crystal-lang/crystal/pull/16209/files/904dd952f788160c49d48b5f3aca040069f669fe#r2429767257) I'd like to add new waiters to tail but add woken waiters to head (to give them some edge).

Author: ysbaddaden

spec/std/crystal/pointer_linked_list_spec.cr

@@ -55,6 +55,23 @@ describe Crystal::PointerLinkedList do
     end
   end
 
+  describe "unshift" do
+    it "prepends the node into the list" do
+      list = Crystal::PointerLinkedList(TestedObject).new
+
+      x = TestedObject.new 0
+      y = TestedObject.new 1
+      z = TestedObject.new 2
+
+      list.unshift pointerof(x)
+      list.unshift pointerof(y)
+      list.unshift pointerof(z)
+
+      ExpectOrderHelper.by_next(x, z, y, x)
+      ExpectOrderHelper.by_previous(x, y, z, x)
+    end
+  end
+
   describe "delete" do
     it "remove a node from list" do
       list = Crystal::PointerLinkedList(TestedObject).new
@@ -110,6 +127,40 @@ describe Crystal::PointerLinkedList do
     end
   end
 
+  describe "pop?" do
+    it "remove and return the last element" do
+      list = Crystal::PointerLinkedList(TestedObject).new
+
+      x = TestedObject.new 0
+      y = TestedObject.new 1
+      z = TestedObject.new 2
+      w = TestedObject.new 3
+
+      list.push pointerof(x)
+      list.push pointerof(y)
+      list.push pointerof(z)
+      list.push pointerof(w)
+
+      obj = list.pop?
+
+      typeof(obj).should eq(Pointer(TestedObject)?)
+
+      obj.should_not be_nil
+      obj.should eq(pointerof(w))
+
+      ExpectOrderHelper.by_next(x, y, z, x)
+      ExpectOrderHelper.by_previous(x, z, y, x)
+    end
+
+    it "return nil if list is empty" do
+      list = Crystal::PointerLinkedList(TestedObject).new
+
+      obj = list.pop?
+
+      obj.should be_nil
+    end
+  end
+
   it "does each" do
     list = Crystal::PointerLinkedList(TestedObject).new
 

src/crystal/pointer_linked_list.cr

@@ -31,7 +31,18 @@ struct Crystal::PointerLinkedList(T)
     @head.null?
   end
 
-  # Appends a node to the tail of the list.
+  # Prepends *node* to the head of the list.
+  def unshift(node : Pointer(T)) : Nil
+    if !empty?
+      typeof(self).insert_impl node, @head.value.previous, @head
+    else
+      node.value.previous = node
+      node.value.next = node
+    end
+    @head = node
+  end
+
+  # Appends *node* to the tail of the list.
   def push(node : Pointer(T)) : Nil
     if empty?
       node.value.previous = node
@@ -42,7 +53,7 @@ struct Crystal::PointerLinkedList(T)
     end
   end
 
-  # Removes a node from the list.
+  # Removes *node* from the list.
   def delete(node : Pointer(T)) : Nil
     _next = node.value.next
 
@@ -68,6 +79,21 @@ struct Crystal::PointerLinkedList(T)
     shift { nil }
   end
 
+  # Removes and returns tail from the list, yields if empty.
+  def pop(&)
+    if !empty?
+      h = @head
+      t = (h.value.previous || h).tap { |t| delete(t) }
+    else
+      yield
+    end
+  end
+
+  # Removes and returns tail from the list, `nil` if empty.
+  def pop?
+    pop { nil }
+  end
+
   # Iterates the list.
   def each(&) : Nil
     return if empty?