hamster 1.0.1.pre.rc3 → 2.0.0

data/lib/hamster/experimental/mutable_set.rb

@@ -1,20 +1,19 @@
-require "forwardable"
 require "hamster/set"
 require "hamster/read_copy_update"
 
 module Hamster
-  def self.mutable_set(*items)
-    MutableSet.new(set(*items))
-  end
-
+  # @api private
   class MutableSet
-    extend Forwardable
     include ReadCopyUpdate
 
+    def self.[](*items)
+      MutableSet.new(Set[*items])
+    end
+
     def add(item)
       transform { |set| set.add(item) }
     end
-    def_delegator :self, :add, :<<
+    alias :<< :add
 
     def add?(item)
       added = false

data/lib/hamster/hash.rb

@@ -1,83 +1,76 @@
-require "forwardable"
-
 require "hamster/immutable"
 require "hamster/undefined"
+require "hamster/enumerable"
 require "hamster/trie"
 require "hamster/set"
 require "hamster/vector"
+require "hamster/associable"
 
 module Hamster
-  def self.hash(pairs = nil, &block)
-    (pairs.nil? && block.nil?) ? EmptyHash : Hash.new(pairs, &block)
-  end
-
-  # A `Hamster::Hash` maps from a set of unique keys to corresponding values,
-  # much like a dictionary maps from words to definitions. Given a key, it can
-  # efficiently store and retrieve values. Looking up a key given its value is also
-  # possible, but less efficient. If an existing key is stored again, the new value
-  # will replace that which was previously stored.
+  # A `Hamster::Hash` maps a set of unique keys to corresponding values, much
+  # like a dictionary maps from words to definitions. Given a key, it can store
+  # and retrieve an associated value in constant time. If an existing key is
+  # stored again, the new value will replace the old. It behaves much like
+  # Ruby's built-in Hash, which we will call RubyHash for clarity. Like
+  # RubyHash, two keys that are `#eql?` to each other and have the same
+  # `#hash` are considered identical in a `Hamster::Hash`.
   #
-  # It behaves much like Ruby's built-in Hash, which we will call RubyHash
-  # for clarity. Like RubyHash, `Hamster::Hash` uses `#hash` and `#eql?` to define
-  # equality between keys. Keys with the same `#hash` code, but which are not `#eql?`
-  # to each other, can coexist in the same `Hamster::Hash`. To retrieve a previously
-  # stored value, the key provided must have the same `#hash` code and be `#eql?`
-  # to the one used for storage.
+  # A `Hamster::Hash` can be created in a couple of ways:
   #
-  # A `Hamster::Hash` can be created in several ways:
-  #
-  #     Hamster.hash('Jane Doe' => 10, 'Jim Doe' => 6)
   #     Hamster::Hash.new(font_size: 10, font_family: 'Arial')
   #     Hamster::Hash[first_name: 'John', last_name: 'Smith']
   #
-  # If you want to write your own class which inherits from `Hamster::Hash`, you can
-  # use either of the latter 2 forms of initialization.
-  #
-  # Note that any `Enumerable` object which yields 2-element `[key, value]` arrays
-  # can be used to initialize a `Hamster::Hash`. So this is also possible:
+  # Any `Enumerable` object which yields two-element `[key, value]` arrays
+  # can be used to initialize a `Hamster::Hash`:
   #
   #     Hamster::Hash.new([[:first_name, 'John'], [:last_name, 'Smith']])
   #
-  # Like RubyHash, key/value pairs can be added using {#store}. Unlike RubyHash,
-  # a new hash is returned, and the existing one is left unchanged:
+  # Key/value pairs can be added using {#put}. A new hash is returned and the
+  # existing one is left unchanged:
   #
   #     hash = Hamster::Hash[a: 100, b: 200]
-  #     hash.store(:c, 500) # => Hamster::Hash[:a => 100, :b => 200, :c => 500]
-  #     hash # => Hamster::Hash[:a => 100, :b => 200]
+  #     hash.put(:c, 500) # => Hamster::Hash[:a => 100, :b => 200, :c => 500]
+  #     hash              # => Hamster::Hash[:a => 100, :b => 200]
   #
