hamster 1.0.1.pre.rc3 → 2.0.0

data/lib/hamster/immutable.rb

@@ -11,7 +11,7 @@ module Hamster
     # @private
     module ClassMethods
       def new(*args)
-        super.immutable!
+        super.__send__(:immutable!)
       end
 
       def memoize(*names)

data/lib/hamster/list.rb

@@ -1,27 +1,14 @@
-require "forwardable"
 require "thread"
-require "atomic"
 require "set"
+require "concurrent/atomics"
 
-require "hamster/core_ext/enumerable"
 require "hamster/undefined"
 require "hamster/enumerable"
+require "hamster/hash"
 require "hamster/set"
 
 module Hamster
   class << self
-    extend Forwardable
-
-    # Create a list containing the given items.
-    #
-    # @example
-    #   list = Hamster.list(:a, :b, :c)
-    #   # => [:a, :b, :c]
-    #
-    # @return [List]
-    def list(*items)
-      items.to_list
-    end
 
     # Create a lazy, infinite list.
     #
@@ -29,7 +16,7 @@ module Hamster
     #
     # @example
     #   Hamster.stream { :hello }.take(3)
-    #   # => [:hello, :hello, :hello]
+    #   # => Hamster::List[:hello, :hello, :hello]
     #
     # @return [List]
     def stream(&block)
@@ -41,7 +28,7 @@ module Hamster
     #
     # @example
     #   Hamster.interval(5,9)
-    #   # => [5, 6, 7, 8, 9]
+    #   # => Hamster::List[5, 6, 7, 8, 9]
     #
     # @param from [Integer] Start value, inclusive
     # @param to [Integer] End value, inclusive
@@ -50,13 +37,12 @@ module Hamster
       return EmptyList if from > to
       interval_exclusive(from, to.next)
     end
-    def_delegator :self, :interval, :range
 
     # Create an infinite list repeating the same item indefinitely
     #
     # @example
     #   Hamster.repeat(:chunky).take(4)
-    #   => [:chunky, :chunky, :chunky, :chunky]
+    #   => Hamster::List[:chunky, :chunky, :chunky, :chunky]
     #
     # @return [List]
     def repeat(item)
@@ -66,8 +52,8 @@ module Hamster
     # Create a list that contains a given item a fixed number of times
     #
     # @example
-    #   Hamster.replicate(3).(:hamster)
-    #   #=> [:hamster, :hamster, :hamster]
+    #   Hamster.replicate(3, :hamster)
+    #   #=> Hamster::List[:hamster, :hamster, :hamster]
     #
     # @return [List]
     def replicate(number, item)
@@ -79,18 +65,18 @@ module Hamster
     #
     # @example
     #   Hamster.iterate(0) { |i| i.next }.take(5)
-    #   # => [0, 1, 2, 3, 4]
+    #   # => Hamster::List[0, 1, 2, 3, 4]
     #
-    # @param item [Object] Starting value
-    # @yieldparam [Object] The previous value
+    # @param [Object] item Starting value
+    # @yieldparam [Object] previous The previous value
     # @yieldreturn [Object] The next value
     # @return [List]
     def iterate(item, &block)
       LazyList.new { Cons.new(item, iterate(yield(item), &block)) }
     end
 
-    # Turn an Enumerator into a `Hamster::List`. The result is a lazy collection
-    # where the values are memoized as they are generated.
+    # Turn an `Enumerator` into a `Hamster::List`. The result is a lazy
+    # collection where the values are memoized as they are generated.
     #
     # If your code uses multiple threads, you need to make sure that the returned
     # lazy collection is realized on a single thread only. Otherwise, a `FiberError`
@@ -121,29 +107,58 @@ module Hamster
     end
   end
 
-  # A `List` can be constructed with {Hamster.list Hamster.list} or {List.[] List[]}.
+  # A `List` can be constructed with {List.[] List[]}, or {Enumerable#to_list}.
   # It consists of a *head* (the first element) and a *tail* (which itself is also
   # a `List`, containing all the remaining elements).
   #
-  # This is a singly linked list. Prepending to the list with {List#cons} runs
+  # This is a singly linked list. Prepending to the list with {List#add} runs
   # in constant time. Traversing the list from front to back is efficient,
   # however, indexed access runs in linear time because the list needs to be
   # traversed to find the element.
   #
   module List
-    extend Forwardable
     include Enumerable
 
     # @private
     CADR = /^c([ad]+)r$/
 
-    def_delegator :self, :head, :first
-    def_delegator :self, :empty?, :null?
-
     # Create a new `List` populated with the given items.
-    # @return [Set]
+    #
+    # @example
+    #   list = Hamster::List[:a, :b, :c]
+    #   # => Hamster::List[:a, :b, :c]
+    #
+    # @return [List]
     def self.[](*items)
-      items.to_list
+      from_enum(items)
+    end
+
+    # Return an empty `List`.
+    #
+    # @return [List]
+    def self.empty
+      EmptyList
+    end
+
+    # This method exists distinct from `.[]` since it is ~30% faster
+    # than splatting the argument.
+    #
+    # Marking as private only because it was introduced for an internal
+    # refactoring. It could potentially be made public with a good name.
+    #
+    # @private
+    def self.from_enum(items)
+      # use destructive operations to build up a new list, like Common Lisp's NCONC
+      # this is a very fast way to build up a linked list
+      list = tail = Hamster::Cons.allocate
+      items.each do |item|
+        new_node = Hamster::Cons.allocate
+        new_node.instance_variable_set(:@head, item)
+        tail.instance_variable_set(:@tail, new_node)
+        tail = new_node
+      end
+      tail.instance_variable_set(:@tail, Hamster::EmptyList)
+      list.tail
     end
 
     # Return the number of items in this `List`.
@@ -160,30 +175,41 @@ module Hamster
       end
       result
     end
