linked 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fefa402916a5d9db25add5e34a0d95cfbfe1440f
-  data.tar.gz: 3f17115bffeb8777ba904292f98c8fffbed1b34b
+  metadata.gz: 128756e7bd9d7a135b08f43d8318d94960aa109a
+  data.tar.gz: 1ab7cd3ac051d2beffb1ef345ba45784b0396310
 SHA512:
-  metadata.gz: 6dbf54c87e2ca417d725e40f12eff566439fc9212c5f13c12bd2c089c0018a09cf671de635c2aa800151e3d6474de793e6b3991ab51c7e7fa3f224903ad34cb2
-  data.tar.gz: 83a352fb6f3f00e5bb7245075d47609521dbeb7c508a1ea066acb2fb120e6affdbc2ed9c54cbcc15c881353b7c716653976eec02e138f7b8131e51c6699ac7c9
+  metadata.gz: e7cdc70d3062ec1e70cb854bb5e52f05f7621e6a8225a9c6a3816ae2b57ad0fdfd9d165dd61d48bf9c0f1ad15f27f5d0027ff7a67b09f91673ce56cf064f3a01
+  data.tar.gz: b7439ec77d5db6122b2fc0f230a7eea8ac9d0043fec80674d392e192977354a5f2ea7338284916b720249dd251f0f125f44ceef7c609e1ea21147dba0f6a4f55

data/lib/linked/item.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# TODO: Think about moving some of basic functionallity of Item into Item::Base.
+
 module Linked
   # Item
   #
@@ -84,33 +86,33 @@ module Linked
                end
       super
     end
-    
+
     # Identity method that simply return the item. This method mirrors List#item
     # and allows other methods that work on Item objects to easily and
     # interchangebly accept both lists and items as arguments.
     #
     # Returns 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 the list that the item is part of.
-        
+
     def list
       raise NoMethodError unless @list
       @list
     end
-    
+
     # Check it the item is part of a list.
     #
     # Returns true if the item is in a list.
-    
+
     def in_list?
       @list ? true : false
     end
@@ -132,7 +134,7 @@ module Linked
     def last?
       @next.nil?
     end
-    
+
     # Check if the item is in the given list.
     #
     # list - any object.
@@ -196,66 +198,6 @@ module Linked
 
     alias previous! prev!
 
-    # Split the chain of items in two. If the chain belongs to a list this item
-    # and all that stay connected to it will continue to belong to it, while the
-    # rest are removed from it.
-    #
-    # By default all items followng this one will be kept together, but if given
-    # the argument after: true, the split will instead happen after this item
-    # and it will instead be kept with those before it.
-    #
-    # Example for the chain (A <> B <> C)
-    #
-    #   B.split(after: false) => (A), (B <> C)
-    #   B.split(after: true)  => (A <> B), (C)
-    #
-    # after - determine wheter to split the chain before or after this item.
-    #
-    # Returns self.
-
-    def split after: false
-      warn '[DEPRECATION] this method will be removed in the next major update. Please use #delete_before and #delete_after instead'
-      if after
-        unless last?
-          if @list
-            item = self
-            count = 1 + loop.count do
-              item = item.next
-              item.list = nil
-            end
-
-            tail = @list.tail
-            tail.prev = self
-            @next = tail
-            @list.shrink count
-          else
-            @next.prev = nil
-            @next = nil
-          end
-        end
-      else
-        unless first?
-          if @list
-            item = self
-            count = 1 + loop.count do
-              item = item.prev
-              item.list = nil
-            end
-
-            head = @list.head
-            head.next = self
-            @prev = head
-            @list.shrink count
-          else
-            @prev.next = nil
-            @prev = nil
-          end
-        end
-      end
-
-      self
-    end
-
     # 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.
@@ -271,8 +213,9 @@ module Linked
     # number of added items as an argument. Should it also be the last item
     # #prev= will be called on the list tail.
     #
-    # sibling - the item to append, or an arbitrary object to be wraped in a new
-    #           item.
+    # 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.
 
@@ -281,15 +224,19 @@ module Linked
         first_item = object.item
         last_item = first_item.send :extract_beginning_with, @list
       else
-        first_item = last_item = self.class.new object
-        first_item.list = @list
-        @list.send :grow if @list
+        if @list
+          first_item = last_item = @list.send :create_item, object
+          first_item.list = @list
+          @list.send :grow
+        else
+          first_item = last_item = self.class.new object
+        end
       end
-      
+
       first_item.prev = self
       @next.prev = last_item if @next
       @next, last_item.next = first_item, @next
-      
+
       last_item
     end
 
@@ -308,8 +255,9 @@ module Linked
     # number of added items as an argument. Should it also be the first item
     # #next= will be called on the list head.
     #
-    # sibling - the item to prepend. or an arbitrary object to be wraped in a
-    #           new item.
+    # 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.
 
@@ -318,18 +266,22 @@ module Linked
         last_item = object.item
         first_item = last_item.send :extract_ending_with, @list
       else
