[DOC]

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@45829 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

enum.c

@@ -1777,6 +1777,51 @@ max_by_i(RB_BLOCK_CALL_FUNC_ARGLIST(i, args))
  *
  *     a = %w[albatross dog horse]
  *     a.max_by(2) {|x| x.length } #=> ["horse", "albatross"]
+ *
+ *  enum.max_by(n) can be used to implement weighted random sampling.
+ *  Following example implements and use Enumerable#wsample.
+ *
+ *     module Enumerable
+ *       # weighted random sampling.
+ *       #
+ *       # Pavlos S. Efraimidis, Paul G. Spirakis
+ *       # Weighted random sampling with a reservoir
+ *       # Information Processing Letters
+ *       # Volume 97, Issue 5 (16 March 2006)
+ *       def wsample(n)
+ *         self.max_by(n) {|v| rand ** (1.0/yield(v)) }
+ *       end
+ *     end
+ *     e = (-20..20).to_a*10000
+ *     a = e.wsample(20000) {|x|
+ *       Math.exp(-(x/5.0)**2) # normal distribution
+ *     }
+ *     # a is 20000 samples from e.
+ *     p a.length #=> 20000
+ *     h = a.group_by {|x| x }
+ *     -10.upto(10) {|x| puts "*" * (h[x].length/30.0).to_i if h[x] }
+ *     #=> *
+ *     #   ***
+ *     #   ******
+ *     #   ***********
+ *     #   ******************
+ *     #   *****************************
+ *     #   *****************************************
+ *     #   ****************************************************
+ *     #   ***************************************************************
+ *     #   ********************************************************************
+ *     #   ***********************************************************************
+ *     #   ***********************************************************************
+ *     #   **************************************************************
+ *     #   ****************************************************
+ *     #   ***************************************
+ *     #   ***************************
+ *     #   ******************
+ *     #   ***********
+ *     #   *******
+ *     #   ***
+ *     #   *
+ *
  */
 
 static VALUE