multiset 0.5.1 → 0.5.3

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    MDhmOWRlOWI0ZWUzY2NmZjc4NDQwOTE0MmFjYWVlNzFjOTVhNTJhMQ==
-  data.tar.gz: !binary |-
-    ZTg5YzE1NmQzYTYzM2I5ODAxMmIzMDdiMDI0ODI0YWJjMDhhYzMwZg==
+SHA1:
+  metadata.gz: a7c8af89e0f0f6799fffe4ded50e5fd4c18ae970
+  data.tar.gz: 32333ad6798227b37eb6c9430a4ce57d21a5a95e
 SHA512:
-  metadata.gz: !binary |-
-    MGRlZGU0MWNlNjljMDQ3ZGYwODVhMjdhN2Y5NzU3N2M2MTY4MTM5NTYxZjcw
-    Y2ZlM2VjMzQ1MmRlMjRjNzNiNmUyNjBiMjgxM2Q4NGNiYzYwMzk3MGQ0ZDBi
-    YzQxMjZkMWYxMGNmYzg5YmEyOWM1MGFlYTM0ZWJiOTY2NDk4ZDQ=
-  data.tar.gz: !binary |-
-    NThjZDRhZTlhOWRmYzU3ZGE0NjI4NzM4MGMwZjAyOThmZjFlMzQxNGQ5MDAz
-    M2QyOGNlOTdkMzM2MGE0NGJhZWQwYjBmZDM2Y2UyMDg4MmI1ZmMxMDQ0Zjc2
-    YzVmMjllYzg2MDJhMzhmMTAwMDBkOTY0MzJhNTI1ODE3MjJlOTc=
+  metadata.gz: 2872da1b9db75cc7a04980d1efa2b153d95d4d2713472285038a80ce6f7ace40a04d4e3fcb04ef68d9fb1ba4870e0bb15f3676d1b14d9084df023cb9401efda3
+  data.tar.gz: 650b478fb6144d634032f36e18ecf796f63b21cb23ca20c38e7213fdfbe36d0ae2082092d133cfa51d8464bc1b0ef9aef74923fded3c533e79c2f883a5e3838f

data/History.txt

@@ -230,3 +230,13 @@
 
 (en)
 * Fixed argument descriptions of some methods in the RDoc document.
+
+=== 0.5.3 / 2017-04-28
+
+(ja)
+* ドキュメントを修正（特に英語の記述について）。
+* Multimap#each_key が、ブロックを与えない場合にEnumeratorを返すようにした。
+
+(en)
+* Fixed documentation, especially in English writing.
+* Multimap#each_key returns an Enumerator if no block is given.

data/README.txt

@@ -19,6 +19,9 @@ Multisets are typically used for counting elements and their appearances in coll
 
 == SYNOPSIS:
 
+The document for detailed APIs can be generated by rdoc. http://docs.ruby-lang.org/en/2.2.0/RDoc/Markup.html
+Rdoc-generated document is available at: http://maraigue.hhiro.net/multiset/doc5/
+
  # Creating a multiset
  Set[:a,:b,:c,:b,:b,:c] # => #<Set: {:b, :c, :a}>
  Multiset[:a,:b,:c,:b,:b,:c] # => #<Multiset:#3 :b, #2 :c, #1 :a>

data/lib/multimap.rb

@@ -5,20 +5,18 @@ require "multiset"
 
 #==概要(Basic information)
 #
-#Rubyによる多重連想配列（マルチマップ）の実装です。
-#通常の連想配列（Rubyでは"Hash"クラス）と異なり、多重連想配列は
-#1つのキーに対して複数の要素が存在し得ます。
+# Ruby implementation of multimap.
+# Unlike ordinary map, also known as associative array
+# (see Ruby documentation for "Hash" class),
+# multimap can contain two or more items for a key.
 #
-#メソッド名は基本的にHashクラスに合わせてあります。またHashクラスが持つ
-#メソッドの大部分を実装していますが、いくつか未実装なものもあります。
+# Methods' names are basically consistent with those of Hash class.
 #