-        first_item = last_item = self.class.new object
-        first_item.list = @list
-        @list.send :grow, 1 if @list
+        if @list
+          first_item = last_item = @list.send :create_item, object
+          first_item.list = @list
+          @list.send :grow
+        else
+          first_item = last_item = self.class.new object
+        end
       end
-      
+
       last_item.next = self
       @prev.next = first_item if @prev
       @prev, first_item.prev = last_item, @prev
-      
+
       first_item
     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.
@@ -346,23 +298,23 @@ module Linked
       @next = @prev = @list = nil
       self
     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.
-    
+
     def delete_before
       @prev.send :extract_ending_with unless first?
     end
-    
+
     # Remove all items after 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.
-    
+
     def delete_after
       @next.send :extract_beginning_with unless last?
     end
@@ -420,7 +372,7 @@ module Linked
       output = format '%s:0x%0x', self.class.name, object_id
       value ? output + " value=#{value.inspect}" : output
     end
-    
+
     # PRIVATE DANGEROUS METHOD. This method should never be called directly
     # since it may leave the extracted item chain in an invalid state.
     #
@@ -439,7 +391,7 @@ module Linked
     # be left in an invalid state.
     #
     # Returns the last item of the chain.
-    
+
     private def extract_beginning_with(new_list = nil)
       old_list = @list
       # Count items and move them to the new list
@@ -448,7 +400,7 @@ module Linked
         last_item.list = new_list
         last_item = last_item.next
       end
-      
+
       # Make sure the old list is in a valid state
       if old_list
         if first?
@@ -463,16 +415,16 @@ module Linked
         # Disconnect the item directly after the chain
         @prev.next = nil unless first?
       end
-      
+
       # Disconnect the chain from the list
       @prev = last_item.next = nil
-      
+
       # Preemptivly tell the new list to grow
       new_list.send :grow, count if new_list
-      
+
       last_item
     end
-    
+
     # PRIVATE DANGEROUS METHOD. This method should never be called directly
     # since it may leave the extracted item chain in an invalid state.
     #
@@ -482,7 +434,7 @@ module Linked
     # effects from calling this method.
     #
     # Returns the first item in the chain.
-    
+
     private def extract_ending_with(new_list = nil)
       old_list = @list
       # Count items and move them to the new list
@@ -491,7 +443,7 @@ module Linked
         first_item.list = new_list
         first_item = first_item.prev
       end
-      
+
       # Make sure the old list is in a valid state
       if old_list
         if last?
@@ -506,13 +458,13 @@ module Linked
         # Disconnect the item directly after the chain
         @next.prev = nil unless last?
       end
-      
+
       # Disconnect the chain from the list
       first_item.prev = @next = nil
-      
+
       # Preemptivly tell the new list to grow
       new_list.send :grow, count if new_list
-      
+
       first_item
     end
   end

data/lib/linked/list.rb

@@ -62,24 +62,24 @@ module Linked
 
       super
     end
-    
+
     # Identity method that simply return the list. This method mirrors Item#list
     # and allows other methods that work on List objects to easily and
     # interchangebly accept both lists and items as arguments.
     #
     # Returns the list itself.
-    
+
     def list
       self
     end
-    
+
     # Access the first item in the list. If the list is empty a NoMethodError
     # will be raised. This mirrors the behaviour of Item#item and allows other
     # methods that work on List objects to easily and interchangeably accept
     # both lists and items as arguments.
     #
     # Returns the first item in the list.
-    
+
     def item
       raise NoMethodError if empty?
       eol.next
@@ -167,18 +167,18 @@ module Linked
       @item_count == 0
     end
 
-    # Insert an item at the end of the list. If the given object is not an Item,
-    # or a decendant of Item, it will be treated as a value. Depending on the
-    # state of the list the value will be
-    # a) wraped in a new instance of Item if the list is empty or
-    # b) wraped in an object of the same class as the last item in the list.
+    # Insert an item at the end of the list. If the given object is not an
+    # object responding to #item it will be treated as a value. The value will
+    # be wraped in a new Item create by #create_item.
+    #
+    # See Item#append for more details.
     #
-    # item - the item to insert, or an arbitrary value.
+    # object - the item to insert, or an arbitrary object.
     #
     # Returns self.
 
-    def push(item)
-      eol.append item
+    def push(object)
+      eol.append object
       self
     end
 
@@ -194,17 +194,17 @@ module Linked
     end
 
     # Insert an item at the beginning of the list. If the given object is not an
-    # Item, or a decendant of Item, it will be treated as a value. Depending on
-    # the state of the list the value will be
-    # a) wraped in a new instance of Item if the list is empty or
-    # b) wraped in an object of the same class as the last item in the list.
+    # object responding to #item it will be treated as a value. The value will
+    # be wraped in a new Item create by #create_item.
+    #
+    # See Item#prepend for more details.
     #
-    # item - the item to insert, or an arbitrary value.
+    # object - the item to insert, or an arbitrary object.
     #
     # Returns self.
 
