linked 0.4.0 → 0.5.1

data/lib/linked/list_enumerable.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Linked
+  # Expects the list to implement `#list_head` and `#list_tail`.
+  module ListEnumerable
+    include Enumerable
+
+    # Iterates over each item in the list If a block is not given an enumerator
+    # is returned.
+    def each_item
+      return to_enum(__method__) { count } unless block_given?
+      return if empty?
+
+      item = list_head
+      loop do
+        yield item
+        item = item.next
+      end
+    end
+
+    alias each each_item
+
+    # Iterates over each item in the list in reverse order. If a block is not
+    # given an enumerator is returned.
+    def reverse_each_item
+      return to_enum(__method__) { count } unless block_given?
+      return if empty?
+
+      item = list_tail
+      loop do
+        yield item
+        item = item.prev
+      end
+    end
+
+    alias reverse_each reverse_each_item
+
+    # Access the first n item(s) in the list.
+    #
+    # n - the number of items to return.
+    #
+    # Returns, for different values of n:
+    # n = nil) an item if the list contains one, or nil.
+    #  n >= 0) an array of between 0 and n items, depending on how many are in.
+    #          the list.
+    def first(n = nil)
+      return list_head unless n
+      raise ArgumentError, 'n cannot be negative' if n.negative?
+
+      return [] if n.zero? || empty?
+
+      list_head.take n
+    end
+
+    # Access the first n item(s) in the list.
+    #
+    # n - the number of items to return.
+    #
+    # Returns, for different values of n:
+    # n = nil) an item if the list contains one, or nil.
+    #  n >= 0) an array of between 0 and n items, depending on how many are in.
+    #          the list. The order is preserved.
+    def last(n = nil)
+      return empty? ? nil : list_tail unless n
+      raise ArgumentError, 'n cannot be negative' if n.negative?
+
+      return [] if n.zero? || empty?
+
+      list_tail.take(-n)
+    end
+
+    # Overrides the Enumerable#count method when given no argument to provide a
+    # fast item count. Instead of iterating over each item, the internal item
+    # count is returned.
+    #
+    # @param  args [Array<Object>] see Enumerable#count
+    # @return [Integer] the number of items counted.
+    def count(*args)
+      if args.empty? && !block_given?
+        empty? ? 0 : list_head.chain_length
+      else
+        super
+      end
+    end
+  end
+end

data/lib/linked/listable.rb

@@ -1,47 +1,57 @@
+# frozen_string_literal: true
+
 module Linked
-  # Listable
-  #                               List (optional)
-  #                           +----^-----+
-  #                   prev <- | Listable | -> next
-  #                           +----------+
+  # The listable item is the foundational element of the linked list. Each link
+  # in the chain knows what comes both before and after, as well as which
+  # elements are in the beginning and end of the chain. This information can be
+  # used to iterate over the chained elements.
+  #
+  # Internally each listable item stores three pointers: one to the head of the
+  # chain and two for the previous and next items respectivly. The head of the
+  # chain uses the head pointer to store how many elements are currently in the
+  # chain, for fast access. Furthermore it uses its pointer to the previous
+  # element to keep track of the last element of the chain.
+  #
+  # In pracitce this means that some operations are fast, or computationally
+  # cheap, while other are more expensive. The follwing actions are fast:
   #
-  # This module implements doubly linked list items, designed to work both on
-  # their own in a chain, and as children of list.
+  # 1) Accessing the previous and next item.
+  # 2) Accessing the first and last element of the chain.
+  # 3) Calculating the length of the chain.
+  # 4) Appending items.
+  # 5) Deleting any item but the first one.
   #
-  # An object is considered a list if it responds to #grow, #shrink and
-  # #create_item. The former two facilitate counting of the items and will be
-  # called everytime an item is appended, prepended or deleted. #create_item is
-  # expected to return a new object that is compatible with the list.
+  # On the flip side, the following are the expensive operations:
   #
-  # Notation
-  # --------
+  # 1) Prepending items.
+  # 2) Deleting the first item.
+  # 3) Splitting the chain.
   #