-#Ruby implementation of multimap.
-#Unlike ordinary map, also known as associative array
-#(see Ruby documentation for "Hash" class),
-#multimap can contain two or more items for a key.
+# Rubyによる多重連想配列（マルチマップ）の実装です。
+# 通常の連想配列（Rubyでは"Hash"クラス）と異なり、多重連想配列は
+# 1つのキーに対して複数の要素が存在し得ます。
 #
-#Most methods’ names are same as those of Hash class, and all other than
-#a few methods in Hash class is implemented on Multimap class.
+# メソッド名は基本的にHashクラスに合わせてあります。
 
 class Multimap
   include Enumerable
@@ -27,11 +25,11 @@ class Multimap
   # Constructors
   #++
   
+  # Generates a new multimap. Different from Hash#new , you cannot
+  # specify default value.
+  # 
   # 新しい多重連想配列を生成します。Hash#newと異なり、デフォルト値は
   # 設定できません。
-  # 
-  # Generates a new multimap. Different from Hash#new , you can not
-  # specify default value.
   def initialize
     @assoc = Hash.new{ |hash, key| hash[key] = Multiset.new }
   end
@@ -43,31 +41,34 @@ class Multimap
   end
   private :cleanup
   
-  # キー<code>key</code>に対応する値（複数存在しうる）を、
-  # Multisetとして返します。Hash#fetchの場合と異なり、キーに対応する
-  # 値が存在しない場合の扱いを指定することはできません。
-  # （そのような場合、空のMultisetが返ります。）
-  # 
-  # Returns values associated with <code>key</code> with format of
-  # Multiset. Different from Hash#fetch, you can not specify
-  # a value or a process when <code>key</code> has not associated with
-  # any value. If <code>key</code> has not associated with any value,
+  # Returns values associated with <code>key</code>, which may exist
+  # two or more, by the format of Multiset.
+  # If <code>key</code> has not associated with any value,
   # Multimap#fetch returns empty Multiset.
+  # Different from Hash#fetch, you cannot specify
+  # a value or a process when <code>key</code> has not associated with
+  # any value. 
+  # 
+  # キー<code>key</code>に対応する値（複数存在しうる）を、
+  # Multisetとして返します。
+  # キーに対応する値が存在しない場合、空のMultisetが返ります。
+  # Hash#fetchの場合と異なり、キーに対応する値が存在しない場合の扱いを
+  # 指定することはできません。
   def fetch(key)
     @assoc[key]
   end
   alias :[] :fetch
   
+  # Sets values associated with <code>key</code> to <code>value_list</code>.
+  # <code>value_list</code> is converted to a Multiset by Multiset.parse .
+  # 
+  # Returns <code>value_list</code>.
+  #
   # キー<code>key</code>に対応する値（複数存在しうる）を
   # <code>value_list</code>で置き換えます。この際、
   # <code>value_list</code>はMultiset.parseを用いてMultisetに変換されます。
   # 
   # <code>value_list</code>を返します。
-  # 
-  # Sets values associated with <code>key</code> to <code>value_list</code>.
-  # <code>value_list</code> is converted to a Multiset by Multiset.parse .
-  # 
-  # Returns <code>value_list</code>.
   def store(key, value_list)
     if value_list.class == Multiset
       @assoc[key] = value_list.dup
@@ -78,46 +79,44 @@ class Multimap
   end
   alias :[]= :store
   
-  # <code>self</code>が<code>other</code>と等しいかどうかを返します。
-  # 
   # Returns whether <code>self</code> is equal to <code>other</code>.
+  # 
+  # <code>self</code>が<code>other</code>と等しいかどうかを返します。
   def ==(other)
     return false unless other.instance_of?(Multimap)
     @assoc == other.to_hash
   end
   
-  # <code>self</code>を<code>Hash</code>に変換して返します。
-  # 生成されるハッシュの構造については、Hash#to_multimapをご覧下さい。
-  # その際、返されるハッシュにおいて値はすべてMultimap型となります。
+  # Converts <code>self</code> to a <code>Hash</code>
+  # whose values in the Hash are all multimaps.
   #