-    def_delegator :self, :size, :length
+    alias :length :size
 
-    # Create a new `List` with `item` added at the front.
+    # Create a new `List` with `item` added at the front. This is a constant
+    # time operation.
+    #
+    # @example
+    #   Hamster::List[:b, :c].add(:a)
+    #   # => Hamster::List[:a, :b, :c]
+    #
     # @param item [Object] The item to add
     # @return [List]
-    def cons(item)
+    def add(item)
       Cons.new(item, self)
     end
-    def_delegator :self, :cons, :>>
-    def_delegator :self, :cons, :conj
-    def_delegator :self, :cons, :conjoin
+    alias :cons :add
 
-    # Create a new `List` with `item` added at the end.
+    # Create a new `List` with `item` added at the end. This is much less efficient
+    # than adding items at the front.
+    #
+    # @example
+    #   Hamster::List[:a, :b] << :c
+    #   # => Hamster::List[:a, :b, :c]
+    #
     # @param item [Object] The item to add
     # @return [List]
-    def add(item)
-      append(Hamster.list(item))
+    def <<(item)
+      append(List[item])
     end
-    def_delegator :self, :add, :<<
 
     # Call the given block once for each item in the list, passing each
-    # item from first to last successively to the block.
+    # item from first to last successively to the block. If no block is given,
+    # returns an `Enumerator`.
     #
     # @return [self]
+    # @yield [item]
     def each
       return to_enum unless block_given?
       list = self
@@ -193,10 +219,15 @@ module Hamster
       end
     end
 
-    # Return a lazy list in which each element is derived from the corresponding
-    # element in this `List`, transformed through the given block.
+    # Return a `List` in which each element is derived from the corresponding
+    # element in this `List`, transformed through the given block. If no block
+    # is given, returns an `Enumerator`.
     #
-    # @return [List]
+    # @example
+    #   Hamster::List[3, 2, 1].map { |e| e * e } # => Hamster::List[9, 4, 1]
+    #
+    # @return [List, Enumerator]
+    # @yield [item]
     def map(&block)
       return enum_for(:map) unless block_given?
       LazyList.new do
@@ -204,42 +235,58 @@ module Hamster
         Cons.new(yield(head), tail.map(&block))
       end
     end
-    def_delegator :self, :map, :collect
+    alias :collect :map
 
-    # Return a lazy list which is realized by transforming each item into a `List`,
+    # Return a `List` which is realized by transforming each item into a `List`,
     # and flattening the resulting lists.
     #
+    # @example
+    #   Hamster::List[1, 2, 3].flat_map { |x| Hamster::List[x, 100] }
+    #   # => Hamster::List[1, 100, 2, 100, 3, 100]
+    #
     # @return [List]
     def flat_map(&block)
       return enum_for(:flat_map) unless block_given?
       LazyList.new do
         next self if empty?
-        head_list = Hamster.list(*yield(head))
+        head_list = List.from_enum(yield(head))
         next tail.flat_map(&block) if head_list.empty?
         Cons.new(head_list.first, head_list.drop(1).append(tail.flat_map(&block)))
       end
     end
 
-    # Return a lazy list which contains all the items for which the given block
+    # Return a `List` which contains all the items for which the given block
     # returns true.
     #
+    # @example
+    #   Hamster::List["Bird", "Cow", "Elephant"].select { |e| e.size >= 4 }
+    #   # => Hamster::List["Bird", "Elephant"]
+    #
     # @return [List]
-    def filter(&block)
-      return enum_for(:filter) unless block_given?
+    # @yield [item] Once for each item.
+    def select(&block)
+      return enum_for(:select) unless block_given?
       LazyList.new do
         list = self
         while true
           break list if list.empty?
-          break Cons.new(list.head, list.tail.filter(&block)) if yield(list.head)
+          break Cons.new(list.head, list.tail.select(&block)) if yield(list.head)
           list = list.tail
         end
       end
     end
+    alias :find_all :select
+    alias :keep_if  :select
 
-    # Return a lazy list which contains all elements up to, but not including, the
+    # Return a `List` which contains all elements up to, but not including, the
     # first element for which the block returns `nil` or `false`.
     #
+    # @example
+    #   Hamster::List[1, 3, 5, 7, 6, 4, 2].take_while { |e| e < 5 }
+    #   # => Hamster::List[1, 3]
+    #
     # @return [List, Enumerator]
+    # @yield [item]
     def take_while(&block)
       return enum_for(:take_while) unless block_given?
       LazyList.new do
@@ -249,10 +296,15 @@ module Hamster
       end
     end
 
-    # Return a lazy list which contains all elements starting from the
+    # Return a `List` which contains all elements starting from the
     # first element for which the block returns `nil` or `false`.
     #
+    # @example
+    #   Hamster::List[1, 3, 5, 7, 6, 4, 2].drop_while { |e| e < 5 }
+    #   # => Hamster::List[5, 7, 6, 4, 2]
+    #
     # @return [List, Enumerator]
+    # @yield [item]
     def drop_while(&block)
       return enum_for(:drop_while) unless block_given?
       LazyList.new do
@@ -262,7 +314,12 @@ module Hamster
       end
     end
 
-    # Return a lazy list containing the first `number` items from this `List`.
+    # Return a `List` containing the first `number` items from this `List`.
+    #
+    # @example
+    #   Hamster::List[1, 3, 5, 7, 6, 4, 2].take(3)
+    #   # => Hamster::List[1, 3, 5]
+    #
     # @param number [Integer] The number of items to retain
     # @return [List]
     def take(number)
@@ -273,7 +330,11 @@ module Hamster
       end
     end
 
-    # Return a lazy list containing all but the last item from this `List`.
+    # Return a `List` containing all but the last item from this `List`.
+    #
+    # @example
+    #   Hamster::List["A", "B", "C"].pop  # => Hamster::List["A", "B"]
+    #
     # @return [List]
     def pop
       LazyList.new do