+  # === Notation
   # Some methods operate on chains of items, and to describe the effects of an
   # operation the following syntax is used.
   #
-  #                    A   ( A <> B )   [ A <> B ]
-  #                   (i)     (ii)        (iii)
+  #                                A     A <> B
+  #                               (i)     (ii)
   #
   # Single items are denoted with capital letters (i), while chains are written
-  # as multiple connected items (ii). The parenthesis are optional. To show that
-  # one or more nodes are wraped in a list, angle brackets are used (iii).
-
+  # as multiple connected items (ii).
   module Listable
-    # Creates a new item. Always make a call to super whenever implementing this
-    # method in a subclass.
+    include Util
 
+    # Creates a new item. Always make a call to super whenever overriding this
+    # method in an including class.
     def initialize(*)
-      @_next = @_prev = @_list = nil
+      reset_item
       super
     end
 
     # Calling #dup on an item returns a copy that is no longer connected to the
     # original item chain, or the list. The value will also be copied.
     #
-    # Returns a new Item.
-
+    # @return [Listable] a new Listable.
     def initialize_copy(*)
-      @_next = @_prev = @_list = nil
+      reset_item
       super
     end
 
@@ -49,212 +59,233 @@ module Linked
     # and allows other methods that work on Item objects to easily and
     # interchangebly accept both lists and items as arguments.
     #
-    # Returns the item itself.
-
+    # @return [Listable] the item itself.
     def item
       self
     end
 
-    # Access the list that the item is part of. If the item is not in a list a
-    # NoMethodError will be raised. This mirrors the behaviour of List#list and
-    # allows other methods that work on List objects to easily and
-    # interchangeably accept both lists and items as arguments.
+    # Returns true if no item come before this one. Note that the implementation
+    # of this method is protected and publicly accessible through its alias
+    # #first?.
     #
-    # Returns the list that the item is part of.
-
-    def list
-      raise NoMethodError unless @_list
-      @_list
+    # @return [true] if the item is the head of the chain.
+    # @return [false] otherwise.
+    def chain_head?
+      # p @_chain_head.is_a? Numeric
+      # @_chain_head.is_a? Numeric
+      @_prev.chain_tail?
     end
 
-    # Check it the item is part of a list.
-    #
-    # Returns true if the item is in a list.
+    alias first? chain_head?
+    protected :chain_head?
 
-    def in_list?
-      @_list ? true : false
+    # Returns true if no item come after this one. Note that the implementation
+    # of this method is protected and publicly accessible through its alias
+    # #last?.
+    #
+    # @return [true] if the item is the tail of the chain.
+    # @return [false] otherwise.
+    def chain_tail?
+      @_next.nil?
     end
 
-    # Check if this is the first item in the list. It is crucial that tail#nil?
-    # returns true for the first item to be identified correctly.
-    #
-    # Returns true if no item come before this one.
+    alias last? chain_tail?
+    protected :chain_tail?
 
-    def first?
-      @_prev.nil?
+    # Returns the first item in the chain. Note that the implementation of this
+    # method is protected and publicly accessible through its aliases
+    # #first_in_chain and #chain.
+    #
+    # @return [Listable] the first item in the chain.
+    def chain_head
+      chain_head? ? self : chain_head!
     end
 
-    # Check if this is the last item in the list. It is crucial that head#nil?
-    # returns true for the last item to be identified correctly.
-    #
-    # Returns true if no item come after this one.
+    alias first_in_chain chain_head
+    alias chain chain_head
+    protected :chain_head
 
-    def last?
-      @_next.nil?
+    # Returns the last item in the chain. Note that the implementation of this
+    # method is protected and publicly accessible through its aliases
+    # #last_in_chain.
+    #
+    # @return [Listable] the last item in the chain.
+    def chain_tail
+      chain_tail? ? self : chain_head.prev!
     end
 
-    # Check if the item is in the given list.
-    #
-    # list - any object.
+    alias last_in_chain chain_tail
+    protected :chain_tail
+
+    # Returns the number of items in the current chain.
     #
-    # Returns true if the item is part of the given list.
+    # @return [Integer] the number of items in the chain.
+    def chain_length
+      chain_head.chain_head!
+    end
 