-  # Converts <code>self</code> to a <code>Hash</code>.
-  # See Hash#to_multimap about format of generated hash.
-  # All values in the returned hash are multimaps.
+  # <code>self</code>を<code>Hash</code>に変換して返します。
+  # 返されるHash中において、値はすべてMultimap型となります。
   def to_hash
     @assoc.dup
   end
   
-  # <code>self</code>に格納された要素をすべて削除します。
-  # <code>self</code>を返します。
-  # 
   # Removes all elements stored in <code>self</code>.
   # Returns <code>self</code>.
+  # 
+  # <code>self</code>に格納された要素をすべて削除します。
+  # <code>self</code>を返します。
   def clear
     @assoc.clear
   end
   
-  # <code>self</code>の複製を生成して返します。
-  #
   # Returns duplicated <code>self</code>.
+  #
+  # <code>self</code>の複製を生成して返します。
   def dup
     @assoc.to_multimap
   end
   
-  # <code>self</code>の内容を<code>other</code>のものに置き換えます。
-  # <code>self</code>を返します。
-  # 
   # Replaces <code>self</code> by <code>other</code>.
   # Returns <code>self</code>.
+  # 
+  # <code>self</code>の内容を<code>other</code>のものに置き換えます。
+  # <code>self</code>を返します。
   def replace(other)
     @assoc.clear
     other.each_pair_with do |key, a_value, count|
@@ -126,37 +125,37 @@ class Multimap
     self
   end
   
-  # <code>key</code>に割り当てられた全ての値を削除し、その値を
-  # Multisetとして返します。
-  # 
   # Deletes all values associated with <code>key</code>, and returns
   # those values as a Multiset.
+  # 
+  # <code>key</code>に割り当てられた全ての値を削除し、その値を
+  # Multisetとして返します。
   def delete(key)
     ret = @assoc[key]
     @assoc.delete(key)
     ret
   end
   
-  # delete_ifと同じですが、<code>self</code>自身からはキーと値の組を
+  # Same as Multimap#delete_if except that, rather than deleting key-value pairs in
+  # <code>self</code>, this generates a new Multimap with specified
+  # key-value pairs are deleted.
+  # 
+  # Multimap#delete_ifと似ますが、<code>self</code>自身からはキーと値の組を
   # 削除せず、要素が削除された結果の多重連想配列を新たに生成して
   # 返します。
-  # 
-  # Same as delete_if, but generates a new Multimap whose pairs of
-  # key and value are deleted, instead of deleting pairs in
-  # <code>self</code>.
   def reject(&block) # :yields: key, single_value
     ret = self.dup
     ret.delete_if &block
     ret
   end
   
-  # ブロックに<code>self</code>のキーと値の組（値は1つ）を順次与え、
-  # 結果が真であった組をすべて削除します。
-  # <code>self</code>を返します。
-  #
   # Gives all pairs of a key and single value in <code>self</code>
   # to given block, and deletes that element if the block returns true.
   # Returns <code>self</code>.
+  #
+  # ブロックに<code>self</code>のキーと値の組（値は1つ）を順次与え、
+  # 結果が真であった組をすべて削除します。
+  # <code>self</code>を返します。
   def delete_if(&block) # :yields: key, single_value
     cleanup
     @assoc.each_pair do |key, value_list|
@@ -167,11 +166,11 @@ class Multimap
     self
   end
   
-  # delete_ifと同じですが、キーと値の組が1つも削除されなければ
-  # <code>nil</code>を返します。
+  # Same as Multimap#delete_if except that <code>nil</code> is returned
+  # if no key-value pair is deleted.
   # 
-  # Same as delete_if, but returns <code>nil</code> if no pair of
-  # key and value is deleted.
+  # Multimap#delete_ifと似ますが、キーと値の組が1つも削除されなければ
+  # <code>nil</code>を返します。
   def reject!(&block) # :yields: key, single_value
     cleanup
     ret = nil
@@ -183,24 +182,24 @@ class Multimap
     ret
   end
   