-  # You also use {#put}. The difference is that {#put} can optionally take a block which
-  # is used to calculate the value to be stored:
+  # {#put} can also take a block, which is used to calculate the value to be
+  # stored.
   #
-  #     hash.put(:a) { hash[:b] + 100 } # => Hamster::Hash[:a => 300, :b => 200]
+  #     hash.put(:a) { |current| current + 200 } # => Hamster::Hash[:a => 300, :b => 200]
   #
-  # Since it is immutable, all methods which you might expect to "modify" a `Hamster::Hash`
-  # actually return a new hash and leave the existing one unchanged. This means that the
-  # `hash[key] = value` syntax used with RubyHashes *cannot* be used with `Hamster::Hash`.
+  # Since it is immutable, all methods which you might expect to "modify" a
+  # `Hamster::Hash` actually return a new hash and leave the existing one
+  # unchanged. This means that the `hash[key] = value` syntax from RubyHash
+  # *cannot* be used with `Hamster::Hash`.
   #
-  # While a `Hamster::Hash` can iterate over its keys (or values), it does not
-  # guarantee any specific iteration order (unlike RubyHash). Likewise, methods like
-  # {#flatten} do not guarantee which order the returned key/value pairs will appear
-  # in.
+  # Nested data structures can easily be updated using {#update_in}:
   #
-  # Like RubyHash, a `Hamster::Hash` can have a default block which is used when
-  # looking up a key which does not exist in the hash. Unlike RubyHash, the default
-  # block will only be passed the missing key, not the hash itself:
+  #     hash = Hamster::Hash["a" => Hamster::Vector[Hamster::Hash["c" => 42]]]
+  #     hash.update_in("a", 0, "c") { |value| value + 5 }
+  #     # => Hamster::Hash["a" => Hamster::Hash["b" => Hamster::Hash["c" => 47]]]
   #
-  #     hash = Hamster::Hash.new { |n| n * 10 }
-  #     hash[5] # => 50
+  # While a `Hamster::Hash` can iterate over its keys or values, it does not
+  # guarantee any specific iteration order (unlike RubyHash). Methods like
+  # {#flatten} do not guarantee the order of returned key/value pairs.
   #
-  # A default block can only be set when creating a `Hamster::Hash` with `Hamster::Hash.new` or
-  # {Hamster.hash Hamster.hash}, not with {Hamster::Hash.[] Hamster::Hash[]}. Default blocks
-  # do not survive marshalling and unmarshalling.
+  # Like RubyHash, a `Hamster::Hash` can have a default block which is used
+  # when looking up a key that does not exist. Unlike RubyHash, the default
+  # block will only be passed the missing key, without the hash itself:
   #
+  #     hash = Hamster::Hash.new { |missing_key| missing_key * 10 }
+  #     hash[5] # => 50
   class Hash
-    extend Forwardable
     include Immutable
     include Enumerable
+    include Associable
 
     class << self
       # Create a new `Hash` populated with the given key/value pairs.
       #
+      # @example
+      #   Hamster::Hash["A" => 1, "B" => 2] # => Hamster::Hash["A" => 1, "B" => 2]
+      #   Hamster::Hash[["A", 1], ["B", 2]] # => Hamster::Hash["A" => 1, "B" => 2]
+      #
+      # @param pairs [::Enumerable] initial content of hash. An empty hash is returned if not provided.
       # @return [Hash]
       def [](pairs = nil)
         (pairs.nil? || pairs.empty?) ? empty : new(pairs)
@@ -104,6 +97,9 @@ module Hamster
       end
     end
 
+    # @param pairs [::Enumerable] initial content of hash. An empty hash is returned if not provided.
+    # @yield [key] Optional _default block_ to be stored and used to calculate the default value of a missing key. It will not be yielded during this method. It will not be preserved when marshalling.
+    # @yieldparam key Key that was not present in the hash.
     def initialize(pairs = nil, &block)
       @trie = pairs ? Trie[pairs] : EmptyTrie
       @default = block