-    def in?(list)
-      @_list.equal? list
+    # Check if this object is in a chain.
+    #
+    # @param  other [Object] the object to check.
+    # @return [true] if this object is in the same chain as the given one.
+    # @return [false] otherwise.
+    def in_chain?(other)
+      return false unless other.is_a? Listable
+      chain_head.equal? other.chain_head
     end
 
-    # Access the next item in the list. If this is the last one a StopIteration
+    alias === in_chain?
+
+    # Access the next item in the chain. If this is the last one a StopIteration
     # will be raised, so that items may be iterated over safely in a loop.
     #
-    # Example
+    # === Usage
     #   loop do
     #     item = item.next
     #   end
     #
-    # Returns the item that come after this.
-
+    # @raise  [StopIteration] if this item is the last in the chain.
+    #
+    # @return [Listable] the item that come after this.
     def next
-      raise StopIteration if last?
+      raise StopIteration if chain_tail?
       @_next
     end
 
-    # Access the previous item in the list. If this is the first one a
+    # Access the previous item in the chain. If this is the first one a
     # StopIteration will be raised, so that items may be iterated over safely in
     # a loop.
     #
-    # Example
+    # === Usage
     #   loop do
     #     item = item.prev
     #   end
     #
-    # Returns the item that come before this.
-
+    # @raise  [StopIteration] if this item is the first in the chain.
+    #
+    # @return [Listable] the item that come before this.
     def prev
-      raise StopIteration if first?
+      raise StopIteration if chain_head?
       @_prev
     end
 
     alias previous prev
 
-    # Inserts the given item between this one and the one after it (if any). If
-    # the given item is part of a chain, all items following it will be moved to
-    # this one, and added to the list if one is set.
-    #
-    # Example for the chain (A <> C)
-    #
-    #   A.append B # => (A <> B <> C)
-    #
-    # Alternativly the argument can be an arbitrary object, in which case a new
-    # item will be created around it.
-    #
-    # If this item is part of a list #grow will be called on it with the
-    # number of added items as an argument. Should it also be the last item
-    # #prev= will be called on the list tail.
-    #
-    # object - the item to append, or an arbitrary object to be wraped in a new
-    #          item. If in a list it will be asked to create the new item via
-    #          List#create_item.
-    #
-    # Returns the last item that was appended.
+    # rubocop:disable Metrics/MethodLength
 
     def append(object)
-      if object.respond_to? :item
-        first_item = object.item
-        last_item = first_item.send :extract_beginning_with, @_list
+      # Assume the given object to be the head of its chain
+      # B. If it is not, chain B will be split before the
+      # object, and the sub chain in which the object now is
+      # the head will be appended.
+      sub_chain_b_head = coerce object
+
+      # Grab the first item in this chain. We will need it
+      # later.
+      target_chain = chain_head
+
+      # Split chain B before the given object and grab the
+      # tail of that new sub chain.
+      sub_chain_b_tail = sub_chain_b_head.split_before_and_insert target_chain
+
+      # If we are the last item in our chain we need to
+      # notify the head that there is a new tail.
+      # Otherwise the next item in the list need to be
+      # linked up correctly.
+      if chain_tail?
+        target_chain.prev = sub_chain_b_tail
       else
-        if @_list
-          first_item = last_item = @_list.send :create_item, object
-          first_item.list = @_list
-          @_list.send :grow
-        else
-          first_item = last_item = create_item object
-        end
+        sub_chain_b_tail.next = next!
+        next!.prev = sub_chain_b_tail
       end
 
-      first_item.prev = self
-      @_next.prev = last_item if @_next
-      @_next, last_item.next = first_item, @_next
+      # Connect sub chain B to this item
+      sub_chain_b_head.prev = self
+      self.next = sub_chain_b_head
 
-      last_item
+      sub_chain_b_tail
     end
 