-    def unshift(item)
-      eol.prepend item
+    def unshift(object)
+      eol.prepend object
       self
     end
 
@@ -216,32 +216,24 @@ module Linked
       return nil if empty?
       first.delete
     end
-    
+
     # Check if an item is in the list.
     #
     # item - Item, or any object that may be in the list.
     #
     # Returns true if the given item is in the list, otherwise false.
-    
+
     def include?(item)
       item.in? self
     rescue NoMethodError
       false
     end
 
-    # Iterates over each item in the list, either in normal or reverse order. If
-    # a block is not given an enumerator is returned.
-    #
-    # reverse - flips the iteration order if true. Note that this option is
-    #           depricated and will be removed in the next major release.
+    # Iterates over each item in the list If a block is not given an enumerator
+    # is returned.
 
-    def each_item(reverse: false, &block)
-      if reverse
-        warn '[DEPRECATION] the option `reverse: true` will be removed in a future release. Please call `reverse_each_item` instead.'
-        eol.before(&block)
-      else
-        eol.after(&block)
-      end
+    def each_item(&block)
+      eol.after(&block)
     end
 
     alias each each_item
@@ -285,6 +277,20 @@ module Linked
       res.join("\n")
     end
 
+    # Protected factory method for creating items compatible with the list. This
+    # method is called whenever an arbitrary object is pushed or unshifted onto
+    # the list and need to be wraped inside an Item.
+    #
+    # This method can be overridden to suport different Item types.
+    #
+    # args - any arguments will be passed on to Item.new.
+    #
+    # Returns a new Item.
+
+    protected def create_item(*args)
+      Item.new(*args)
+    end
+
     # Internal method to grow the list with n elements. Never call this method
     # without also inserting the n elements.
     #
@@ -306,17 +312,17 @@ module Linked
     private def shrink(n = 1)
       @item_count -= n
     end
-    
+
     # Private method to clear the list. Never call this method without also
     # modifying the items in the list, as this operation leavs them in an
     # inconsistant state. If the list items are kept, make sure to
     # a) clear the `prev` pointer of the first item and
     # b) clear the `next` pointer of the last item.
-    
+
     private def clear
       head.send :next=, tail
       tail.send :prev=, head
-      
+
       @item_count = 0
     end
 
@@ -342,7 +348,7 @@ module Linked
       return nil if n == 0
       return n > 1 ? [] : nil if item.next!.nil?
       return item.next if n == 1
-      
+
       n = items_left if n > items_left
 
       arr = Array.new n
@@ -376,18 +382,18 @@ module Linked
       return item.prev if n == 1
 
       n = items_left if n > items_left
-      
+
       arr = Array.new n
       (n - 1).downto(0) { |i| arr[i] = item = item.prev }
       arr
     rescue StopIteration
       arr.compact! || arr
     end
-    
+
     # This method is called whenever the module is included somewhere. In the
     # special case when List is included in an Item the #item method must be
     # changed to return self.
-    
+
     def self.included(klass)
       klass.send(:define_method, :item) { self } if klass < Item
     end

data/lib/linked/list/eol.rb

@@ -38,44 +38,28 @@ module Linked
         true
       end
 
-      # Inserts one or more items at the end of the list. If the given object is
-      # not an Item, or a decendant of Item, it will be treated as a value.
-      # Depending on the state of the list the value will be
-      # a) wraped in a new instance of Item if the list is empty or
-      # b) wraped in an object of the same class as the last item in the list.
+      # Inserts one or more items at the end of the list.
       #
-      # sibling - the item or value to be appended.
-      #
-      # Returns the item that was appended. In case of a string of items the
-      # last one is returned.
+      # See Item#append for more details.
 
-      def append(sibling)
-        if @prev == self
-          sibling = Item.new sibling unless sibling.is_a? Item
-          super sibling
-        else
-          @prev.append sibling
-        end
+      def append(object)
+        empty? ? super : @prev.append(object)
       end
 
-      # Inserts one or more items at the beginning of the list. If the given
-      # object is not an Item, or a decendant of Item, it will be treated as a
-      # value. Depending on the state of the list the value will be
-      # a) wraped in a new instance of Item if the list is empty or
-      # b) wraped in an object of the same class as the last item in the list.
+      # Inserts one or more items at the beginning of the list.
       #
-      # sibling - the item or value to be prepended.
+      # See Item#append for more details.
+
+      def prepend(object)
+        empty? ? super : @next.prepend(object)
+      end
+
+      # Private helper to check if the item chain is empty.
       #
-      # Returns the item that was prepended. In case of a string of items the
-      # first one is returned.
+      # Return true if the chain is empty, otherwise nil.
 
-      def prepend(sibling)
-        if @next == self
-          sibling = Item.new sibling unless sibling.is_a? Item
-          super sibling
-        else
-          @next.prepend sibling
-        end
+      private def empty?
+        @prev == self
       end
     end
   end

data/lib/linked/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Linked
-  VERSION = '0.2.1'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: linked
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Sebastian Lindberg