@@ -118,11 +114,14 @@ module Hamster
 
     # Return the number of key/value pairs in this `Hash`.
     #
+    # @example
+    #   Hamster::Hash["A" => 1, "B" => 2, "C" => 3].size  # => 3
+    #
     # @return [Integer]
     def size
       @trie.size
     end
-    def_delegator :self, :size, :length
+    alias :length :size
 
     # Return `true` if this `Hash` contains no key/value pairs.
     #
@@ -130,34 +129,50 @@ module Hamster
     def empty?
       @trie.empty?
     end
-    def_delegator :self, :empty?, :null?
 
     # Return `true` if the given key object is present in this `Hash`. More precisely,
     # return `true` if a key with the same `#hash` code, and which is also `#eql?`
     # to the given key object is present.
     #
+    # @example
+    #   Hamster::Hash["A" => 1, "B" => 2, "C" => 3].key?("B")  # => true
+    #
     # @param key [Object] The key to check for
     # @return [Boolean]
     def key?(key)
       @trie.key?(key)
     end
-    def_delegator :self, :key?, :has_key?
-    def_delegator :self, :key?, :include?
-    def_delegator :self, :key?, :member?
+    alias :has_key? :key?
+    alias :include? :key?
+    alias :member?  :key?
 
     # Return `true` if this `Hash` has one or more keys which map to the provided value.
     #
+    # @example
+    #   Hamster::Hash["A" => 1, "B" => 2, "C" => 3].value?(2)  # => true
+    #
     # @param value [Object] The value to check for
     # @return [Boolean]
     def value?(value)
       each { |k,v| return true if value == v }
       false
     end
-    def_delegator :self, :value?, :has_value?
+    alias :has_value? :value?
 
     # Retrieve the value corresponding to the provided key object. If not found, and
     # this `Hash` has a default block, the default block is called to provide the
-    # value.
+    # value. Otherwise, return `nil`.
+    #
+    # @example
+    #   h = Hamster::Hash["A" => 1, "B" => 2, "C" => 3]
+    #   h["B"]             # => 2
+    #   h.get("B")         # => 2
+    #   h.get("Elephant")  # => nil
+    #
+    #   # Hamster Hash with a default proc:
+    #   h = Hamster::Hash.new("A" => 1, "B" => 2, "C" => 3) { |key| key.size }
+    #   h.get("B")         # => 2
+    #   h.get("Elephant")  # => 8
     #
     # @param key [Object] The key to look up
     # @return [Object]
@@ -169,7 +184,7 @@ module Hamster
         @default.call(key)
       end
     end
-    def_delegator :self, :get, :[]
+    alias :[] :get
 
     # Retrieve the value corresponding to the given key object, or use the provided
     # default value or block, or otherwise raise a `KeyError`.
@@ -190,6 +205,19 @@ module Hamster
     #   @param key [Object] The key to look up
     #   @param default [Object] Object to return if the key is not found
     #
+    # @example
+    #   h = Hamster::Hash["A" => 1, "B" => 2, "C" => 3]
+    #   h.fetch("B")         # => 2
+    #   h.fetch("Elephant")  # => KeyError: key not found: "Elephant"
+    #
+    #   # with a default value:
+    #   h.fetch("B", 99)         # => 2
+    #   h.fetch("Elephant", 99)  # => 99
+    #
+    #   # with a block:
+    #   h.fetch("B") { |key| key.size }         # => 2
+    #   h.fetch("Elephant") { |key| key.size }  # => 8
+    #
     # @return [Object]
     def fetch(key, default = Undefined)
       entry = @trie.get(key)
@@ -213,36 +241,70 @@ module Hamster
     # returns will replace the existing value. This is useful for "transforming"
     # the value associated with a certain key.
     #
-    # Avoid mutating objects which are used as keys. `String`s are an exception --
+    # Avoid mutating objects which are used as keys. `String`s are an exception:
     # unfrozen `String`s which are used as keys are internally duplicated and