-    # Inserts the given item between this one and the one before it (if any). If
-    # the given item is part of a chain, all items preceeding it will be moved
-    # to this one, and added to the list if one is set.
-    #
-    # Example for the chain (A <> C)
-    #
-    #   C.prepend B # => (A <> B <> C)
-    #
-    # Alternativly the argument can be an arbitrary object, in which case a new
-    # item will be created around it.
-    #
-    # If this item is part of a list #grow will be called on it with the
-    # number of added items as an argument. Should it also be the first item
-    # #next= will be called on the list head.
-    #
-    # object - the item to prepend. or an arbitrary object to be wraped in a
-    #          new item. If in a list it will be asked to create the new item
-    #          via List#create_item.
-    #
-    # Returns the last item that was prepended.
+    # rubocop:enable Metrics/MethodLength
+
+    # rubocop:disable Metrics/MethodLength
 
     def prepend(object)
-      if object.respond_to? :item
-        last_item = object.item
-        first_item = last_item.send :extract_ending_with, @_list
-      else
-        if @_list
-          first_item = last_item = @_list.send :create_item, object
-          first_item.list = @_list
-          @_list.send :grow
-        else
-          first_item = last_item = create_item object
-        end
+      sub_chain_a_tail = coerce object
+
+      if chain_head?
+        sub_chain_a_tail.split_after_and_insert
+        sub_chain_a_tail.append self
+
+        return chain_head
       end
 
-      last_item.next = self
-      @_prev.next = first_item if @_prev
-      @_prev, first_item.prev = last_item, @_prev
+      target_chain = chain_head
+
+      sub_chain_a_head = sub_chain_a_tail.split_after_and_insert target_chain
+
+      prev!.next = sub_chain_a_head
+      sub_chain_a_head.prev = prev!
+
+      sub_chain_a_tail.next = self
+      self.prev = sub_chain_a_tail
 
-      first_item
+      sub_chain_a_head
     end
 
-    # Remove an item from the chain. If this item is part of a list and is
-    # either first, last or both in that list, #next= and #prev= will be called
-    # on the list head and tail respectivly.
+    # rubocop:enable Metrics/MethodLength
+
+    # rubocop:disable Metrics/MethodLength
+
+    # Remove an item from the chain. Note that calling #delete on the first item
+    # in a chain causes all subsequent items to be moved to a new chain.
     #
-    # If this item is part of a list #shrink will be called on it.
+    # === Usage
+    # Example using the chain A <> B <> C
     #
-    # Returns self.
-
+    #   A.delete # => A | B <> C
+    #   B.delete # => B | A <> C
+    #   C.delete # => C | A <> B
+    #
+    # @return [self]
     def delete
-      @_next.prev = @_prev if @_next
-      @_prev.next = @_next if @_prev
-      @_list.send :shrink if @_list
+      if chain_head?
+        split_after_and_insert
+      else
+        shrink
 
-      @_next = @_prev = @_list = nil
-      self
+        if chain_tail?
+          chain_head.prev = @_prev
+        else
+          @_next.prev = @_prev
+        end
+
+        @_prev.next = @_next
+      end
+
+      reset_item
     end
 
-    # Remove all items before this one in the chain. If the items are part of a
-    # list they will be removed from it.
-    #
-    # Returns the last item in the chain that was just deleted, or nil if this
-    # is the first item.
+    # rubocop:enable Metrics/MethodLength
 
+    # Remove all items before this one in the chain.
+    #
+    # @return [nil] if this is the first item.
+    # @return [Listable] the first item in the chain that was just deleted.
     def delete_before
-      @_prev.send :extract_ending_with unless first?
+      prev!.split_after_and_insert unless chain_head?
     end
 
-    # Remove all items after this one in the chain. If the items are part of a
-    # list they will be removed from it.
+    # Remove all items after this one in the chain.
     #
-    # Returns the last item in the chain that was just deleted, or nil if this
-    # is the first item.
-
+    # @return [nil] if this is the lst item.
+    # @return [Listable] the first item in the chain that was just deleted.
     def delete_after
-      @_next.send :extract_beginning_with unless last?
+      return nil if chain_tail?
+
+      item = next!
+      item.split_before_and_insert
+      item
     end
 
     # Iterates over each item before this, in reverse order. If a block is not