-  # rejectと同じですが、ブロックへの引数が（キー、キーに割り当てられた値、
-  # その値がキーに割り当てられている個数）の3つの組で与えられます。
-  # 
-  # Same as reject, but arguments given to block is the tuple of three:
-  # (key, one value associated with the key, numbers of that value
+  # Same as Multimap#reject except that arguments given to block is the following three:
+  # (key, single value associated with the key, numbers of that value
   # associated with the key).
+  # 
+  # Multimap#rejectと似ますが、ブロックへの引数が（キー、キーに割り当てられた値、
+  # その値がキーに割り当てられている個数）の3つの組で与えられます。
   def reject_with(&block) # :yields: key, a_value, count
     ret = self.dup
     ret.delete_with &block
     ret
   end
   
-  # delete_ifと同じですが、ブロックへの引数が（キー、キーに割り当てられた値、
-  # その値がキーに割り当てられている個数）の3つの組で与えられます。
-  # 
-  # Same as delete_if, but arguments given to block is the tuple of three:
-  # (key, one value associated with the key, numbers of that value
+  # Same as Multimap#delete_if except that arguments given to block is the following three:
+  # (key, single value associated with the key, numbers of that value
   # associated with the key).
+  # 
+  # Multimap#delete_ifと同じですが、ブロックへの引数が（キー、キーに割り当てられた値、
+  # その値がキーに割り当てられている個数）の3つの組で与えられます。
   def delete_with(&block) # :yields: key, a_value, count
     cleanup
     @assoc.each_pair do |key, value_list|
@@ -211,11 +210,11 @@ class Multimap
     self
   end
   
-  # <code>self</code>のすべてのキーと値の組について繰り返します。
-  # <code>self</code>を返します。
-  # 
   # Iterates for each pair of a key and a value in <code>self</code>.
   # Returns <code>self</code>.
+  #
+  # <code>self</code>のすべてのキーと値の組について繰り返します。
+  # <code>self</code>を返します。
   def each_pair
     if block_given?
       cleanup
@@ -231,14 +230,14 @@ class Multimap
   end
   alias :each :each_pair
   
+  # Iterates for each pair of a key and a value in <code>self</code>,
+  # giving the following three to block:
+  # (key, single value associated with the key, numbers of that value
+  # associated with the key). Returns <code>self</code>.
+  # 
   # <code>self</code>のすべてのキーと値の組について、
   # ブロックに（キー、キーに割り当てられた値、その値が割り当てられた数）
   # の組を与えながら繰り返します。<code>self</code>を返します。
-  # 
-  # Iterates for each pair of a key and a value in <code>self</code>,
-  # giving the tuple of three to block:
-  # (key, one value associated with the key, numbers of that value
-  # associated with the key). Returns <code>self</code>.
   def each_pair_with
     if block_given?
       cleanup
@@ -253,32 +252,36 @@ class Multimap
     end
   end
   
-  # <code>self</code>のすべてのキーと、そのキーに割り当てられた
-  # すべての値（Multisetで与えられる）の組について繰り返します。
-  # <code>self</code>を返します。
-  # 
   # Iterates for each pair of a key and all values associated with the key
   # (list of values is given as Multiset) in <code>self</code>.
   # Returns <code>self</code>.
+  # 
+  # <code>self</code>のすべてのキーと、そのキーに割り当てられた
+  # すべての値（Multisetで与えられる）の組について繰り返します。
+  # <code>self</code>を返します。
   def each_pair_list(&block) # :yields: key, value_list
     cleanup
     @assoc.each_pair &block
   end
   
   
+  # Iterates for each key in <code>self</code>. Returns <code>self</code>.
+  # 
   # <code>self</code>のすべてのキーについて繰り返します。
   # <code>self</code>を返します。
-  # 
-  # Iterates for each key in <code>self</code>. Returns <code>self</code>.
   def each_key(&block) # :yields: key
-    cleanup
-    @assoc.each_key &block
+    if block_given?
+      cleanup
+      @assoc.each_key &block
+    else
+      Enumerator.new(self, :each_key)
+    end
   end
   
+  # Iterates for each value in <code>self</code>. Returns <code>self</code>.
+  # 
   # <code>self</code>のすべての値について繰り返します。
   # <code>self</code>を返します。
-  # 
-  # Iterates for each value in <code>self</code>. Returns <code>self</code>.
   def each_value(&block) # :yields: single_value
     if block_given?
       cleanup
@@ -291,18 +294,18 @@ class Multimap
     end
   end
   
-  # <code>self</code>のすべてのキーを、配列として返します。
-  # 
   # Returns an array in which keys in <code>self</code> are stored.
+  # 
+  # <code>self</code>のすべてのキーを、配列として返します。
   def keys
     cleanup
     @assoc.keys
   end
   
   
-  # <code>self</code>のすべての値を、Multisetとして返します。
-  # 
   # Returns a Multiset in which values in <code>self</code> are stored.
+  # 
+  # <code>self</code>のすべての値を、Multisetとして返します。
   def values
     cleanup
     ret = Multiset.new
@@ -312,17 +315,17 @@ class Multimap
     ret
   end
   
-  # <code>self</code>に要素がないかどうかを返します。
-  #
   # Returns whether <code>self</code> has no element.
+  #
+  # <code>self</code>に要素がないかどうかを返します。
   def empty?
     cleanup
     @assoc.empty?
   end
   
-  # <code>self</code>にキー<code>key</code>かあるかどうかを返します。
-  #
   # Returns whether <code>self</code> has a key <code>key</code>.
+  #
+  # <code>self</code>にキー<code>key</code>かあるかどうかを返します。
   def has_key?(key)
     cleanup
     @assoc.has_key?(key)
@@ -331,23 +334,23 @@ class Multimap
   alias :include? :has_key?
   alias :member? :has_key?
 
-  # <code>self</code>に値<code>value</code>かあるかどうかを返します。
-  #
   # Returns whether <code>self</code> has a value <code>value</code>.
+  #
+  # <code>self</code>に値<code>value</code>かあるかどうかを返します。
   def has_value?(value)
     self.values.items.include?(value)
   end
   alias :value? :has_value?
   
-  # <code>self</code>から値が<code>value</code>であるような要素を
-  # 検索し、それに対応するキーを返します。該当するキーが複数存在する場合、
-  # そのうちの1つを返します。該当するキーが存在しなければ
-  # <code>nil</code>を返します。
-  #
   # Search a pair of key and value from <code>self</code> such that
   # the value is equal to the argument <code>value</code>.
   # If two or keys are matched, returns one of them.
   # If no key is matched, returns nil.
+  #
+  # <code>self</code>から値が<code>value</code>であるような要素を
+  # 検索し、それに対応するキーを返します。該当するキーが複数存在する場合、
+  # そのうちの1つを返します。該当するキーが存在しなければ
+  # <code>nil</code>を返します。
   def key(value)
     self.each_pair_with do |key, a_value, count|
       return key if value == a_value
@@ -356,28 +359,28 @@ class Multimap
   end
   alias :index :key
   
+  # Retrieves values (instances of Multiset) of <code>self</code>
+  # associated with <code>key_list</code>, and returns those values
+  # as an array. i.e. returns an array whose elements are multisets.
+  # 
   # <code>self</code>から<code>key_list</code>の各キーに対応する値
   # （Multiset型）を取り出し、それらを配列として返します。
   # すなわち、Multisetを要素とする配列を返します。
-  # 
-  # Gets values (instances of Multiset) of <code>self</code>
-  # associated with <code>key_list</code>, and returns those values
-  # as an array. i.e. returns an array whose elements are multisets.
   def values_at(*key_list)
     key_list.map{ |key| self[key] }
   end
   alias :indexes :values_at
   alias :indices :values_at
   
-  # <code>self</code>のキーと値を入れ替えたMultimapを返します。
-  # 例えばキー:aに対応する値が2つの:xと1つの:yであれば、変換結果は
-  # キー:xに:aが2つ、キー:yに:aが1つ対応するMultimapです。
-  # 
   # Returns a Multimap whose keys are values in <code>self</code>, and
   # values are keys in <code>self</code>. For example,
   # If <code>self</code> has a key :a associated with two :x and one :y,
   # returned multimap has two keys :x and :y, and their values are
   # two :a and one :a respectively.