-    # frozen.
+    # frozen. This matches RubyHash's behaviour.
+    #
+    # @example
+    #   h = Hamster::Hash["A" => 1, "B" => 2]
+    #   h.put("C", 3)
+    #   # => Hamster::Hash["A" => 1, "B" => 2, "C" => 3]
+    #   h.put("B") { |value| value * 10 }
+    #   # => Hamster::Hash["A" => 1, "B" => 20]
     #
     # @param key [Object] The key to store
     # @param value [Object] The value to associate it with
-    # @yield [value] The previously stored value
+    # @yield [value] The previously stored value, or `nil` if none.
     # @yieldreturn [Object] The new value to store
     # @return [Hash]
     def put(key, value = yield(get(key)))
-      self.class.alloc(@trie.put(key, value), @default)
+      new_trie = @trie.put(key, value)
+      if new_trie.equal?(@trie)
+        self
+      else
+        self.class.alloc(new_trie, @default)
+      end
     end
 
-    # Return a new `Hash` with the existing key/value associations, plus an association
-    # between the provided key and value. If an equivalent key is already present, its
-    # associated value will be replaced with the provided one.
+    # Return a new `Hash` with a deeply nested value modified to the result of
+    # the given code block.  When traversing the nested `Hash`es and `Vector`s,
+    # non-existing keys are created with empty `Hash` values.
     #
-    # Avoid mutating objects which are used as keys. `String`s are an exception --
-    # unfrozen `String`s which are used as keys are internally duplicated and
-    # frozen.
+    # The code block receives the existing value of the deeply nested key (or
+    # `nil` if it doesn't exist). This is useful for "transforming" the value
+    # associated with a certain key.
+    #
+    # Note that the original `Hash` and sub-`Hash`es and sub-`Vector`s are left
+    # unmodified; new data structure copies are created along the path wherever
+    # needed.
+    #
+    # @example
+    #   hash = Hamster::Hash["a" => Hamster::Hash["b" => Hamster::Hash["c" => 42]]]
+    #   hash.update_in("a", "b", "c") { |value| value + 5 }
+    #   # => Hamster::Hash["a" => Hamster::Hash["b" => Hamster::Hash["c" => 47]]]
+    #
+    # @param key_path [::Array<Object>] List of keys which form the path to the key to be modified
+    # @yield [value] The previously stored value
+    # @yieldreturn [Object] The new value to store
+    # @return [Hash]
+
+    # An alias for {#put} to match RubyHash's API. Does not support {#put}'s
+    # block form.
     #
+    # @see #put
     # @param key [Object] The key to store
     # @param value [Object] The value to associate it with
     # @return [Hash]
     def store(key, value)
-      self.class.alloc(@trie.put(key, value), @default)
+      put(key, value)
     end
 
-    # Return a new `Hash` with the association for `key` removed. If `key` is not
-    # present, return `self`.
+    # Return a new `Hash` with `key` removed. If `key` is not present, return
+    # `self`.
+    #
+    # @example
+    #   Hamster::Hash["A" => 1, "B" => 2, "C" => 3].delete("B")
+    #   # => Hamster::Hash["A" => 1, "C" => 3]
     #
     # @param key [Object] The key to remove
     # @return [Hash]
@@ -251,20 +313,38 @@ module Hamster
     end
 
     # Call the block once for each key/value pair in this `Hash`, passing the key/value
-    # pair as parameters. No specific iteration order is guaranteed (but the order will
-    # be stable for any particular `Hash`.)
+    # pair as parameters. No specific iteration order is guaranteed, though the order will
+    # be stable for any particular `Hash`.
     #
+    # @example
+    #   Hamster::Hash["A" => 1, "B" => 2, "C" => 3].each { |k, v| puts "k=#{k} v=#{v}" }
+    #
+    #   k=A v=1
+    #   k=C v=3
+    #   k=B v=2
+    #   # => Hamster::Hash["A" => 1, "B" => 2, "C" => 3]
+    #
+    # @yield [key, value] Once for each key/value pair.
     # @return [self]
     def each(&block)
       return to_enum if not block_given?
       @trie.each(&block)
       self
     end
-    def_delegator :self, :each, :each_pair
+    alias :each_pair :each
 
     # Call the block once for each key/value pair in this `Hash`, passing the key/value
     # pair as parameters. Iteration order will be the opposite of {#each}.
     #
+    # @example
+    #   Hamster::Hash["A" => 1, "B" => 2, "C" => 3].reverse_each { |k, v| puts "k=#{k} v=#{v}" }
+    #
+    #   k=B v=2
+    #   k=C v=3
+    #   k=A v=1
+    #   # => Hamster::Hash["A" => 1, "B" => 2, "C" => 3]
+    #
+    # @yield [key, value] Once for each key/value pair.
     # @return [self]
     def reverse_each(&block)
       return enum_for(:reverse_each) if not block_given?
@@ -273,8 +353,17 @@ module Hamster
     end
 
     # Call the block once for each key/value pair in this `Hash`, passing the key as a
-    # parameter.
+    # parameter. Ordering guarantees are the same as {#each}.
     #
+    # @example
+    #   Hamster::Hash["A" => 1, "B" => 2, "C" => 3].each_key { |k| puts "k=#{k}" }
+    #
+    #   k=A
+    #   k=C
+    #   k=B
+    #   # => Hamster::Hash["A" => 1, "B" => 2, "C" => 3]
+    #
+    # @yield [key] Once for each key/value pair.
     # @return [self]
     def each_key
       return enum_for(:each_key) if not block_given?
@@ -283,8 +372,17 @@ module Hamster
     end
 
     # Call the block once for each key/value pair in this `Hash`, passing the value as a
-    # parameter.
+    # parameter. Ordering guarantees are the same as {#each}.
+    #
+    # @example
+    #   Hamster::Hash["A" => 1, "B" => 2, "C" => 3].each_value { |v| puts "v=#{v}" }
     #
+    #   v=1
+    #   v=3
+    #   v=2
+    #   # => Hamster::Hash["A" => 1, "B" => 2, "C" => 3]
+    #
+    # @yield [value] Once for each key/value pair.
     # @return [self]
     def each_value
       return enum_for(:each_value) if not block_given?
@@ -296,48 +394,72 @@ module Hamster
     # pair as parameters. The block should return a `[key, value]` array each time.
     # All the returned `[key, value]` arrays will be gathered into a new `Hash`.
     #
+    # @example
+    #   h = Hamster::Hash["A" => 1, "B" => 2, "C" => 3]
+    #   h.map { |k, v| ["new-#{k}", v * v] }
+    #   # => Hash["new-C" => 9, "new-B" => 4, "new-A" => 1]
+    #
+    # @yield [key, value] Once for each key/value pair.
     # @return [Hash]
     def map
       return enum_for(:map) unless block_given?
       return self if empty?
       self.class.new(super, &@default)
     end
-    def_delegator :self, :map, :collect
-
-    def_delegator :self, :reduce, :foldr
+    alias :collect :map
 
     # Return a new `Hash` with all the key/value pairs for which the block returns true.
     #
+    # @example
+    #   h = Hamster::Hash["A" => 1, "B" => 2, "C" => 3]
+    #   h.select { |k, v| v >= 2 }
+    #   # => Hamster::Hash["B" => 2, "C" => 3]
+    #
+    # @yield [key, value] Once for each key/value pair.
+    # @yieldreturn Truthy if this pair should be present in the new `Hash`.
     # @return [Hash]
-    def filter(&block)
-      return enum_for(:filter) unless block_given?
-      derive_new_hash(@trie.filter(&block))
+    def select(&block)
+      return enum_for(:select) unless block_given?
+      derive_new_hash(@trie.select(&block))
     end