@@ -262,12 +293,11 @@ module Linked
     #
     # Note that raising a StopIteraion inside the block will cause the loop to
     # silently stop the iteration early.
-
     def before
       return to_enum(__callee__) unless block_given?
-      return if first?
+      return if chain_head?
 
-      item = self.prev
+      item = prev
 
       loop do
         yield item
@@ -280,10 +310,9 @@ module Linked
     #
     # Note that raising a StopIteraion inside the block will cause the loop to
     # silently stop the iteration early.
-
     def after
       return to_enum(__callee__) unless block_given?
-      return if last?
+      return if chain_tail?
 
       item = self.next
 
@@ -293,6 +322,60 @@ module Linked
       end
     end
 
+    # rubocop:disable Metrics/MethodLength
+
+    # Take n items and put them into a sorted array. If n is positive the array
+    # will include this item, as well the n - 1 items following it in the chain.
+    # If n is negative the items will be taken from before this item instead.
+    #
+    # If there are less than n - 1 items before/after this the resulting array
+    # will contain less than n items.
+    #
+    # @raise  [ArgumentError] if `n` is not an integer.
+    #
+    # @param  n [Integer] the number of items to take.
+    # @return [Array<Listable>] an array containing the taken items.
+    def take(n)
+      raise ArgumentError, 'n must be an integer' unless n.is_a? Integer
+
+      # Optimize for the most simple cases
+      return [self] if n == 1 || n == -1
+      return [] if n.zero?
+
+      n_abs = n.abs
+
+      res = Array.new n_abs
+
+      if n.positive?
+        res[0] = self
+        enum = after
+        iter = 1.upto(n_abs - 1)
+      else
+        res[n_abs - 1] = self
+        enum = before
+        iter = (n_abs - 2).downto 0
+      end
+
+      iter.each { |i| res[i] = enum.next }
+      res
+    rescue StopIteration
+      res.compact!
+      res
+    end
+
+    # rubocop:enable Metrics/MethodLength
+
+    # Due to the nature of listable objects the default #inspect method is
+    # problematic. This basic replacement includes only the class name and the
+    # object id.
+    #
+    # @return [String] a string representation of the object.
+    def inspect
+      block_given? ? yield(self) : object_identifier
+    end
+
+    protected
+
     # Protected factory method for creating items compatible with this listable
     # item. This method is called whenever an arbitrary object is appended or
     # prepended onto this item and need to be wraped/converted.
@@ -301,141 +384,221 @@ module Linked
     #
     # args - any arguments will be passed on to .new.
     #
-    # Returns a new Listable object.
-
-    protected def create_item(*args)
+    # Must return a new Listable object.
+    def create_item(*args)
       self.class.new(*args)
     end
 
-    # Protected unsafe accessor of the next item in the list. It is preferable
+    # Protected unsafe accessor of the next item in the chain. It is preferable
     # to use #next, possibly in conjunction with #last?.
     #
     # Returns the item that come after this, or nil if this is the last one.
-
-    protected def next!
+    def next!
       @_next
     end
 
-    # Calling #next= directly is not recommended since it may corrupt the chain.
-
-    protected def next=(other)
+    # Never call this method directly since it may corrupt the chain.
+    #
+    # Sets the value of the `next` field.
+    def next=(other)
       @_next = other
     end
 
-    # Protected, unsafe accessor of the previous item in the list. It is
+    # Protected, unsafe accessor of the previous item in the chain. It is
     # preferable to use #prev, possibly in conjunction with #first?.
     #
-    # Returns the item that come before this, or nil if this is the first one.
-
-    protected def prev!
+    # Returns the item that come before this, or the last item in the chain if
+    # this is the first one.
+    def prev!
       @_prev
     end
 
-    # Calling #prev= directly is not recommended since it may corrupt the chain.
-
-    protected def prev=(other)
+    # Never call this method directly since it may corrupt the chain.
+    #
+    # Sets the value of the `prev` field.
+    def prev=(other)
       @_prev = other
     end
 
