linked 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 513dbae22fea14a370f2181ef4da797264121631
-  data.tar.gz: 685eb16cb3380aec648af578118b54416af20772
+  metadata.gz: ea4e0ba7b896f4e64d885d73066e65e4e08b49ea
+  data.tar.gz: 7913edd077d33d5a7b36982568d5b3cb46cc7c1e
 SHA512:
-  metadata.gz: b3cfa2318674d45841c7a075250cb88d1095a5df6c56a270eda3bf60bce06cd41db8612f1d1df520cd9ab32ded2f73aedb36f71e1fb410c7d875e77f4d128e62
-  data.tar.gz: 6557225296323c2ff767766bde4ea13067e39103bc84a9e3fb43229991ca65156373475ad7091412174608c11c4b7bdf889274d96d975e9fee3bd493a1f8aab0
+  metadata.gz: 1467066f7e5af4ddc7eca82013d94777b956d7c93497502977fd776523e570bb7ae0d441940cb9a275f567c48750a50cff80881de98e1ca89c1592b7a5aff599
+  data.tar.gz: fac1a3393906af1c00f788fbc4e5eb30ab2b48e042190f898b43944a6ae4718baec62b9c0e0193537cc4f484f4a518f435abf0a7611bb5f28215d6aa8128b54f

data/README.md

@@ -1,5 +1,6 @@
 # Linked
 