+    alias :find_all :select
+    alias :keep_if  :select
 
     # Yield `[key, value]` pairs until one is found for which the block returns true.
     # Return that `[key, value]` pair. If the block never returns true, return `nil`.
     #
+    # @example
+    #   h = Hamster::Hash["A" => 1, "B" => 2, "C" => 3]
+    #   h.find { |k, v| v.even? }
+    #   # => ["B", 2]
+    #
     # @return [Array]
+    # @yield [key, value] At most once for each key/value pair, until the block returns `true`.
+    # @yieldreturn Truthy to halt iteration and return the yielded key/value pair.
     def find
       return enum_for(:find) unless block_given?
       each { |entry| return entry if yield entry }
       nil
     end
-    def_delegator :self, :find, :detect
-
-    def_delegator :self, :max, :maximum
-    def_delegator :self, :min, :minimum
+    alias :detect :find
 
     # Return a new `Hash` containing all the key/value pairs from this `Hash` and
     # `other`. If no block is provided, the value for entries with colliding keys
-    # will be that from `other`. Otherwie, the value for each duplicate key is
-    # determined by called the block with the key, its value in this `Hash`, and
-    # its value in `other`.
+    # will be that from `other`. Otherwise, the value for each duplicate key is
+    # determined by calling the block.
     #
     # `other` can be a `Hamster::Hash`, a built-in Ruby `Hash`, or any `Enumerable`
     # object which yields `[key, value]` pairs.
     #
-    # @param other [Enumerable] The collection to merge with
+    # @example
+    #   h1 = Hamster::Hash["A" => 1, "B" => 2, "C" => 3]
+    #   h2 = Hamster::Hash["C" => 70, "D" => 80]
+    #   h1.merge(h2)
+    #   # => Hamster::Hash["C" => 70, "A" => 1, "D" => 80, "B" => 2]
+    #   h1.merge(h2) { |key, v1, v2| v1 + v2 }
+    #   # => Hamster::Hash["C" => 73, "A" => 1, "D" => 80, "B" => 2]
+    #
+    # @param other [::Enumerable] The collection to merge with
     # @yieldparam key [Object] The key which was present in both collections
     # @yieldparam my_value [Object] The associated value from this `Hash`
     # @yieldparam other_value [Object] The associated value from the other collection
@@ -353,17 +475,38 @@ module Hamster
           end
         end
       else
-        other.reduce(@trie) { |trie, (key, value)| trie.put(key, value) }
+        @trie.bulk_put(other)
       end
 
       derive_new_hash(trie)
     end
-    def_delegator :self, :merge, :+
 
-    # Return a {Vector} which contains all the `[key, value]` pairs in this `Hash`
-    # as 2-element Arrays, either in their natural sorted order as determined by
-    # `#<=>`, or if an optional block is supplied, by using the block as a comparator.
-    # See `Enumerable#sort`.
+    # Retrieve the value corresponding to the given key object, or use the provided
+    # default value or block, or otherwise raise a `KeyError`.
+    #
+    # @overload fetch(key)
+    #   Retrieve the value corresponding to the given key, or raise a `KeyError`
+    #   if it is not found.
+    #   @param key [Object] The key to look up
+    # @overload fetch(key) { |key| ... }
+
+    # Return a sorted {Vector} which contains all the `[key, value]` pairs in
+    # this `Hash` as two-element `Array`s.
+    #
+    # @overload sort
+    #   Uses `#<=>` to determine sorted order.
+    # @overload sort { |(k1, v1), (k2, v2)| ... }
+    #   Uses the block as a comparator to determine sorted order.
+    #
+    #   @example
+    #     h = Hamster::Hash["Dog" => 1, "Elephant" => 2, "Lion" => 3]
+    #     h.sort { |(k1, v1), (k2, v2)| k1.size  <=> k2.size }
+    #     # => Hamster::Vector[["Dog", 1], ["Lion", 3], ["Elephant", 2]]
+    #   @yield [(k1, v1), (k2, v2)] Any number of times with different pairs of key/value associations.
+    #   @yieldreturn [Integer] Negative if the first pair should be sorted
+    #                          lower, positive if the latter pair, or 0 if equal.
+    #
+    # @see ::Enumerable#sort
     #
     # @return [Vector]
     def sort