@@ -284,8 +345,13 @@ module Hamster
       end
     end
 
-    # Return a lazy list containing all items after the first `number` items from
+    # Return a `List` containing all items after the first `number` items from
     # this `List`.
+    #
+    # @example
+    #   Hamster::List[1, 3, 5, 7, 6, 4, 2].drop(3)
+    #   # => Hamster::List[7, 6, 4, 2]
+    #
     # @param number [Integer] The number of items to skip over
     # @return [List]
     def drop(number)
@@ -299,9 +365,13 @@ module Hamster
       end
     end
 
-    # Return a lazy list with all items from this `List`, followed by all items from
+    # Return a `List` with all items from this `List`, followed by all items from
     # `other`.
     #
+    # @example
+    #   Hamster::List[1, 2, 3].append(Hamster::List[4, 5])
+    #   # => Hamster::List[1, 2, 3, 4, 5]
+    #
     # @param other [List] The list to add onto the end of this one
     # @return [List]
     def append(other)
@@ -310,21 +380,31 @@ module Hamster
         Cons.new(head, tail.append(other))
       end
     end
-    def_delegator :self, :append, :concat
-    def_delegator :self, :append, :cat
-    def_delegator :self, :append, :+
+    alias :concat :append
+    alias :+ :append
 
     # Return a `List` with the same items, but in reverse order.
+    #
+    # @example
+    #   Hamster::List["A", "B", "C"].reverse # => Hamster::List["C", "B", "A"]
+    #
     # @return [List]
     def reverse
       LazyList.new { reduce(EmptyList) { |list, item| list.cons(item) }}
     end
 
-    # Gather the corresponding elements from this `List` and `others` (that is,
-    # the elements with the same indices) into new 2-element lists. Return a
-    # lazy list of these 2-element lists.
+    # Combine two lists by "zipping" them together.  The corresponding elements
+    # from this `List` and each of `others` (that is, the elements with the
+    # same indices) will be gathered into lists.
     #
-    # @param others [List] A list of the lists to zip together with this one
+    # If `others` contains fewer elements than this list, `nil` will be used
+    # for padding.
+    #
+    # @example
+    #   Hamster::List["A", "B", "C"].zip(Hamster::List[1, 2, 3])
+    #   # => Hamster::List[Hamster::List["A", 1], Hamster::List["B", 2], Hamster::List["C", 3]]
+    #
+    # @param others [List] The list to zip together with this one
     # @return [List]
     def zip(others)
       LazyList.new do
@@ -335,7 +415,7 @@ module Hamster
 
     # Gather the first element of each nested list into a new `List`, then the second
     # element of each nested list, then the third, and so on. In other words, if each
-    # nested list is a "row", return a lazy list of "columns" instead.
+    # nested list is a "row", return a `List` of "columns" instead.
     #
     # Although the returned list is lazy, each returned nested list (each "column")
     # is strict. So while each nested list in the input can be infinite, the parent
@@ -349,7 +429,7 @@ module Hamster
     #   list3 = Hamster.iterate(3) { |n| n * 3 }
     #
     #   # Now we transpose our 3 infinite "rows" into an infinite series of 3-element "columns"
-    #   Hamster.list(list1, list2, list3).transpose.take(4)
+    #   Hamster::List[list1, list2, list3].transpose.take(4)
     #   # => Hamster::List[
     #   #      Hamster::List[1, 2, 3],
     #   #      Hamster::List[2, 4, 9],
@@ -367,8 +447,12 @@ module Hamster
       end
     end
 
-    # Concatenate an infinite series of copies of this `List` together (into a
-    # new lazy list). Or, if empty, just return an empty list.
+    # Concatenate an infinite series of copies of this `List` together into a
+    # new `List`. Or, if empty, just return an empty list.
+    #
+    # @example
+    #   Hamster::List[1, 2, 3].cycle.take(10)
+    #   # => Hamster::List[1, 2, 3, 1, 2, 3, 1, 2, 3, 1]
     #
     # @return [List]
     def cycle
@@ -384,27 +468,43 @@ module Hamster
     # will be moved to the end. If `count` is negative, the elements will be shifted
     # right, and those shifted past the last position will be moved to the beginning.
     #
+    # @example
+    #   l = Hamster::List["A", "B", "C", "D", "E", "F"]
+    #   l.rotate(2)   # => Hamster::List["C", "D", "E", "F", "A", "B"]
+    #   l.rotate(-1)  # => Hamster::List["F", "A", "B", "C", "D", "E"]
+    #
     # @param count [Integer] The number of positions to shift items by
     # @return [Vector]
+    # @raise [TypeError] if count is not an integer.
     def rotate(count = 1)
       raise TypeError, "expected Integer" if not count.is_a?(Integer)
-      return self if  empty? || (count % size) == 0
+      return self if empty? || (count % size) == 0
       count = (count >= 0) ? count % size : (size - (~count % size) - 1)
       drop(count).append(take(count))
     end
 
-    # Return 2 `List`s, one of the first `number` items, and another of all the
-    # remaining items.
+    # Return two `List`s, one of the first `number` items, and another with the
+    # remaining.
+    #
+    # @example
+    #   Hamster::List["a", "b", "c", "d"].split_at(2)
+    #   # => [Hamster::List["a", "b"], Hamster::List["c", "d"]]
+    #
     # @param number [Integer] The index at which to split this list
     # @return [Array]
     def split_at(number)
       [take(number), drop(number)].freeze
     end
 
-    # Return 2 `List`s, one up to (but not including) the first item for which the
+    # Return two `List`s, one up to (but not including) the first item for which the
     # block returns `nil` or `false`, and another of all the remaining items.
     #
+    # @example
+    #   Hamster::List[4, 3, 5, 2, 1].span { |x| x > 2 }
+    #   # => [Hamster::List[4, 3, 5], Hamster::List[2, 1]]
+    #
     # @return [Array]
+    # @yield [item]
     def span(&block)
       return [self, EmptyList].freeze unless block_given?
       splitter = Splitter.new(self, block)
@@ -413,46 +513,75 @@ module Hamster
        Splitter::Right.new(splitter, mutex)].freeze
     end
 
-    # Return 2 `List`s, one up to (but not including) the first item for which the
+    # Return two `List`s, one up to (but not including) the first item for which the
     # block returns true, and another of all the remaining items.
     #
+    # @example
+    #   Hamster::List[1, 3, 4, 2, 5].break { |x| x > 3 }
+    #   # => [Hamster::List[1, 3], Hamster::List[4, 2, 5]]
+    #
     # @return [Array]
+    # @yield [item]
     def break(&block)
       return span unless block_given?
       span { |item| !yield(item) }
     end
 
-    # Return an empty `List`.
+    # Return an empty `List`. If used on a subclass, returns an empty instance
+    # of that class.
+    #
     # @return [List]
     def clear
       EmptyList
     end
 
-    # Return a `List` with the same items, but sorted either in their natural order,
-    # or using an optional comparator block. The block must take 2 parameters, and
-    # return 0, 1, or -1 if the first one is equal, greater than, or less than the
-    # second (respectively).
+    # Return a new `List` with the same items, but sorted.
+    #
+    # @overload sort
+    #   Compare elements with their natural sort key (`#<=>`).
+    #
+    #   @example
+    #     Hamster::List["Elephant", "Dog", "Lion"].sort
+    #     # => Hamster::List["Dog", "Elephant", "Lion"]
+    #
+    # @overload sort
+    #   Uses the block as a comparator to determine sorted order.
+    #
+    #   @yield [a, b] Any number of times with different pairs of elements.
+    #   @yieldreturn [Integer] Negative if the first element should be sorted
+    #                          lower, positive if the latter element, or 0 if
+    #                          equal.
+    #   @example
+    #     Hamster::List["Elephant", "Dog", "Lion"].sort { |a,b| a.size <=> b.size }
+    #     # => Hamster::List["Dog", "Lion", "Elephant"]
     #
     # @return [List]
     def sort(&comparator)
-      LazyList.new { super(&comparator).to_list }
+      LazyList.new { List.from_enum(super(&comparator)) }
     end
 
-    # Return a new `List` with the same items, but sorted. The sort order will be
-    # determined by mapping the items through the given block to obtain sort keys,
-    # and then sorting the keys according to their natural sort order.
+    # Return a new `List` with the same items, but sorted. The sort order is
+    # determined by mapping the items through the given block to obtain sort
+    # keys, and then sorting the keys according to their natural sort order
+    # (`#<=>`).
+    #
+    # @yield [element] Once for each element.
+    # @yieldreturn a sort key object for the yielded element.
+    # @example
+    #   Hamster::List["Elephant", "Dog", "Lion"].sort_by { |e| e.size }
+    #   # => Hamster::List["Dog", "Lion", "Elephant"]
     #
     # @return [List]
     def sort_by(&transformer)
       return sort unless block_given?
-      LazyList.new { super(&transformer).to_list }
+      LazyList.new { List.from_enum(super(&transformer)) }
     end
 
     # Return a new `List` with `sep` inserted between each of the existing elements.
     #
     # @example
-    #   Hamster.list('one', 'two', 'three').intersperse(' ')
-    #   # => Hamster::List['one', ' ', 'two', ' ', 'three']
+    #   Hamster::List["one", "two", "three"].intersperse(" ")
+    #   # => Hamster::List["one", " ", "two", " ", "three"]
     #
     # @return [List]
     def intersperse(sep)
@@ -462,35 +591,62 @@ module Hamster
       end
     end
 
-    # Return a lazy list with the same items, but all duplicates removed.
+    # Return a `List` with the same items, but all duplicates removed.
     # Use `#hash` and `#eql?` to determine which items are duplicates.
     #
+    # @example
+    #   Hamster::List[:a, :b, :a, :c, :b].uniq      # => Hamster::List[:a, :b, :c]
+    #   Hamster::List["a", "A", "b"].uniq(&:upcase) # => Hamster::List["a", "b"]
+    #
     # @return [List]
-    def uniq(items = ::Set.new)
-      LazyList.new do
-        next self if empty?
-        next tail.uniq(items) if items.include?(head)
-        Cons.new(head, tail.uniq(items.add(head)))
+    def uniq(&block)
+      _uniq(::Set.new, &block)
+    end
+
+    # @private
+    # Separate from `uniq` so as not to expose `items` in the public API.
+    def _uniq(items, &block)
+      if block_given?
+        LazyList.new do
+          next self if empty?
+          if items.add?(block.call(head))
+            Cons.new(head, tail._uniq(items, &block))
+          else
+            tail._uniq(items, &block)
+          end
+        end
+      else
+        LazyList.new do
+          next self if empty?
+          next tail._uniq(items) if items.include?(head)
+          Cons.new(head, tail._uniq(items.add(head)))
+        end
       end
     end
-    def_delegator :self, :uniq, :nub
-    def_delegator :self, :uniq, :remove_duplicates
+    protected :_uniq
 
     # Return a `List` with all the elements from both this list and `other`,
     # with all duplicates removed.
     #
+    # @example
+    #   Hamster::List[1, 2].union(Hamster::List[2, 3]) # => Hamster::List[1, 2, 3]
+    #
     # @param other [List] The list to merge with
     # @return [List]
     def union(other, items = ::Set.new)
       LazyList.new do
-        next other.uniq(items) if empty?
+        next other._uniq(items) if empty?
         next tail.union(other, items) if items.include?(head)
         Cons.new(head, tail.union(other, items.add(head)))
       end
     end
-    def_delegator :self, :union, :|
+    alias :| :union
 