+[![Gem Version](https://badge.fury.io/rb/linked.svg)](https://badge.fury.io/rb/linked)
 [![Build Status](https://travis-ci.org/seblindberg/ruby-linked.svg?branch=master)](https://travis-ci.org/seblindberg/ruby-linked)
 [![Coverage Status](https://coveralls.io/repos/github/seblindberg/ruby-linked/badge.svg?branch=master)](https://coveralls.io/github/seblindberg/ruby-linked?branch=master)
 [![Inline docs](http://inch-ci.org/github/seblindberg/ruby-linked.svg?branch=master)](http://inch-ci.org/github/seblindberg/ruby-linked)

data/lib/linked/item.rb

@@ -56,12 +56,12 @@ module Linked
         @prev = nil
       end
     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.
-    
+
     def initialize_dup(source)
       @next = @prev = @list = nil
       @value = begin
@@ -326,21 +326,21 @@ module Linked
         item = item.next
       end
     end
-    
+
     # Freezes the value, as well as making the list item itself immutable.
-    
+
     def freeze
       value.freeze
       super
     end
-    
+
     # The default #inspect method becomes very cluttered the moment you start
     # liking objects together. This implementation fixes that and only shows the
     # class name, object id and value (if set).
-    
+
     def inspect
       return yield self if block_given?
-      
+
       output = format '%s:0x%0x', self.class.name, object_id
       value ? output + " value=#{value.inspect}" : output
     end

data/lib/linked/list.rb

@@ -46,67 +46,81 @@ module Linked
     def initialize(*)
       @eol = EOL.new list: self
       @item_count = 0
-      
+
       super
     end
-    
+
     # When copying a list its entire item chain needs to be copied as well.
     # Therefore #dup will be called on each of the original lists items, making
     # this operation quite expensive.
-    
+
     def initialize_dup(source)
       @eol = EOL.new list: self
       @item_count = 0
-      
+
       source.each_item { |item| push item.dup  }
-      
+
       super
     end
 
-    # Access the first n item(s) in the list.
+    # Access the first n item(s) in the list. If a block is given each item will
+    # be yielded to it. The first item, starting from the first in the list, for
+    # which the block returns true and the n - 1 items directly following it
+    # will be returned.
     #
     # n - the number of items to return.
     #
-    # Returns the first item, or an array of items if n > 1.
+    # Returns, for different values of n:
+    # n == 0) nil
+    # n == 1) an item if the list contains one, or nil
+    #  n > 1) an array of between 0 and n items, depending on how many are in
+    #         the list
 
-    def first(*args)
-      if args.empty?
-        eol.next!
-      else
-        super
+    def first(n = 1)
+      raise ArgumentError, 'n cannot be negative' if n < 0
+
+      return first_item_after eol, count, n unless block_given?
+
+      item = eol
+      items_left = count
+
+      items_left.times do
+        break if yield next_item = item.next
+        item = next_item
+        items_left -= 1
       end
+
+      first_item_after item, items_left, n
     end
 
-    # Access the last n item(s) in the list. When n > 1 the resulting array of
-    # items will have their order preserved.
-    #
-    # When n is zero an empty array will be returned, in order to comply with
-    # the behaviour of #first. Negative values will raise an ArgumentError.
+    # Access the last n item(s) in the list. The items will retain thier order.
+    # If a block is given each item, starting with the last in the list, will be
+    # yielded to it. The first item for which the block returns true and the
+    # n - 1 items directly preceding it will be returned.
     #
     # n - the number of items to return.
     #
-    # Returns the last item, or an array of items if n > 1.
+    # Returns, for different values of n:
+    # n == 0) nil
+    # n == 1) an item if the list contains one, or nil
+    #  n > 1) an array of between 0 and n items, depending on how many are in
+    #         the list
 
     def last(n = 1)
-      if n == 1
-        eol.prev!
-      else
-        raise ArgumentError, 'n cannot be negative' if n < 0
-
-        n = count if n > count
-        res = Array.new n
+      raise ArgumentError, 'n cannot be negative' if n < 0
 
-        return res if n == 0
+      return last_item_before eol, count, n unless block_given?
 
-        item = eol.prev!
-        loop do
-          n -= 1
-          res[n] = item
-          item = item.prev
-        end
+      item = eol
+      items_left = count
 
-        res
+      items_left.times do
+        break if yield prev_item = item.prev
+        item = prev_item
+        items_left -= 1
       end
+
+      last_item_before item, items_left, n
     end
 
     # Overrides the Enumerable#count method when given no argument to provide a
@@ -184,21 +198,32 @@ module Linked
     # 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.
+    # reverse - flips the iteration order if true. Note that this option is
+    #           depricated and will be removed in the next major release.
 
     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
     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(&block)
+      eol.before(&block)
+    end
+
+    alias reverse_each reverse_each_item
+
     # Calls #freeze on all items in the list, as well as the head and the tail
     # (eol).
-    
+
     def freeze
       eol.freeze
       each_item(&:freeze)
@@ -214,15 +239,15 @@ module Linked
     def inspect(&block)
       # Get the parents inspect output
       res = [super]
-      
+
       each_item do |item|
         lines = item.inspect(&block).split "\n"
-        
+
         res.push (item.last? ? '└─╴' : '├─╴') + lines.shift
         padding = item.last? ? '   ' : '│  '
         lines.each { |line| res.push padding + line }
       end
-      
+
       res.join("\n")
     end
 
@@ -247,5 +272,60 @@ module Linked
     private def shrink(n = 1)
       @item_count -= n
     end
+
+    # Private helper method that returns the first n items, starting just after
+    # item,  given that there are items_left items left. The following must hold
+    # for the output to be valid:
+    # a) n > 0
+    # b) there are at least items_left items left
+    #
+    # item - the Item just before the item to start from
+    # items_left - the number of items left.
+    # n - the number of items to return.
+    #
+    # Returns, for different values of n:
+    # n == 0) nil
+    # n == 1) an item if items_left > 0 or nil
+    #  n > 1) an array of items if items_left > 0 or an empty array
+
+    private def first_item_after(item, items_left, n)
+      # Optimize for these cases
+      return nil if n == 0
+      return item.next if n == 1
+
+      (n > items_left ? items_left : n).times.map { item = item.next }
+    rescue StopIteration
+      n > 1 ? [] : nil
+    end
+
+    # Private helper method that returns the last n items, ending just before
+    # item,  given that there are items_left items left. The following must hold
+    # for the output to be valid:
+    # a) n > 0
+    # b) there are at least items_left items left
+    #
+    # item - the Item just after the item to start from.
+    # items_left - the number of items left.
+    # n - the number of items to return.
+    #
+    # Returns, for different values of n:
+    # n == 0) nil
+    # n == 1) an item if items_left > 0 or nil
+    #  n > 1) an array of items if items_left > 0 or an empty array
+
+    private def last_item_before(item, items_left, n)
+      # Optimize for these cases
+      return nil if n == 0
+      return item.prev if n == 1
+
+      # Truncate n if it is larger than the number of items
+      # left
+      n = (n > items_left ? items_left : n)
+      (n - 1).downto(0).with_object(Array.new n) do |i, arr|
+        arr[i] = item = item.prev
+      end
+    rescue StopIteration
+      n > 1 ? [] : nil
+    end
   end
 end

data/lib/linked/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: linked
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Sebastian Lindberg
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-08-07 00:00:00.000000000 Z
+date: 2016-08-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler