facets 2.0.0 → 2.0.1

data/AUTHORS

@@ -49,6 +49,7 @@ work is greatly appreciated.
 * Tim Pease
 * Jonas Pfenniger
 * Ryan Platte
+* Oliver Renaud
 * Christoph Rippel
 * Daniel Schierbeck
 * Gavin Sinclair
@@ -57,6 +58,7 @@ work is greatly appreciated.
 * Peter Vanbroekhoven
 * Jim Weirich
 * Jeff Wood
+* Erik Veenstra
 * Austin Ziegler
 * Why The Lucky Stiff
 

data/README

@@ -7,68 +7,54 @@
 
 == Introduction
 
-Ruby Facets is the singele largest collection of general purpose method extensions
-and system additions for the Ruby programming language.
+Ruby Facets is the single largest collection of general purpose method extensions and system additions for the Ruby programming language.
 
-The core extensions is a large collection of methods which extend the core capabilities of Ruby's
-built-in classes and modules. This collection of extension methods are unique by virtue of
-their atomicity. The methods are stored in relatively small groups of tightly coupled methods so
-that each can be required independently. This gives developers the potential for much finer
-control over which extra methods to bring into their code.
+The core extensions is a large collection of methods which extend the core capabilities of Ruby's built-in classes and modules. This collection of extension methods are unique by virtue of their atomicity. The methods are stored in relatively small groups of tightly coupled methods so that each can be required independently. This gives developers the potential for much finer control over which extra methods to bring into their code.
 
-The "more" additions are a collection of classes, modules and light meta-systems which
-consitutes an ever improving source of reusable components. Some very nice additions are
-provided, from the simple Functor class to a full-blown annotations system.
+The "more" additions are a collection of classes, modules and light meta-systems which constitutes an ever improving source of reusable components. Some very nice additions are provided, from the simple Functor class to a full-blown annotations system.
 
 
 == Installation
 
-Ycan intall either via RubyGems or manually:
+The easiest way to install is via RubyGems.
 
-  % gem install facets
+  $ gem install facets
 
-or
+To install manually, download and unpack the .tar.gz package and use the included
+task/install script. Eg.
 
-  % tar -xzf facets-2.x.x.tar.gz
-  % cd facets-2.x.x
-  % sudo task/setup
+  $ tar -xvzf facets-2.x.x.tar.gz
+  $ cd facets-2.x.x
+  $ sudo task/setup
 
+On Window the last step will be:
 
-== Compatability with 1.x series.
+  C:\> ruby task/setup
 
-Prior to 2.0, Facets was divided between CORE and MORE --standalone extensions vs.
-classes and modules, respectively. With 2.0, the idea of CORE has take only a
-slightly new meaning. Instead CORE now represents the libraries that are considerd essential
-and as such are loaded automatically when using ++require "facets"++. While still primarily
-made up of extension methods a few classes now belong to core as well. In conjuction
-with this the extension methods are no longer stored on a per-method basis, but rather in
-tight knit packs. While dividing the extension methods up on a per-method basis had certain advantages,
-not the least of which was a simple organization, it proved too granular --rather than "atomic"
-it was "subatomic". With 2.0 we have address this issue. All the extension methods have now been
-orgnized into small tightly related groups.
+IMPORTANT! Note that setup.rb is no longer used b/c of Facets' new layout.
 
-However, being able to require on the basis of a method is still a useful approach,
-so a compatability layer for the 1.x series has been created. It makes it possible to
-load Facets libraries on a per method basis, just as before, via require redirection.
 
-For example:
+== Compatibility with 1.x series.
+
+Prior to 2.0, Facets was divided between CORE and MORE --standalone extensions vs. classes and modules, respectively. With 2.0, the notion of "CORE" has taken only a slightly differnt meaning. Instead CORE now consists of the libraries that are thought essential and as such are loaded automatically when using ++require "facets"++. While still primarily made up of extension methods a few classes now belong to core as well.
+
+Additionally, the extension methods are no longer stored on a per-method basis. While dividing the extension methods up on a per-method basis had certain advantages, not the least of which was a simple organization, it proved too granular --more "subatomic" than "atomic". With 2.0 we have address this issue. All the extension methods have now been organized into small tightly related groups.
+However, being able to require on the basis of a method is still a useful approach, so a compatibility layer for the 1.x series has been created. It makes it possible to load Facets libraries on a per method basis, just as before, via require redirection. For example:
 
-  require 'facets/core/string/underscore'
+  require 'facets/string/underscore'
 
-Will redirect according to the content of the underscore.rb file:
+Will redirect according to the content of the underscore.rb file which is:
 
   require  'facets/string/stylize'
 