@@ -371,11 +514,19 @@ module Hamster
     end
 
     # Return a {Vector} which contains all the `[key, value]` pairs in this `Hash`
-    # as 2-element Arrays. The order which the pairs will appear in is determined by
+    # as two-element Arrays. The order which the pairs will appear in is determined by
     # passing each pair to the code block to obtain a sort key object, and comparing
     # the sort keys using `#<=>`.
-    # See `Enumerable#sort_by`.
     #
+    # @see ::Enumerable#sort_by
+    #
+    # @example
+    #   h = Hamster::Hash["Dog" => 1, "Elephant" => 2, "Lion" => 3]
+    #   h.sort_by { |key, value| key.size }
+    #   # => Hamster::Vector[["Dog", 1], ["Lion", 3], ["Elephant", 2]]
+    #
+    # @yield [key, value] Once for each key/value pair.
+    # @yieldreturn a sort key object for the yielded pair.
     # @return [Vector]
     def sort_by
       Vector.new(super)
@@ -383,6 +534,10 @@ module Hamster
 
     # Return a new `Hash` with the associations for all of the given `keys` removed.
     #
+    # @example
+    #   h = Hamster::Hash["A" => 1, "B" => 2, "C" => 3]
+    #   h.except("A", "C")  # => Hamster::Hash["B" => 2]
+    #
     # @param keys [Array] The keys to remove
     # @return [Hash]
     def except(*keys)
@@ -390,10 +545,12 @@ module Hamster
     end
 
     # Return a new `Hash` with only the associations for the `wanted` keys retained.
-    # If any of the `wanted` keys are not present in this `Hash`, they will not be present
-    # in the returned `Hash` either.
     #
-    # @param wanted [Array] The keys to retain
+    # @example
+    #   h = Hamster::Hash["A" => 1, "B" => 2, "C" => 3]
+    #   h.slice("B", "C")  # => Hamster::Hash["B" => 2, "C" => 3]
+    #
+    # @param wanted [::Enumerable] The keys to retain
     # @return [Hash]
     def slice(*wanted)
       trie = Trie.new(0)
@@ -404,6 +561,10 @@ module Hamster
     # Return a {Vector} of the values which correspond to the `wanted` keys.
     # If any of the `wanted` keys are not present in this `Hash`, they will be skipped.
     #
+    # @example
+    #   h = Hamster::Hash["A" => 1, "B" => 2, "C" => 3]
+    #   h.values_at("B", "A", "D")  # => Hamster::Vector[2, 1]
+    #
     # @param wanted [Array] The keys to retrieve
     # @return [Vector]
     def values_at(*wanted)
@@ -412,7 +573,11 @@ module Hamster
       Vector.new(array.freeze)
     end
 
-    # Return a new {Set} populated with the keys from this `Hash`.
+    # Return a new {Set} containing the keys from this `Hash`.
+    #
+    # @example
+    #   Hamster::Hash["A" => 1, "B" => 2, "C" => 3, "D" => 2].keys
+    #   # => Hamster::Set["D", "C", "B", "A"]
     #
     # @return [Set]
     def keys
@@ -421,14 +586,23 @@ module Hamster
 
     # Return a new {Vector} populated with the values from this `Hash`.
     #
+    # @example
+    #   Hamster::Hash["A" => 1, "B" => 2, "C" => 3, "D" => 2].values
+    #   # => Hamster::Vector[2, 3, 2, 1]
+    #
     # @return [Vector]
     def values
       Vector.new(each_value.to_a.freeze)
     end
 
-    # Return a new `Hash` created by using our keys as values, and values as keys.
+    # Return a new `Hash` created by using keys as values and values as keys.
     # If there are multiple values which are equivalent (as determined by `#hash` and