-    # Calling #list= directly is not recommended since it may corrupt the list.
+    # Protected, unsafe accessor of the first item in the chain. It is
+    # preferable to use #first.
+    #
+    # Returns the first item in the chain, or the chain item count if this is
+    # the first one.
+    def chain_head!
+      @_chain_head
+    end
+
+    # Never call this method directly since it may corrupt the chain.
+    #
+    # Sets the value of the `first` field.
 
-    protected def list=(list)
-      @_list = list
+    def chain_head=(other)
+      @_chain_head = other
     end
 
-    # PRIVATE DANGEROUS METHOD. This method should never be called directly
-    # since it may leave the extracted item chain in an invalid state.
+    # Never call this method directly since it may corrupt the chain. Grow the
+    # chain with n items.
     #
-    # This method extracts the item, together with the chain following it, from
-    # the list they are in (if any) and optionally facilitates moving them to a
-    # new list.
+    # n - the number of items to increase the chain count with.
     #
-    # Given the two lists
-    #                         [ A <> B <> C ]   [ D ]
-    #                               (I)          (II)
+    # Returns the updated chain count.
+
+    def grow(n = 1)
+      head = chain_head
+      head.chain_head = head.chain_head! + n
+    end
+
+    # Never call this method directly since it may corrupt the chain. Shrink the
+    # chain with n items.
     #
-    # calling B.extract_beginning_with(II) will result in (B <> C) being removed
-    # from (I), and (II) to be grown by two. (B <> C) will now reference (II)
-    # but they will not yet be linked to any of the items in it. It is therefore
-    # necessary to insert them directly after calling this method, or (II) will
-    # be left in an invalid state.
+    # n - the number of items to decrease the chain count with.
     #
-    # Returns the last item of the chain.
+    # Returns the updated chain count.
+
+    def shrink(n = 1)
+      head = chain_head
+      head.chain_head = head.chain_head! - n
+    end
 
-    private def extract_beginning_with(new_list = nil)
-      old_list = @_list
-      # Count items and move them to the new list
-      last_item = self
-      count = 1 + loop.count do
-        last_item.list = new_list
-        last_item = last_item.next
+    # Split the chain on this item and insert the latter part into the chain
+    # with head as its first item.
+    #
+    # Calling C.split_before_and_insert(.) yields the two chains (ii) and (iii)
+    #
+    #   A <> B <> C <> D    A <> B    C <> D
+    #         (i)            (ii)     (iii)
+    #
+    # Chain (ii) is guaranteed to be complete. Chain (iii) will however be left
+    # in an inclomplete state unless head_b == self (default). The first item in
+    # (iii) must then be connected to the one preceeding it.
+    #
+    # head_b - the head of a new chain that (iii) will be added to.
+    #
+    # Returns the last element of (iii).
+
+    def split_before_and_insert(head_b = self)
+      # Get the current chain head. It will remain the head
+      # of sub chain a (ii). If this item is the first then
+      # chain a will be empty.
+      chain_a_head = chain_head? ? nil : chain_head
+
+      # The head of sub chain b (iii) is self.
+      chain_b_head = self
+
+      # Find the tail of sub chain b by iterating over each
+      # item, starting with this one. Set the the new head
+      # of these while counting them.
+      chain_b_tail = self
+      chain_b_length = 1
+
+      loop do
+        chain_b_tail.chain_head = head_b
+        chain_b_tail = chain_b_tail.next
+        chain_b_length += 1
       end
 
-      # Make sure the old list is in a valid state
-      if old_list
-        if first?
-          old_list.send :clear
-        else
-          old_list.send :shrink, count
-          # Fix the links within in the list
-          @_prev.next = last_item.next!
-          last_item.next!.prev = @_prev
-        end
-      else
-        # Disconnect the item directly after the chain
-        @_prev.next = nil unless first?
+      # If sub chain a is not empty it needs to be updated.
+      # Shrink its count by the number of items in sub
+      # chain b and complete it by connecting the head to
+      # the tail.
+      if chain_a_head
+        chain_a_head.shrink chain_b_length
+
+        chain_a_tail = chain_b_head.prev
+        chain_a_head.prev = chain_a_tail
+        chain_a_tail.next = nil
       end
 