+  # 
+  # <code>self</code>のキーと値を入れ替えたMultimapを返します。
+  # 例えばキー:aに対応する値が2つの:xと1つの:yであれば、変換結果は
+  # キー:xに:aが2つ、キー:yに:aが1つ対応するMultimapです。
   def invert
     ret = Multimap.new
     self.each_pair_with do |key, a_value, count|
@@ -386,9 +389,9 @@ class Multimap
     ret
   end
   
-  # <code>self</code>に含まれている要素数を返します。 
-  # 
   # Returns number of all elements in <code>self</code>. 
+  # 
+  # <code>self</code>に含まれている要素数を返します。 
   def size
     ret = 0
     self.each_pair_with{ |key, a_value, count| ret += count }
@@ -396,11 +399,11 @@ class Multimap
   end
   alias :length :size
   
-  # <code>self</code>に<code>other</code>の要素を追加します。
-  # <code>self</code>を返します。
-  # 
   # Add elements in <code>other</code> to <code>self</code>.
   # Returns <code>self</code>.
+  # 
+  # <code>self</code>に<code>other</code>の要素を追加します。
+  # <code>self</code>を返します。
   def merge!(other)
     other.each_pair_with do |key, a_value, count|
       self[key].add a_value, count
@@ -408,9 +411,9 @@ class Multimap
     self
   end
   
-  # <code>self</code>と<code>other</code>の要素を合わせた多重集合を返します。
-  #
   # Returns merged multiset of <code>self</code> and <code>other</code>.
+  #
+  # <code>self</code>と<code>other</code>の要素を合わせた多重集合を返します。
   def merge(other)
     ret = self.dup
     ret.merge! other
@@ -453,16 +456,6 @@ class Multimap
 end
 
 class Hash
-  # <code>self</code>を多重連想配列に変換し、その結果を返します。
-  # 新しく生成される多重連想配列においてキーに割り当てられる値は、
-  # <code>self</code>におけるキーの値をMultiset.parseによって多重集合に
-  # 変換したものとなります。
-  # 
-  # （例）キー<code>:a</code>には<code>:x</code>と<code>:y</code>が1個ずつ、
-  # キー<code>:b</code>には<code>:x</code>が2個割り当てられた多重連想配列
-  # 
-  # <code>{:a => [:x, :y], :b => [:x, :x]}.to_multimap</code>
-  # 
   # Generates multiset from <code>self</code>.
   # In generated multiset, values associated with a key are defined by
   # the result of Multiset.parse(values_in_<code>self</code>) .
@@ -472,19 +465,29 @@ class Hash
   # key <code>:b</code> is associated with values two <code>:x</code>
   # 
   # <code>{:a => [:x, :y], :b => [:x, :x]}.to_multimap</code>
+  #
+  # <code>self</code>を多重連想配列に変換し、その結果を返します。
+  # 新しく生成される多重連想配列においてキーに割り当てられる値は、
+  # <code>self</code>におけるキーの値をMultiset.parseによって多重集合に
+  # 変換したものとなります。
+  # 
+  # （例）キー<code>:a</code>には<code>:x</code>と<code>:y</code>が1個ずつ、
+  # キー<code>:b</code>には<code>:x</code>が2個割り当てられた多重連想配列
+  # 
+  # <code>{:a => [:x, :y], :b => [:x, :x]}.to_multimap</code>
   def to_multimap
     ret = Multimap.new
     self.each_pair{ |key, val| ret[key] = val }
     ret
   end
   
-  # <code>self</code>を多重連想配列に変換し、その結果を返します。
-  # 新しく生成される多重連想配列においてキーに割り当てられる値は、
-  # <code>self</code>に含まれる1要素のみです。
-  # 
   # Generates multiset from <code>self</code>.
   # In generated multiset, only one value is associated with a key
   # (value in <code>self</code>).
+  #
+  # <code>self</code>を多重連想配列に変換し、その結果を返します。
+  # 新しく生成される多重連想配列においてキーに割り当てられる値は、
+  # <code>self</code>に含まれる1要素のみです。
   def multimap
     ret = Multimap.new
     self.each_pair{ |key, val| ret[key] = Multiset[val] }