-    # Return a lazy list with all elements except the last one.
+    # Return a `List` with all elements except the last one.
+    #
+    # @example
+    #   Hamster::List["a", "b", "c"].init # => Hamster::List["a", "b"]
+    #
     # @return [List]
     def init
       return EmptyList if tail.empty?
@@ -505,10 +661,10 @@ module Hamster
       list.head
     end
 
-    # Return a lazy list of all suffixes of this list.
+    # Return a `List` of all suffixes of this list.
     #
     # @example
-    #   Hamster.list(1,2,3).tails
+    #   Hamster::List[1,2,3].tails
     #   # => Hamster::List[
     #   #      Hamster::List[1, 2, 3],
     #   #      Hamster::List[2, 3],
@@ -522,10 +678,10 @@ module Hamster
       end
     end
 
-    # Return a lazy list of all prefixes of this list.
+    # Return a `List` of all prefixes of this list.
     #
     # @example
-    #   Hamster.list(1,2,3).inits
+    #   Hamster::List[1,2,3].inits
     #   # => Hamster::List[
     #   #      Hamster::List[1],
     #   #      Hamster::List[1, 2],
@@ -535,14 +691,14 @@ module Hamster
     def inits
       LazyList.new do
         next self if empty?
-        Cons.new(Hamster.list(head), tail.inits.map { |list| list.cons(head) })
+        Cons.new(List[head], tail.inits.map { |list| list.cons(head) })
       end
     end
 
-    # Return a lazy list of all combinations of length `n` of items from this `List`.
+    # Return a `List` of all combinations of length `n` of items from this `List`.
     #
     # @example
-    #   Hamster.list(1,2,3).combination(2)
+    #   Hamster::List[1,2,3].combination(2)
     #   # => Hamster::List[
     #   #      Hamster::List[1, 2],
     #   #      Hamster::List[1, 3],
@@ -558,6 +714,14 @@ module Hamster
     end
 
     # Split the items in this list in groups of `number`. Return a list of lists.
+    #
+    # @example
+    #   ("a".."o").to_list.chunk(5)
+    #   # => Hamster::List[
+    #   #      Hamster::List["a", "b", "c", "d", "e"],
+    #   #      Hamster::List["f", "g", "h", "i", "j"],
+    #   #      Hamster::List["k", "l", "m", "n", "o"]]
+    #
     # @return [List]
     def chunk(number)
       LazyList.new do
@@ -568,19 +732,26 @@ module Hamster
     end
 
     # Split the items in this list in groups of `number`, and yield each group
-    # to the block (as a `List`).
-    # @return [self]
+    # to the block (as a `List`). If no block is given, returns an
+    # `Enumerator`.
+    #
+    # @return [self, Enumerator]
+    # @yield [list] Once for each chunk.
     def each_chunk(number, &block)
       return enum_for(:each_chunk, number) unless block_given?
       chunk(number).each(&block)
       self
     end
-    def_delegator :self, :each_chunk, :each_slice
+    alias :each_slice :each_chunk
 
     # Return a new `List` with all nested lists recursively "flattened out",
     # that is, their elements inserted into the new `List` in the place where
     # the nested list originally was.
     #
+    # @example
+    #   Hamster::List[Hamster::List[1, 2], Hamster::List[3, 4]].flatten
+    #   # => Hamster::List[1, 2, 3, 4]
+    #
     # @return [List]
     def flatten
       LazyList.new do
@@ -595,10 +766,17 @@ module Hamster
     # for which the block returned that value.
     #
     # @return [Hash]
+    # @yield [item]
+    # @example
+    #    Hamster::List["a", "b", "ab"].group_by { |e| e.size }
+    #    # Hamster::Hash[
+    #    #   1 => Hamster::List["b", "a"],
+    #    #   2 => Hamster::List["ab"]
+    #    # ]
     def group_by(&block)
       group_by_with(EmptyList, &block)
     end
-    def_delegator :self, :group_by, :group
+    alias :group :group_by
 
     # Retrieve the item at `index`. Negative indices count back from the end of
     # the list (-1 is the last item). If `index` is invalid (either too high or
@@ -617,22 +795,47 @@ module Hamster
       node.head
     end
 
-    # Element reference. Return the item at a specific index, or a specified,
-    # contiguous range of items (as a new list).
+    # Return specific objects from the `List`. All overloads return `nil` if
+    # the starting index is out of range.
+    #
+    # @overload list.slice(index)
+    #   Returns a single object at the given `index`. If `index` is negative,
+    #   count backwards from the end.
+    #
+    #   @param index [Integer] The index to retrieve. May be negative.
+    #   @return [Object]
+    #   @example
+    #     l = Hamster::List["A", "B", "C", "D", "E", "F"]
+    #     l[2]  # => "C"
+    #     l[-1] # => "F"
+    #     l[6]  # => nil
     #
-    # @overload list[index]
-    #   Return the item at `index`.
-    #   @param index [Integer] The index to retrieve.
-    # @overload list[start, length]
-    #   Return a sublist starting at index `start` and continuing for `length` elements.
-    #   @param start [Integer] The index to start retrieving items from.
+    # @overload list.slice(index, length)
+    #   Return a sublist starting at `index` and continuing for `length`
+    #   elements or until the end of the `List`, whichever occurs first.
+    #
+    #   @param start [Integer] The index to start retrieving items from. May be
+    #                          negative.
     #   @param length [Integer] The number of items to retrieve.
-    # @overload list[range]
-    #   Return a sublist specified by the given `range` of indices.
-    #   @param range [Range] The range of indices to retrieve.
+    #   @return [List]
+    #   @example
+    #     l = Hamster::List["A", "B", "C", "D", "E", "F"]
+    #     l[2, 3]  # => Hamster::List["C", "D", "E"]
+    #     l[-2, 3] # => Hamster::List["E", "F"]
+    #     l[20, 1] # => nil
     #
-    # @return [Object]
-    def [](arg, length = (missing_length = true))
+    # @overload list.slice(index..end)
+    #   Return a sublist starting at `index` and continuing to index
+    #   `end` or the end of the `List`, whichever occurs first.
+    #
+    #   @param range [Range] The range of indices to retrieve.
+    #   @return [Vector]
+    #   @example
+    #     l = Hamster::List["A", "B", "C", "D", "E", "F"]
+    #     l[2..3]    # => Hamster::List["C", "D"]
+    #     l[-2..100] # => Hamster::List["E", "F"]
+    #     l[20..21]  # => nil
+    def slice(arg, length = (missing_length = true))
       if missing_length
         if arg.is_a?(Range)
           from, to = arg.begin, arg.end
@@ -665,18 +868,35 @@ module Hamster
         list.take(length)
       end
     end
-    def_delegator :self, :[], :slice
+    alias :[] :slice
 
-    # Pass each item successively to the block, and return a `List` of indices where
-    # the block returns true.
+    # Return a `List` of indices of matching objects.
+    #
+    # @overload indices(object)
+    #   Return a `List` of indices where `object` is found. Use `#==` for
+    #   testing equality.
+    #
+    #   @example
+    #     Hamster::List[1, 2, 3, 4].indices(2)
+    #     # => Hamster::List[1]
+    #
+    # @overload indices
+    #   Pass each item successively to the block. Return a list of indices
+    #   where the block returns true.
+    #
+    #   @yield [item]
+    #   @example
+    #     Hamster::List[1, 2, 3, 4].indices { |e| e.even? }
+    #     # => Hamster::List[1, 3]
     #
     # @return [List]
-    def find_indices(i = 0, &block)
-      return EmptyList if empty? || !block_given?
+    def indices(object = Undefined, i = 0, &block)
+      return indices { |item| item == object } if not block_given?
+      return EmptyList if empty?
       LazyList.new do
         node = self
         while true
-          break Cons.new(i, node.tail.find_indices(i + 1, &block)) if yield(node.head)
+          break Cons.new(i, node.tail.indices(Undefined, i + 1, &block)) if yield(node.head)
           node = node.tail
           break EmptyList if node.empty?
           i += 1
@@ -684,42 +904,25 @@ module Hamster
       end
     end
 
-    # Return a `List` of indices where `object` is found. Use `#==` for testing equality.
-    #
-    # @param object [Object] The object to search for
-    # @return [List]
-    def elem_indices(object)
-      find_indices { |item| item == object }
-    end
-
-    # Return a `List` of indices where the given object is found, or where the given
-    # block returns true.
-    #
-    # @overload indices(obj)
-    #   Return a `List` of indices where `obj` is found. Use `#==` for testing equality.
-    # @overload indices { |item| ... }
-    #   Pass each item successively to the block. Return a list of indices where the
-    #   block returns true.
-    #
-    # @return [List]
-    def indices(object = Undefined, &block)
-      return elem_indices(object) unless object.equal?(Undefined)
-      find_indices(&block)
-    end
-
     # Merge all the nested lists into a single list, using the given comparator
     # block to determine the order which items should be shifted out of the nested
-    # lists and into the output list. The comparator should take 2 parameters and
-    # return 0, 1, or -1 if the first parameter is (respectively) equal to, greater
-    # than, or less than the second parameter. Whichever nested list's `#head` is
-    # determined to be "lowest" according to the comparator will be the first in
-    # the merged `List`.
+    # lists and into the output list.
+    #
+    # @example
+    #   list_1 = Hamster::List[1, -3, -5]
+    #   list_2 = Hamster::List[-2, 4, 6]
+    #   Hamster::List[list_1, list_2].merge { |a,b| a.abs <=> b.abs }
+    #   # => Hamster::List[1, -2, -3, 4, -5, 6]
     #
     # @return [List]
+    # @yield [a, b] Pairs of items from matching indices in each list.
+    # @yieldreturn [Integer] Negative if the first element should be selected
+    #                        first, positive if the latter element, or zero if
+    #                        either.
     def merge(&comparator)
       return merge_by unless block_given?
       LazyList.new do
-        sorted = remove(&:empty?).sort do |a, b|
+        sorted = reject(&:empty?).sort do |a, b|
           yield(a.head, b.head)
         end
         next EmptyList if sorted.empty?
@@ -733,11 +936,19 @@ module Hamster
     # list. Whichever nested list's `#head` has the "lowest" sort key (according to
     # their natural order) will be the first in the merged `List`.
     #
+    # @example
+    #   list_1 = Hamster::List[1, -3, -5]
+    #   list_2 = Hamster::List[-2, 4, 6]
+    #   Hamster::List[list_1, list_2].merge_by { |x| x.abs }
+    #   # => Hamster::List[1, -2, -3, 4, -5, 6]
+    #
     # @return [List]
+    # @yield [item] Once for each item in either list.
+    # @yieldreturn [Object] A sort key for the element.
     def merge_by(&transformer)
       return merge_by { |item| item } unless block_given?
       LazyList.new do
-        sorted = remove(&:empty?).sort_by do |list|
+        sorted = reject(&:empty?).sort_by do |list|
           yield(list.head)
         end
         next EmptyList if sorted.empty?
@@ -753,12 +964,15 @@ module Hamster
 
     # Return a new `List` with the given items inserted before the item at `index`.
     #
+    # @example
+    #   Hamster::List["A", "D", "E"].insert(1, "B", "C") # => Hamster::List["A", "B", "C", "D", "E"]
+    #
     # @param index [Integer] The index where the new items should go
     # @param items [Array] The items to add
     # @return [List]
     def insert(index, *items)
       if index == 0
-        return items.to_list.append(self)
+        return List.from_enum(items).append(self)
       elsif index > 0
         LazyList.new do
           Cons.new(head, tail.insert(index-1, *items))
@@ -769,8 +983,12 @@ module Hamster
       end
     end
 
-    # Return a lazy list with all elements equal to `obj` removed. `#==` is used
+    # Return a `List` with all elements equal to `obj` removed. `#==` is used
     # for testing equality.
+    #
+    # @example
+    #   Hamster::List[:a, :b, :a, :a, :c].delete(:a) # => Hamster::List[:b, :c]
+    #
     # @param obj [Object] The object to remove.
     # @return [List]
     def delete(obj)
@@ -780,9 +998,13 @@ module Hamster
       LazyList.new { Cons.new(list.head, list.tail.delete(obj)) }
     end
 
-    # Return a lazy list containing the same items, minus the one at `index`.
+    # Return a `List` containing the same items, minus the one at `index`.
     # If `index` is negative, it counts back from the end of the list.
     #
+    # @example
+    #   Hamster::List[1, 2, 3].delete_at(1)  # => Hamster::List[1, 3]
+    #   Hamster::List[1, 2, 3].delete_at(-1) # => Hamster::List[1, 2]
+    #
     # @param index [Integer] The index of the item to remove
     # @return [List]
     def delete_at(index)
@@ -799,16 +1021,40 @@ module Hamster
 
     # Replace a range of indexes with the given object.
     #
-    # @overload fill(obj)
-    #   Return a new `List` of the same size, with every item set to `obj`.
-    # @overload fill(obj, start)
-    #   Return a new `List` with all indexes from `start` to the end of the
-    #   list set to `obj`.
-    # @overload fill(obj, start, length)
-    #   Return a new `List` with `length` indexes, beginning from `start`,
-    #   set to `obj`.
+    # @overload fill(object)
+    #   Return a new `List` of the same size, with every index set to `object`.
+    #
+    #   @param [Object] object Fill value.
+    #   @example
+    #     Hamster::List["A", "B", "C", "D", "E", "F"].fill("Z")
+    #     # => Hamster::List["Z", "Z", "Z", "Z", "Z", "Z"]
+    #
+    # @overload fill(object, index)
+    #   Return a new `List` with all indexes from `index` to the end of the
+    #   vector set to `obj`.
+    #
+    #   @param [Object] object Fill value.
+    #   @param [Integer] index Starting index. May be negative.
+    #   @example
+    #     Hamster::List["A", "B", "C", "D", "E", "F"].fill("Z", 3)
+    #     # => Hamster::List["A", "B", "C", "Z", "Z", "Z"]
+    #
+    # @overload fill(object, index, length)
+    #   Return a new `List` with `length` indexes, beginning from `index`,
+    #   set to `obj`. Expands the `List` if `length` would extend beyond the
+    #   current length.
+    #
+    #   @param [Object] object Fill value.
+    #   @param [Integer] index Starting index. May be negative.
+    #   @param [Integer] length
+    #   @example
+    #     Hamster::List["A", "B", "C", "D", "E", "F"].fill("Z", 3, 2)
+    #     # => Hamster::List["A", "B", "C", "Z", "Z", "F"]
+    #     Hamster::List["A", "B"].fill("Z", 1, 5)
+    #     # => Hamster::List["A", "Z", "Z", "Z", "Z", "Z"]
     #
     # @return [List]
+    # @raise [IndexError] if index is out of negative range.
     def fill(obj, index = 0, length = nil)
       if index == 0
         length ||= size
@@ -837,7 +1083,17 @@ module Hamster
     #
     # If no block is given, an `Enumerator` is returned instead.
     #
+    # @example
+    #   Hamster::List[1, 2, 3].permutation.to_a
+    #   # => [Hamster::List[1, 2, 3],
+    #   #     Hamster::List[2, 1, 3],
+    #   #     Hamster::List[2, 3, 1],
+    #   #     Hamster::List[1, 3, 2],
+    #   #     Hamster::List[3, 1, 2],
+    #   #     Hamster::List[3, 2, 1]]
+    #
     # @return [self, Enumerator]
+    # @yield [list] Once for each permutation.
     def permutation(length = size, &block)
       return enum_for(:permutation, length) if not block_given?
       if length == 0
@@ -863,7 +1119,7 @@ module Hamster
     # counts as one sublist.)
     #
     # @example
-    #   Hamster.list(1, 2, 3).subsequences { |list| p list }
+    #   Hamster::List[1, 2, 3].subsequences { |list| p list }
     #   # prints:
     #   # Hamster::List[1]
     #   # Hamster::List[1, 2]
@@ -885,10 +1141,15 @@ module Hamster
       self
     end
 
-    # Return 2 `List`s, the first containing all the elements for which the block
-    # evaluates to true, the second containing the rest.
+    # Return two `List`s, the first containing all the elements for which the
+    # block evaluates to true, the second containing the rest.
+    #
+    # @example
+    #   Hamster::List[1, 2, 3, 4, 5, 6].partition { |x| x.even? }
+    #   # => [Hamster::List[2, 4, 6], Hamster::List[1, 3, 5]]
     #
     # @return [List]
+    # @yield [item] Once for each item.
     def partition(&block)
       return enum_for(:partition) if not block_given?
       partitioner = Partitioner.new(self, block)
@@ -920,12 +1181,13 @@ module Hamster
       reduce(0) { |hash, item| (hash << 5) - hash + item.hash }
     end
 
-    # Return `self`.
+    # Return `self`. Since this is an immutable object duplicates are
+    # equivalent.
     # @return [List]
     def dup
       self
     end
-    def_delegator :self, :dup, :clone
+    alias :clone :dup
 
     # Return `self`.
     # @return [List]
@@ -971,13 +1233,21 @@ module Hamster
 
     private
 