-    # `#eql?`), only one out of each group of equivalent values will be retained.
+    # `#eql?`), only one out of each group of equivalent values will be
+    # retained. Which one specifically is undefined.
+    #
+    # @example
+    #   Hamster::Hash["A" => 1, "B" => 2, "C" => 3, "D" => 2].invert
+    #   # => Hamster::Hash[1 => "A", 3 => "C", 2 => "B"]
     #
     # @return [Hash]
     def invert
@@ -447,6 +621,13 @@ module Hamster
     # As a special case, if `level` is 0, each `[key, value]` pair will be a
     # separate element in the returned {Vector}.
     #
+    # @example
+    #   h = Hamster::Hash["A" => 1, "B" => [2, 3, 4]]
+    #   h.flatten
+    #   # => Hamster::Vector["A", 1, "B", [2, 3, 4]]
+    #   h.flatten(2)
+    #   # => Hamster::Vector["A", 1, "B", 2, 3, 4]
+    #
     # @param level [Integer] The number of times to recursively flatten the `[key, value]` pairs in this `Hash`.
     # @return [Vector]
     def flatten(level = 1)
@@ -461,6 +642,9 @@ module Hamster
     # When a matching key is found, return the `[key, value]` pair as an array.
     # Return `nil` if no match is found.
     #
+    # @example
+    #   Hamster::Hash["A" => 1, "B" => 2, "C" => 3].assoc("B")  # => ["B", 2]
+    #
     # @param obj [Object] The key to search for (using #==)
     # @return [Array]
     def assoc(obj)
@@ -472,6 +656,9 @@ module Hamster
     # When a matching value is found, return the `[key, value]` pair as an array.
     # Return `nil` if no match is found.
     #
+    # @example
+    #   Hamster::Hash["A" => 1, "B" => 2, "C" => 3].rassoc(2)  # => ["B", 2]
+    #
     # @param obj [Object] The value to search for (using #==)
     # @return [Array]
     def rassoc(obj)
@@ -483,6 +670,9 @@ module Hamster
     # When a matching value is found, return its associated key object.
     # Return `nil` if no match is found.
     #
+    # @example
+    #   Hamster::Hash["A" => 1, "B" => 2, "C" => 3].key(2)  # => "B"
+    #
     # @param value [Object] The value to search for (using #==)
     # @return [Object]
     def key(value)
@@ -493,6 +683,10 @@ module Hamster
     # Return a randomly chosen `[key, value]` pair from this `Hash`. If the hash is empty,
     # return `nil`.
     #
+    # @example
+    #   Hamster::Hash["A" => 1, "B" => 2, "C" => 3].sample
+    #   # => ["C", 3]
+    #
     # @return [Array]
     def sample
       @trie.at(rand(size))
@@ -537,14 +731,10 @@ module Hamster
       end
     end
 
-    def_delegator :self, :dup, :uniq
-    def_delegator :self, :dup, :nub
-    def_delegator :self, :dup, :remove_duplicates
-
     # Return the contents of this `Hash` as a programmer-readable `String`. If all the
     # keys and values are serializable as Ruby literal strings, the returned string can
-    # be passed to `eval` to reconstitute an equivalent `Hash`. However, the default
-    # block (if there is one) will be lost when doing this.
+    # be passed to `eval` to reconstitute an equivalent `Hash`. The default
+    # block (if there is one) will be lost when doing this, however.
     #
     # @return [String]
     def inspect
@@ -590,7 +780,7 @@ module Hamster
       end
       output
     end
-    def_delegator :self, :to_hash, :to_h
+    alias :to_h :to_hash
 
     # @return [::Hash]
     # @private
@@ -623,9 +813,10 @@ module Hamster
     end
   end
 
-  # The canonical empty `Hash`. Returned by `Hamster.hash` and `Hash[]` when
+  # The canonical empty `Hash`. Returned by `Hash[]` when
   # invoked with no arguments; also returned by `Hash.empty`. Prefer using this
   # one rather than creating many empty hashes using `Hash.new`.
   #
+  # @private
   EmptyHash = Hamster::Hash.empty
 end