-So the underscore method will be loaded just as before. But a few other *stylization*
-methods will be loaded as well. This actually proves a more useful approach b/c
-often one will want to use one of the related methods as well.
+So the underscore method will be loaded just as before. But a few other *stylization* methods will also be loaded. This actually proves a more useful approach because quite often a related method is needed as well.
+
+The other significant change from 1.x to 2.0 is the removal of some libraries that were considered too extraneous for a general purpose library. Most of these were spun-off to their own projects. In particular, the web-related libs are now part of Blow (http://blow.rubyforge.org), inflection libraries are in English (http://english.rubyforge.org), units.rb along with constants.rb are in Stick (http://stick.rubyforge.org), and the persistance system in Opod (http://opod.rubyforge.org).
 
 
 == Mission
 
-Facets holds to the notion that the more we can reasonably integrate into
-a common foundation directed toward general needs, the better that foundation
-will be able to serve everyone. There are a number of advantages here:
+Facets holds to the notion that the more we can reasonably integrate into a common foundation directed toward general needs, the better that foundation will be able to serve everyone. There are a number of advantages here:
 
     * Better Code-reuse
     * Collaborative Improvements
@@ -78,43 +64,24 @@ will be able to serve everyone. There are a number of advantages here:
 
 == Status
 
-The current status is quite good. While some parts are still considered
-beta, everything is relatively usable.
-
+The current status of Facets is very good. While some libs could still use some "finishing" work, all are highly API stable and functional.
 
-== Installation
-
-The easiest way to install is via RubyGems. On the command line enter:
-
-  > gem install facets
-
-To manually install, unpack the .tar.bz2 package and use the included
-setup.rb script. For example:
-
-  > tar -xvzf facets-x.x.x.tar.gz
-  > cd facets-x.x.x
-  > sudo util/setup
-
-On Window the last step will be:
 
-  > ruby util/setup
+== Usage
 
+For detailed usage of any given method or module please refer to the API RDocs.
 
-== Usage
+  http://facets.rubyforge.org/learn.html
 
-For detailed usage of any given method or module please refer to the
-API RDocs. Most are well documented. Assistance in improving
-documentation though is always appreciated.
+Most libraries are well documented. Assistance in improving documentation though is always appreciated.
 
-If you plan to use more then a few of Facets core method it is recommended
-that you require require the main facility.
+If you plan to use more then a few of Facets core method it is recommended that you require require the main facility.
 
   require 'facets'
 
 This loads all the CORE functionality at once.
 
-Of course you can use the CORE library piecemenal if you prefer.
-The general require statement for a core extensions library is:
+Of course you can use the CORE library piecemeal if you prefer. The general require statement for a core extensions library is:
 
   require 'facets/<class|module>/<method-lib>'
 
@@ -122,48 +89,38 @@ For example:
 
   require 'facets/time/stamp'
 
-Most "atoms" contain only a few methods, sometimes only one, but a few excpetions
-provide quite a few method, such as ++string/indexable.rb++.
+Most "atoms" contain only a few methods, sometimes only one, but a few exceptions provide quite a few method, such as ++string/indexable.rb++.
 
-You can load per-class or per-module groups of core methods by requiring the class
-or module by name. For example"
+You can load per-class or per-module groups of core methods by requiring the class or module by name. For example"
 
   require 'facets/time'
 
 Will require all the Time method extensions.
 
-Note that some methods that were part of CORE in 1.8 and earlier are now
-part of MORE libraries. A good example is 'random.rb'. There were separated
-b/c they had more specialized usecases, where as CORE extensions are
-intended as general purpose.
+Note that some methods that were part of CORE in 1.8 and earlier are now part of MORE libraries. A good example is 'random.rb'. There were separated b/c they had more specialized usecases, where as CORE extensions are intended as general purpose.
 
-Using a Facets/MORE library of modules, classes or microframeworks
-is essentially the same. For example:
+Using a Facets/MORE library of modules, classes or microframeworks is essentially the same. For example:
 
   require 'facets/basicobject'
 
+Again, for details pertaining to the functionality of each feature, please see the API Docs.
+
+
 # PLEASE IGNORE THIS FOR NOW
-#
-# It is possible to eliminate the need for the 'facets/' prefix on requires if
-# the Facets libpaths are added to the LOAD_PATH. But this isn't as straight-foward
-# as it is for most libraries b/c of the layout of Facets library.
-#
-#   require 'facets-topload'
-#   require 'basicobject'
-#
-# Understand that on the off chance that another library has the same name as
-# one of Facets' everything will still work fine. You will just not be able to use the
-# prefixless shorcut to require it.
-#
-# END.
 
-Again, for details pertaining to the functionality of each feature, please see the API Docs.
+It is possible to eliminate the need for the 'facets/' prefix on requires if the Facets libpaths are added to the LOAD_PATH. But this isn't as straight-forward as it is for most libraries b/c of the layout of Facets library.
+
+  require 'facets-topload'
+  require 'basicobject'
+
+Understand that on the off chance that another library has the same name as one of Facets' everything will still work fine. You will just not be able to use the prefixless shortcut to require it.
+
+# END IGNORE.
 
 
 == Method File Names
 
-Operator method redirect files are stored using english names. For instance for
-Proc#* is 'proc/op_mul'.
+Operator method redirect files are stored using English names. For instance for Proc#* is 'proc/op_mul'.
 
 For reference, here is the chart.
 
@@ -192,43 +149,29 @@ For reference, here is the chart.
      []=  => op_store
      []   => op_fetch
 
-Facets simply takes the '*' and translates it into a string acceptable
-to all file systems. Also, if a method ends in '=', '?' or '!' it is
-simply removed.
+Facets simply takes the '*' and translates it into a string acceptable to all file systems. Also, if a method ends in '=', '?' or '!' it is simply removed.
 
 
 == Contribute
 
 This project thrives on contribution.
 
-If you have any extension methods, classes, modules or small frameworks
-that you think have general applicability and would like to see them
-included in this project, don't hesitiate to submit. There's a very good
-chance it will be included.  Also, if you have better versions of any thing
-already included or simply have a patch, they too are more than welcome.
-We want Ruby Facets to be of the highest quality.
+If you have any extension methods, classes, modules or small frameworks that you think have general applicability and would like to see them included in this project, don't hesitiate to submit. There's a very good chance it will be included.  Also, if you have better versions of any thing already included or simply have a patch, they too are more than welcome. We want Ruby Facets to be of the highest quality.
 
 
 == Authors
 
-This collection was put together by, and largely written by Thomas Sawyer
-(aka Trans). He can be reached via email at transfire at gmail.com.
+This collection was put together by, and largely written by Thomas Sawyer (aka Trans). He can be reached via email at transfire at gmail.com.
 
-Some parts of this collection were written and/or inspired by other
-persons. Fortunately nearly all were copyrighted under the same open
-license, the Ruby License. In the few excpetions I have included the
-copyright notice with the source code.
+Some parts of this collection were written and/or inspired by other persons. Fortunately nearly all were copyrighted under the same open license, the Ruby License. In the few exceptions I have included the copyright notice with the source code.
 
-Any code file not specifically labelled shall fall under the Ruby License.
+Any code file not specifically labeled shall fall under the Ruby License.
 
-In all cases, I have made every effort to give credit where credit is due.
-You will find these copyrights, thanks and acknowledgements embedded in the
-source code, and an unobtrusive "Author(s)" section is given in the RDocs.
+In all cases, I have made every effort to give credit where credit is due. You will find these copyrights, thanks and acknowledgments embedded in the source code, and an unobtrusive "Author(s)" section is given in the RDocs.
 
 Also see the AUTHORS file for a list of all contributing Rubyists.
 
-If anyone is missing from the list, please let me know and
-I will correct right away. Thanks.
+If anyone is missing from the list, please let me know and I will correct right away. Thanks.
 
 
 == License
@@ -240,27 +183,9 @@ The collection PER COLLECTION is licensed as follows:
 
   Distributed under the terms of the Ruby license.
 
-The Ruby license is a dual license that also provides for use of the GPL.
-Complete texts of both licenses accompany this document (see doc/COPYING).
-
-  This program is free software; you can redistribute it and/or modify
-  it under the terms of the GNU General Public License as published by
-  the Free Software Foundation; either version 2 of the License, or
-  (at your option) any later version.
-
-  This program is distributed in the hope that it will be useful,
-  but WITHOUT ANY WARRANTY; without even the implied warranty of
-  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-  GNU General Public License for more details.
-
-  You should have received a copy of the GNU General Public License
-  along with this program; if not, write to the Free Software
-  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+The Ruby license is a dual license that also provides for use of the GPL. Complete texts of both licenses accompany this document (see LICENSE).
 
-Acknowledgments and Copyrights for particular snippets of borrowed code
-are given in their respective source. All licenses are either compatible
-with the Ruby license (namely the GPL) or the original author has given
-permission for inclusion of their code under such lincense.
+Acknowledgments and Copyrights for particular snippets of borrowed code are given in their respective source. All licenses are either compatible with the Ruby license (namely the GPL) or the original author has given permission for inclusion of their code under such license.
 
 
 == Pitch
@@ -270,14 +195,7 @@ permission for inclusion of their code under such lincense.
 
 ----
 
-[1] A lot of mental anguish went into finding this good project name Ruby Facets.
-    Of course, in the end only one name can take the honor. Other good names
-    which were considered: Calibre, Florida and California, Warchest w/ Atomix,
-    Downs & Ace, Trix & Atomx and even Pillbox & Pills (a _why suggestion).
-    Then the names that almost won out and were used for a good while:
-    Nano Methods and Mega Modules --great names but a little to "fad".
-    Finally let's not forget even older "working" titles that were used
-    along the way: Raspberry, ABC, Succ and the very original Tomslib.
+[1] A lot of mental anguish went into finding this good project name Ruby Facets. Of course, in the end only one name can take the honor. Other good names which were considered: Calibre, Florida and California, Warchest w/ Atomix, Downs & Ace, Trix & Atomx and even Pillbox & Pills (a _why suggestion). Then the names that almost won out and were used for a good while: Nano Methods and Mega Modules --great names but a little to "fad". Finally let's not forget even older "working" titles that were used along the way: Raspberry, ABC, Succ and the very original Tomslib.
 
 ----
 

data/demo/bench/enumerable/bench_collect.rb

@@ -0,0 +1,84 @@
+require 'benchmark'
+
+module Enumerable
+
+  # group_by
+
+  def group_by_1(&block)
+    h = k = e = nil
+    r = Hash.new
+    each{|e| (r[yield(e)] ||= []) << e}
+    r
+  end
+
+  def group_by_2(&block)
+    r = Hash.new{ |h,k| h[k]=[] }
+    each{|e| r[yield(e)] << e}
+    r
+  end
+
+  # cluster_by
+
+  def cluster_by_1(&block)
+    group_by_1(&block).values  # No sorting.
+  end
+
+  def cluster_by_2(&block)
+    #partition_by_fast(&block).values.sort    # Sorted by value.
+    group_by_1(&block).sort.transpose.pop  # Sorted by key.
+  end
+
+  def cluster_by_3(&block)        # As defined by Facets.
+    h = {}
+    each{|e| (h[block[e]] ||= []) << e}
+    h.keys.sort!.map{|k| h[k]}        # Sorted by key.
+  end
+
+end
+
+#
+
+Benchmark.bmbm do |x|
+  n = 10
+  a = (0...10000).to_a + (0...10000).to_a
+  h = (0...10000).inject({}){|h, e| h[e] = e ; h}
+
+  # group_by
+
+  x.report("group_by_1") do
+    n.times do
+      a.group_by_1{|e| e % 10}
+      h.group_by_1{|k, v| v % 10}
+    end
+  end
+
+  x.report("group_by_2") do
+    n.times do
+      a.group_by_2{|e| e % 10}
+      h.group_by_2{|k, v| v % 10}
+    end
+  end
+
+  # cluster_by
+
+  x.report("cluster_by_1") do
+    n.times do
+      a.cluster_by_1{|e| e % 10}
+      h.cluster_by_1{|k, v| v % 10}
+    end
+  end
+
+  x.report("cluster_by_2") do
+    n.times do
+      a.cluster_by_2{|e| e % 10}
+      h.cluster_by_2{|k, v| v % 10}
+    end
+  end
+
+  x.report("cluster_by_3") do
+    n.times do
+      a.cluster_by_3{|e| e % 10}
+      h.cluster_by_3{|k, v| v % 10}
+    end
+  end
+end

data/demo/bench/enumerable/bench_count.rb

@@ -0,0 +1,58 @@
+require 'benchmark'
+
+module Enumerable
+
+  # duplicates
+
+  def duplicates_1
+    h1 = {}
+    h2 = {}
+    each {|i|
+      h2[i] = true if h1[i]
+      h1[i] = true
+    }
+    h2.keys
+  end
+
+  def duplicates_2
+    inject(Hash.new(0)){|h,v| h[v]+=1; h}.reject{|k,v| v==1}.keys
+  end
+
+  # uniq_by
+
+  def uniq_by_1 #:yield:
+    h = {}; inject([]) {|a,x| h[yield(x)] ||= a << x}
+  end
+
+  def uniq_by_2
+    inject({}) { |h,x| h[yield(x)] ||= x; h }.values
+  end
+
+end
+
+#
+
+Benchmark.bmbm do |x|
+  n = 10000
+  a = [1,1,2,3,4,4,5,6,7,7]
+
+  # duplicates
+
+  x.report("duplicates_1") do
+    n.times { a.duplicates_1 }
+  end
+
+  x.report("duplicates_2") do
+    n.times { a.duplicates_2 }
+  end
+
+  # uniq_by
+
+  x.report("uniq_by_1") do
+    n.times { a.uniq_by_1{ |x| x } }
+  end
+
+  x.report("uniq_by_2") do
+    n.times { a.uniq_by_2{ |x| x } }
+  end
+end