hamster 0.4.3 → 1.0.0

data/History.rdoc

@@ -1,419 +0,0 @@
-=== 0.4.3 / 2012-10-01
-
-* Track size on Tries for performance (fredericksgary)
-* Hash#values should not return a set as there is no guarantee of uniqueness (and worse it means you potentially lose duplicate values). (fredericksgary)
-* Add Hash#slice, Hash#except, Hash#fetch (misfo)
-* Implemented a public Hash#new for subclassing (misfo)
-* Some initial benchmarks (haedius)
-* Documentation corrections (harukizaemon, szajbus, rwfowler)
-
-=== 0.4.2 / 2011-04-07
-
-* Added List#merge/merge_by to merge sorted lists into a single stream.
-* Added Enumerator#to_list produces a lazy list.
-* Alias List/Set#group_by as #group.
-
-=== 0.4.0 / 2010-12-13
-
-* Added initial implementation of Vector for efficient indexed access.
-
-* Fix car/cdr so they work on Ruby 1.8.7 (tianyicui)
-* Fix specs when running under 1.8.7 (tianyicui, kef)
-* Fix bundler/rvm support (kef)
-
-=== 0.3.10 / 2010-10-22
-
-* Update to RSpec 2.
-
-=== 0.3.9 / 2010-06-02
-
-* Implement Hash#values.
-
-=== 0.3.8 / 2010-06-02
-
-* Hash now accepts a block for supplying default values.
-
-=== 0.3.7 / 2010-05-16
-
-* Initial Queue implementation complete.
-
-* Implement Stack#peek.
-
-* Add Stack#enqueue, #dequeue to reflect the fact that a Stack is also a LIFO Queue.
-
-* Fix incompatibilities with Ruby 1.8.7 syntax.
-
-=== 0.3.6 / 2010-05-03
-
-* Hash#put now supports returning a value from a block instead of passing an explicit value. Almost like a substitute for the non-functional []=
-
-=== 0.3.4 / 2010-04-29
-
-* Reduce garbage collection by keeping a singleton instance of an empty hash.
-
-* Added some VERY experimental Read-Copy-Update collections (no tests).
-
-* Slightly improve performance and greatly improve the readability of #eql?/#== methods.
-
-* Added some VERY experimental memoization for immutable objects.
-
-* Added Set#merge as an alias for Set#union.
-
-* Implemented Hash#merge (aliased as #+).
-
-=== 0.3.3 / 2010-04-09
-
-* Fixed: hash code generation had VERY poor distribution.
-
-=== 0.3.1 / 2010-04-04
-
-* Fixed: Immutable not required in hamster.rb
-
-=== 0.3.0 / 2010-03-28
-
-* Add Hamster::Immutable as general purpose module to facililate immutability.
-
-* List, Stack, Set, and Hash now all implement Hamster::Immutable.
-
-=== 0.2.13 / 2010-03-25
-
-* Implement Hash#hash.
-
-* Implement Set#hash.
-
-* Implement List#hash.
-
-* Implement Set#flatten.
-
-=== 0.2.12 / 2010-03-01
-
-* Fixed bug: List#join accidentally modifying head if it was a string.
-
-=== 0.2.11 / 2010-02-15
-
-* Implement Set#one?
-
-* Implement Set#minimum (aliased as #min).
-
-* Implement Set#maximum (aliased as #max).
-
-* Implement Set#reduce with an optional memo.
-
-* Fix List#reduce should return nil when given no block and no starting value.
-
-=== 0.2.10 / 2010-02-15
-
-* Fix a bunch of spec failures under 1.8.7.
-
-* Remove some redundant object construction.
-
-=== 0.2.9 / 2010-02-11
-
-* Fix #to_list not available in all Enumerables.
-
-=== 0.2.8 / 2010-02-10
-
-* Implement Set#exclusion (aliased as #^) as equivalent to ((a | b) - (a & b)).
-
-* Implement Set#subset?
-
-* Implement Set#superset?
-
-* Implement Set#difference (aliased as #diff, #subtract, and #-).
-
-* Implement Set#intersection (aliased as #intersect and #&).
-
-* Implement Set#union (aliased as #| and #+).
-
-* Implement Set#union (aliased as #| and #+).
-
-* Remove Hash#[]= as its useless.
-
-=== 0.2.7 / 2010-02-08
-
-* Fixed bug with Hamster.interval (and Hamster.range) not handling Strings correctly.
-
-=== 0.2.6 / 2010-01-29
-
-* Implement Array#to_list.
-
-* Simplify (and improve performance of) conversions from arrays to lists.
-
-* Speed up Set and List sorting.
-
-* Implement Hash#find (aliased as #detect).
-
-* Implement List#elem_indices, List#find_indices (aliased as #indices as appropriate).
-
-* Implement List#index as per MRI and alias as #elem_index, and #find_index as appropriate.
-
-* Remove some redundant construction of streams.
-
-=== 0.2.5 / 2010-01-19
-
-* Implement Set#clear.
-
-* Implement List#slice (also aliased as #[from, length]).
-
-* Implement List#at (aliased as #[index]).
-
-=== 0.2.4 / 2010-01-18
-
-* Fix List#cadr and friends under JRuby.
-
-* Remove redundant locking (speed up).
-
-* Make reverse "lazy" (ish).
-
-* Fixed: StackOverflow calling List#head and List#tail on very large lazy lists.
-
-* Alias #reduce as #foldr.
-
-=== 0.2.3 / 2010-01-18
-
-* Implement Set#group_by.
-
-* Implement List#group_by.
-
-* Implement Hash#inspect.
-
-* Tuples can now be implicitly converted to args and variables via #to_ary, meaning you can do:
-
-   integers = Hamster.iterate(1, &:succ)
-   odds, evens = integers.partition(&:odd?)
-
-=== 0.2.2 / 2010-01-15
-
-* Implement List#flatten.
-
-* Implement List#each_slice (aliased as #each_chunk).
-
-* Return a tuple rather than a list for #split_at, #partition, #break, and #span.
-
-* Implement List#chunk.
-
-* Implement Set#compact.
-
-* Implement List#compact.
-
-=== 0.2.1 / 2010-01-15
-
-* Fix bug: List#empty? would cause a stack overflow on very large streams.
-
-=== 0.2.0 / 2010-01-14
-
-* List methods that return lists are now all lazy. Not sure what, if any, negative impact this will have but the positives have so far been well worth it.
-
-* Ensure List#eql? (and #==) doesn't accidentally consider an empty list to be equal to an empty array!
-
-* Ensure List responds_to? cadr and friends.
-
-* Stream now releases the block for garbage collection once called.
-
-* Implement List#combinations.
-
-* Implement List#inits.
-
-* Implement List#tails.
-
-* Implement Hash#uniq.
-
-* Alias #uniq as #remove_duplicates.
-
-* Alias #all? as #forall?
-
-* Implement Set#product.
-
-* Implement Set#sum.
-
-=== 0.1.23 / 2010-01-11
-
-* Implement List#product.
-
-* Implement List#sum.
-
-* Implement List#last.
-
-* Implement List#init.
-
-* Alias #reject as #remove.
-
-* Alias #each as #foreach.
-
-* Rename Hash#remove as Hash#delete.
-
-* Rename Set#remove as Set#delete.
-
-=== 0.1.22 / 2010-01-10
-
-* Implement List#union (aliased as #|).
-
-* Implement List#uniq (aliased as #nub).
-
-* Implement List#intersperse.
-
-* Alias #include? as #elem?
-
-* Implement Stack#to_list.
-
-* Implement Stack#to_a.
-
-* Implement Set#join.
-
-* Implement Set#count.
-
-* Implement List#count.
-
-* Alias #include? as #contains?
-
-* #each now returns nil if you specify a block.
-
-* Implement Set#find (aliased as #detect).
-
-=== 0.1.21 / 2010-01-08
-
-* Implement List#sort. (Very, VERY inefficient implementation!)
-
-* Implement List#sort_by. (Very, VERY inefficient implementation!)
-
-* Implement Set#to_set.
-
-* Implement Set#inspect.
-
-* Implement Set#first (aliased as #head).
-
-* Implement Set#sort. (Very, VERY inefficient implementation!)
-
-* Implement Set#sort_by. (Very, VERY inefficient implementation!)
-
-* Implement List#join.
-
-=== 0.1.20 / 2010-01-07
-
-* Implement Stack#clear.
-
-* Implement List#clear and Stack#clear.
-
-* Implement List#break.
-
-* Implement List#span.
-
-=== 0.1.19 / 2010-01-03
-
-* Bump minimum Ruby version to 1.8.7. I mean really, c'mon!
-
-=== 0.1.18 / 2010-01-03
-
-* Added gem development dependency on RSpec.
-
-=== 0.1.17 / 2010-01-02
-
-* Alias #empty? as #null?
-
-* Implement List#split_at.
-
-* Implement List.iterate.
-
-* Implement List#cycle.
-
-* Implement List.replicate.
-
-* Implement List.repeat.
-
-* Simplify List#take.
-
-* Simplify any?, all?, and none?
-
-* Re-write List#one? to be less complex.
-
-* Add Set#to_list.
-
-* Implement List#zip.
-
-* Implement Set#grep.
-
-* Implement Set#uniq (aliased as #nub).
-
-* Implement List#grep.
-
-=== 0.1.16 / 2009-12-30
-
-* Ensure streams cache results.
-
-* Ensure lists don't blow the stack.
-
-* List#entries is now an alias for List#to_a.
-
-* Implement List#to_list.
-
-* Implement List#one?.
-
-* Set#to_a is now aliased as #entries.
-
-* Implement List#minimum (aliased as #min) and List#maximum (aliased as #max).
-
-=== 0.1.15 / 2009-12-15
-
-* Implemented IO#to_list.
-
-* Implemented Enumerable#to_list.
-
-=== 0.1.14 / 2009-12-14
-
-* List#reduce supports optional initial value.
-
-* Implemented List#to_ary for implicit conversion to arrays and call parameters.
-
-* Implemented Set#to_a.
-
-* Alias #filter as #find_all.
-
-* Alias #reject as #delete_if.
-
-* Alias #reduce as #fold.
-
-=== 0.1.13 / 2009-12-10
-
-* Stack now fully functional
-
-=== 0.1.12 / 2009-12-10
-
-* List methods are now lazy where feasible
-
-* Now works under Ruby >= 1.8.6
-
-=== 0.1.8 / 2009-11-29
-
-* Add convenience constructors: List[], Set[], and Hash[]
-
-=== 0.1.7 / 2009-11-27
-
-* Implemented #eql?/== for Hash and Set.
-
-=== 0.1.6 / 2009-11-23
-
-* First cut at finishing implementation of Hash.
-
-=== 0.1.5 / 2009-11-5
-
-* Add some examples
-
-=== 0.1.4 / 2009-10-26
-
-* Simplify and share Trie between Hash and Set
-
-=== 0.1.3 / 2009-10-26
-
-* All known issues fixed.
-
-=== 0.1.2 / 2009-10-25
-
-* Fixed all but one outstanding issue with #remove
-
-=== 0.1.1 / 2009-10-23
-
-* Added #remove
-
-=== 0.1.0 / 2009-10-21
-
-* Initial version

data/LICENSE

@@ -1,20 +0,0 @@
-Copyright (c) 2009-2010 Simon Harris
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -1,236 +0,0 @@
-= Hamster - Efficient, Immutable, Thread-Safe Collection classes for Ruby
-
-  GitHub:   http://github.com/harukizaemon/hamster
-  RubyGems: https://rubygems.org/gems/hamster
-  email:    haruki_zaemon@mac.com
-  IRC:      ##haruki_zaemon on freenode
-
-== Introduction
-
-Hamster started out as an implementation of Hash Array Mapped Tries (HAMT) for Ruby (see http://lampwww.epfl.ch/papers/idealhashtrees.pdf) and has since expanded to include implementations of other Persistent Data Structures (see http://en.wikipedia.org/wiki/Persistent_data_structure) including Set, List, Stack, Queue, and Vector.
-
-Hamster collections are immutable. Whenever you modify a Hamster collection, the original is preserved and a modified copy is returned. This makes them inherently thread-safe and sharable. (For an interesting perspective on why immutability itself is inherently a good thing, you might like to take a look at Matthias Felleisen's Function Objects presentation: http://www.ccs.neu.edu/home/matthias/Presentations/ecoop2004.pdf)
-
-Hamster collection classes remain space efficient by making use of some very well understood and very simple techniques that enable sharing between copies.
-
-Hamster collections are almost always closed under a given operation. That is, whereas Ruby's collection methods always return arrays, Hamster collections will return an instance of the same class wherever possible.
-
-And lastly, Hamster lists are lazy -- where Ruby's language constructs permit -- making it possible to, among other things, process "infinitely large" lists. (Note: Ruby 1.9 supports a form of laziness using Enumerator. However, they're implemented using Fibers which unfortunately can't be shared across threads.)
-
-== Installation
-
-Hamster is distributed as a gem via rubygems (http://rubygems.org/gems/hamster) or as source via GitHub (http://github.com/harukizaemon/hamster).
-
-Installation via the gem is easy:
-
-  > gem install hamster
-
-Once installed, all that remains is to make the collection classes available in your code:
-
-  require 'hamster'
-
-Installation via bundler is even easier:
-
-  gem "hamster"
-
-
-If you prefer, you can instead require individual classes as necessary:
-
-  require 'hamster/list'
-  require 'hamster/stack'
-  require 'hamster/queue'
-  require 'hamster/hash'
-  require 'hamster/set'
-  require 'hamster/vector'
-
-== Examples
-
-Most Hamster classes support an API that resembles their standard library counterpart, with the caveat that any modification returns a new instance. What follows are some simple examples to help illustrate this point.
-
-=== Hash
-
-Constructing a Hamster Hash is almost as simple as a regular one:
-
-  simon = Hamster.hash(:name => "Simon", :gender => :male)  # => {:name => "Simon", :gender => :male}
-
-Accessing the contents will be familiar to you:
-
-  simon[:name]          # => "Simon"
-  simon.get(:gender)    # => :male
-
-Updating the contents is a little different than you are used to:
-
-  james = simon.put(:name, "James")   # => {:name => "James", :gender => :male}
-  simon                               # => {:name => "Simon", :gender => :male}
-  james[:name]                        # => "James"
-  simon[:name]                        # => "Simon"
-
-As you can see, updating the hash returned a copy leaving the original intact. Similarly, deleting a key returns yet another copy:
-
-  male = simon.delete(:name)    # => {:gender => :male}
-  simon                         # => {:name => "Simon", :gender => :male}
-  male.has_key?(:name)          # => false
-  simon.has_key?(:name)         # => true
-
-Hamster's hash doesn't provide an assignment (<tt>#[]=</tt>) method. The reason for this is simple yet irritating: Ruby assignment methods always return the assigned value, no matter what the method itself returns. For example:
-
-  counters = Hamster.hash(:odds => 0, :evens => 0)
-  counters[:odds] += 1          # => 1
-
-Because of this, the returned copy would be lost thus making the construct useless. Instead <tt>#put</tt> accepts a block instead of an explicit value so we can still do something similar
-
-  counters.put(:odds) { |value| value + 1 }    # => {:odds => 1, :evens => 0}
-
-or more succinctly:
-
-  counters.put(:odds, &:next)   # => {:odds => 1, :evens => 0}
-
-=== Set
-
-=== List
-
-Lists have a head -- the value of the item at the head of the list -- and a tail -- containing the remaining items. For example:
-
-  list = Hamster.list(1, 2, 3)
-
-  list.head    # => 1
-  list.tail    # => Hamster.list(2, 3)
-
-To add to a list, you use <tt>#cons</tt>:
-
-  original = Hamster.list(1, 2, 3)
-  copy = original.cons(0)           # => Hamster.list(0, 1, 2, 3)
-
-Notice how modifying a list actually returns a new list. That's because Hamster lists are immutable. Thankfully, just like Hamster Set and Hash, they're also very efficient at making copies!
-
-Lists are, where possible, lazy. That is, they try to defer processing items until absolutely necessary. For example, given a crude function to detect prime numbers:
-
-  def prime?(n)
-    2.upto(Math.sqrt(n).round) { |i| return false  if n % i == 0 }
-    true
-  end
-
-The following code will only call <tt>prime?</tt> as many times as necessary to generate the first 3 prime numbers between 10000 and 1000000:
-
-  Hamster.interval(10000, 1000000).filter { |i| prime?(i) }.take(3)    # => 0.0009s
-
-Compare that to the conventional equivalent which needs to calculate all possible values in the range before taking the first 3:
-
-  (10000..1000000).select { |i| prime?(i) }.take(3)   # => 10s
-
-Besides <tt>Hamster.list</tt> there are other ways to construct lists:
-
-<tt>Hamster.interval(from, to)</tt> (aliased as <tt>.range</tt>) creates a lazy list equivalent to a list containing all the values between <tt>from</tt> and <tt>to</tt> without actually creating a list that big.
-
-<tt>Hamster.stream { ... }</tt> allows you to creates infinite lists. Each time a new value is required, the supplied block is called. For example, to generate a list of integers you could do:
-
-  count = 0
-  integers = Hamster.stream { count += 1 }
-
-<tt>Hamster.repeat(x)</tt> creates an infinite list with x the value for every element.
-
-<tt>Hamster.replicate(n, x)</tt> creates a list of size n with x the value for every element.
-
-<tt>Hamster.iterate(x) { |x| ... }</tt> creates an infinite list where the first item is calculated by applying the block on the initial argument, the second item by applying the function on the previous result and so on. For example, a simpler way to generate a list of integers would be:
-
-  integers = Hamster.iterate(1) { |i| i + 1 }
-
-or even more succinctly:
-
-  integers = Hamster.iterate(1, &:next)
-
-You also get <tt>Enumerable#to_list</tt> so you can slowly transition from built-in collection classes to Hamster.
-
-And finally, you get <tt>IO#to_list</tt> allowing you to lazily processes huge files. For example, imagine the following code to process a 100MB file:
-
-  File.open("my_100_mb_file.txt") do |io|
-    lines = []
-    io.each_line do |line|
-      break if lines.size == 10
-      lines << line.chomp.downcase.reverse
-    end
-  end
-
-How many times/how long did you read the code before it became apparent what the code actually did? Now compare that to the following:
-
-  File.open("my_100_mb_file.txt") do |io|
-    io.map(&:chomp).map(&:downcase).map(&:reverse).take(10)
-  end
-
-Unfortunately, though the second example reads nicely, it takes around 13 seconds to run (compared with 0.033 seconds for the first) even though we're only interested in the first 10 lines! However, using a little <tt>#to_list</tt> magic, we can get the running time back down to 0.033 seconds!
-
-  File.open("my_100_mb_file.txt") do |io|
-    io.to_list.map(&:chomp).map(&:downcase).map(&:reverse).take(10)
-  end
-
-How is this even possible? It's possible because <tt>IO#to_list</tt> creates a lazy list whereby each line is only ever read and processed as needed, in effect converting it to the first example without all the syntactic, imperative, noise.
-
-=== Stack
-
-=== Queue
-
-=== Vector
-
-== Disclaimer
-
-Hamster started out as a spike to prove a point and has since morphed into something I actually use. My primary concern has been to round out the functionality with good test coverage and clean, readable code.
-
-Performance is pretty good -- especially with lazy lists -- but there are some things which may blow the stack due to a lack of Tail-Call-Optimisation in Ruby.
-
-Documentation is sparse but I've tried as best I can to write specs that read as documentation. I've also tried to alias methods as their <tt>Enumerable</tt> equivalents where possible to ease code migration.
-
-== Reporting bugs
-
-Please report all bugs on the GitHub issue tracker located at: http://github.com/harukizaemon/hamster/issues
-
-== But I still don't understand why I should care?
-
-As mentioned earlier, persistent data structures perform a copy whenever they are modified meaning there is never any chance that two threads could be modifying the same instance at any one time. And, because they are very efficient copies, you don't need to worry about using up gobs of memory in the process.
-
-Even if threading isn't a concern, because they're immutable, you can pass them around between objects, methods, and functions in the same thread and never worry about data corruption; no more defensive calls to <tt>#dup</tt>!
-
-=== OK, that sounds mildly interesting. What's the downside--there's always a downside?
-
-There's a potential performance hit when compared with MRI's built-in, native, hand-crafted C-code implementation of Hash. For example:
-
-  hash = Hamster.hash
-  (1..10000).each { |i| hash = hash.put(i, i) }   # => 0.05s
-  (1..10000).each { |i| hash.get(i) }             # => 0.008s
-
-versus
-
-  hash = {}
-  (1..10000).each { |i| hash[i] = i }   # => 0.004s
-  (1..10000).each { |i| hash[i] }       # => 0.001s
-
-=== That seems pretty bad?
-
-Well, yes and no. The previous comparison wasn't really fair. Sure, if all you want to do is replace your existing uses of Hash in single-threaded environments then don't even bother. However, if you need something that can be used efficiently in concurrent environments where multiple threads are accessing--reading AND writing--the contents things get much better.
-
-=== Do you have a better example?
-
-A more realistic comparison might look like:
-
-  hash = Hamster.hash
-  (1..10000).each { |i| hash = hash.put(i, i) }   # => 0.05s
-  (1..10000).each { |i| hash.get(i) }             # => 0.008s
-
-versus
-
-  hash = {}
-  (1..10000).each { |i|
-    hash = hash.dup
-    hash[i] = i
-  }                                 # => 19.8s
-
-  (1..10000).each { |i| hash[i] }   # => 0.001s
-
-What's even better -- or worse depending on your perspective -- is that after all that, the native Hash version still isn't thread-safe and still requires some synchronisation around it slowing it down even further.
-
-The Hamster version on the other hand was unchanged from the original whilst remaining inherently thread-safe, and 3 orders of magnitude faster.
-
-=== Sure, but as you say, you still need synchronisation so why bother with the copying?
-
-Well, I could show you one but I'd have to re-write/wrap most Hash methods to make them generic, or at the very least write some application-specific code that synchronised using a <tt>Mutex</tt> and ... well ... it's hard, I always make mistakes, I always end up with weird edge cases and race conditions so, I'll leave that as an exercise for you :)
-
-And don't forget that even if threading isn't a concern for you, the safety provided by immutability alone is worth it, not to mention the lazy implementations.