+    # Perform compositions of `car` and `cdr` operations (traditional shorthand
+    # for `head` and `tail` respectively). Their names consist of a `c`,
+    # followed by at least one `a` or `d`, and finally an `r`. The series of
+    # `a`s and `d`s in the method name identify the series of `car` and `cdr`
+    # operations performed, in inverse order.
+    #
+    # @return [Object, List]
+    # @example
+    #   l = Hamster::List[nil, Hamster::List[1]]
+    #   l.car   # => nil
+    #   l.cdr   # => Hamster::List[Hamster::List[1]]
+    #   l.cadr  # => Hamster::List[1]
+    #   l.caadr # => 1
     def method_missing(name, *args, &block)
       if name.to_s.match(CADR)
-        # Perform compositions of car and cdr operations. Their names consist of a 'c',
-        # followed by at least one 'a' or 'd', and finally an 'r'. The series of 'a's and
-        # 'd's in the method name identify the series of car and cdr operations performed.
-        # The order in which the 'a's and 'd's appear is the inverse of the order in which
-        # the corresponding operations are performed.
         code = "def #{name}; self."
         code << Regexp.last_match[1].reverse.chars.map do |char|
           {'a' => 'head', 'd' => 'tail'}[char]
@@ -1020,6 +1290,7 @@ module Hamster
     def size
       @size ||= super
     end
+    alias :length :size
 
     def cached_size?
       @size != nil
@@ -1031,7 +1302,7 @@ module Hamster
   # only called) when one of these operations is performed.
   #
   # By returning a `Cons` that in turn has a {LazyList} as its tail, one can
-  # construct infinite lazy lists.
+  # construct infinite `List`s.
   #
   # @private
   class LazyList
@@ -1040,7 +1311,7 @@ module Hamster
     def initialize(&block)
       @head   = block # doubles as storage for block while yet unrealized
       @tail   = nil
-      @atomic = Atomic.new(0) # haven't yet run block
+      @atomic = Concurrent::Atomic.new(0) # haven't yet run block
       @size   = nil
     end
 
@@ -1048,6 +1319,7 @@ module Hamster
       realize if @atomic.get != 2
       @head
     end
+    alias :first :head
 
     def tail
       realize if @atomic.get != 2
@@ -1062,6 +1334,7 @@ module Hamster
     def size
       @size ||= super
     end
+    alias :length :size
 
     def cached_size?
       @size != nil
@@ -1106,7 +1379,7 @@ module Hamster
     end
   end
 
-  # Common behavior for other classes which implement various kinds of lazy lists
+  # Common behavior for other classes which implement various kinds of `List`s
   # @private
   class Realizable
     include List
@@ -1119,6 +1392,7 @@ module Hamster
       realize if @head == Undefined
       @head
     end
+    alias :first :head
 
     def tail
       realize if @tail == Undefined
@@ -1133,6 +1407,7 @@ module Hamster
     def size
       @size ||= super
     end
+    alias :length :size
 
     def cached_size?
       @size != nil
@@ -1143,7 +1418,7 @@ module Hamster
     end
   end
 
-  # This class can divide a collection into 2 lazy lists, one of items
+  # This class can divide a collection into 2 `List`s, one of items
   #   for which the block returns true, and another for false
   # At the same time, it guarantees the block will only be called ONCE for each item
   #
@@ -1167,7 +1442,7 @@ module Hamster
     end
   end
 
-  # One of the lazy lists which gets its items from a Partitioner
+  # One of the `List`s which gets its items from a Partitioner
   # @private
   class Partitioned < Realizable
     def initialize(partitioner, buffer, mutex)
@@ -1176,7 +1451,9 @@ module Hamster
     end
 
     def realize
-      @mutex.synchronize do
+      # another thread may get ahead of us and null out @mutex
+      mutex = @mutex
+      mutex && mutex.synchronize do
         return if @head != Undefined # another thread got ahead of us
         while true
           if !@buffer.empty?
@@ -1198,9 +1475,10 @@ module Hamster
     end
   end
 
-  # This class can divide a list up into 2 lazy lists, one for the prefix of elements
-  #   for which the block returns true, and another for all the elements after that
-  # It guarantees that the block will only be called ONCE for each item
+  # This class can divide a list up into 2 `List`s, one for the prefix of
+  # elements for which the block returns true, and another for all the elements
+  # after that. It guarantees that the block will only be called ONCE for each
+  # item
   #
   # @private
   class Splitter
@@ -1226,6 +1504,7 @@ module Hamster
       @list.empty?
     end
 
+    # @private
     class Left < Realizable
       def initialize(splitter, buffer, mutex)
         super()
@@ -1233,7 +1512,9 @@ module Hamster
       end
 
       def realize
-        @mutex.synchronize do
+        # another thread may get ahead of us and null out @mutex
+        mutex = @mutex
+        mutex && mutex.synchronize do
           return if @head != Undefined # another thread got ahead of us
           while true
             if !@buffer.empty?
@@ -1253,6 +1534,7 @@ module Hamster
       end
     end
 
+    # @private
     class Right < Realizable
       def initialize(splitter, mutex)
         super()
@@ -1260,7 +1542,8 @@ module Hamster
       end
 
       def realize
-        @mutex.synchronize do
+        mutex = @mutex
+        mutex && mutex.synchronize do
           return if @head != Undefined
           @splitter.next_item until @splitter.done?
           if @splitter.right.empty?
@@ -1275,7 +1558,7 @@ module Hamster
   end
 
   # A list without any elements. This is a singleton, since all empty lists are equivalent.
-  #
+  # @private
   module EmptyList
     class << self
       include List
@@ -1285,6 +1568,7 @@ module Hamster
       def head
         nil
       end
+      alias :first :head
 
       # There are no subsequent elements, so return an empty list.
       # @return [self]
@@ -1301,10 +1585,11 @@ module Hamster
       def size
         0
       end
+      alias :length :size
 
       def cached_size?
         true
       end
     end
   end
-end
+end.freeze