-      # Disconnect the chain from the list
-      @_prev = last_item.next = nil
+      # Tell the new chain to grow. If sub chain b is to be
+      # the new head we can insert the count directly. We
+      # also complete the chain by connecting the head to
+      # the tail. The next field of the tail should already
+      # be nil.
+      if chain_b_head.equal? head_b
+        chain_b_head.chain_head = chain_b_length
+        chain_b_head.prev = chain_b_tail
+      else
+        head_b.grow chain_b_length
+      end
 
-      # Preemptivly tell the new list to grow
-      new_list.send :grow, count if new_list
+      # Chain a is now either empty (nil) or completed.
+      # Chain b however is only complete if the given head
+      # is equal to self (default). If it is not chain b
+      # will need a) the next field of the tail set to the
+      # item after, unless nil, and b) the prev field of
+      # head set to the item before.
 
-      last_item
+      chain_b_tail
     end
 
-    # PRIVATE DANGEROUS METHOD. This method should never be called directly
-    # since it may leave the extracted item chain in an invalid state.
-    #
-    # This method extracts the item, together with the chain preceding it, from
-    # the list they are in (if any) and optionally facilitates moving them to a
-    # new list. See #extract_beginning_with for a description of the side
-    # effects from calling this method.
-    #
-    # Returns the first item in the chain.
+    # TODO
 
-    private def extract_ending_with(new_list = nil)
-      old_list = @_list
-      # Count items and move them to the new list
-      first_item = self
-      count = 1 + loop.count do
-        first_item.list = new_list
-        first_item = first_item.prev
-      end
+    def split_after_and_insert(head_a = chain_head)
+      # If this is not the last item in the chain, sub chain
+      # b will contain items. Use #split_before_and_insert
+      # to cut the chain after this one. This will complete
+      # chain b and update the item count of chain a.
+      next!.split_before_and_insert unless chain_tail?
 
-      # Make sure the old list is in a valid state
-      if old_list
-        if last?
-          old_list.send :clear
-        else
-          old_list.send :shrink, count
-          # Fix the links within in the list
-          @_next.prev = first_item.prev!
-          first_item.prev!.next = @_next
-        end
-      else
-        # Disconnect the item directly after the chain
-        @_next.prev = nil unless last?
+      chain_a_head = chain_head
+
+      # If the head of sub chain a is same as the target
+      # chain head
+      return chain_a_head if chain_a_head.equal? head_a
+
+      chain_a_length = chain_length
+
+      # Set the head field of all items, starting with the
+      # tail (self), moving backwards.
+      item = self
+
+      # Loop until we hit the first item.
+      loop do
+        item.chain_head = head_a
+        item = item.prev
       end
 
-      # Disconnect the chain from the list
-      first_item.prev = @_next = nil
+      # Tell the target chain to grow with the number of
+      # items in sub chain a.
+      head_a.grow chain_a_length
+
+      # Sub chain b is now either empty or complete. Sub
+      # chain a however is only complete if the target
+      # head is the same as the head of chain a. Otherwise
+      # the prev field of head and the next field of tail
+      # both need to be set correctly.
+      chain_a_head
+    end
+
+    private
 
-      # Preemptivly tell the new list to grow
-      new_list.send :grow, count if new_list
+    # Convert the given object to a listable item. If the object responds to
+    # #item the result of that call is returned. Otherwise a new item is created
+    # using #create_item.
+    #
+    # @param  other [Object] the object to coerce.
+    # @return [Listable] a listable item.
+    def coerce(other)
+      if other.respond_to? :item
+        other.item
+      else
+        create_item other
+      end
+    end
 
-      first_item
+    # Reset the fields of the item to their initial state. This leaves the item
+    # in a consistent state as a single item chain.
+    #
+    # Only call this method on items that are disconnected from their siblings.
+    # Otherwise the original chain (if any) will be left in an inconsistent
+    # state.
+    #
+    # @return [self]
+    def reset_item
+      @_chain_head = 1
+      @_next = nil
+      @_prev = self
     end
   end
 end