facets 2.9.1 → 2.9.2

data/src/core-uncommon/facets/array/median.rb

@@ -0,0 +1,17 @@
+require 'facets/array/percentile'
+
+class Array
+
+  # Returns the median for the array; nil if array is empty.
+  #
+  # NOTE: This is not (presently) a common core extension and is not
+  # loaded automatically when using <code>require 'facets'</code>.
+  #--
+  # TODO: Does Array#median belong in a math-oriented library?
+  #++
+  def median
+    percentile(50)
+  end
+
+end
+

data/src/core-uncommon/facets/array/op_pow.rb

@@ -0,0 +1,9 @@
+require 'facets/array/product'
+
+class Array
+  # Array#** is an alias for Array#product.
+  #
+  # NOTE: This is not (presently) a common core extension and is not
+  # loaded automatically when using <code>require 'facets'</code>.
+  alias_method :**, :product
+end

data/src/core-uncommon/facets/array/percentile.rb

@@ -0,0 +1,32 @@
+class Array
+
+  # Returns the percentile value for percentile _p_; nil if array is empty.
+  #
+  # +p+ should be expressed as an integer; <tt>percentile(90)</tt> returns
+  # the 90th percentile of the array.
+  #
+  # Algorithm from NIST[http://www.itl.nist.gov/div898/handbook/prc/section2/prc252.htm]
+  #
+  # NOTE: This is not (presently) a common core extension and is not
+  # loaded automatically when using <code>require 'facets'</code>.
+  #
+  # CREDT: ?
+
+  def percentile(p)
+    sorted_array = self.sort
+    rank = (p.to_f / 100) * (self.length + 1)
+
+    if self.length == 0
+      return nil
+    elsif rank.to_i == rank #fractional_part?
+      sample_0 = sorted_array[rank.truncate - 1]
+      sample_1 = sorted_array[rank.truncate]
+
+      fractional_part = rank.abs.modulo(1)
+      return (fractional_part * (sample_1 - sample_0)) + sample_0
+    else
+      return sorted_array[rank.to_i - 1]
+    end    
+  end
+  
+end

data/src/core-uncommon/facets/class/preallocate.rb

@@ -0,0 +1,52 @@
+class Class
+
+  # Designate aspect modules to be added to a object at instantiation.
+  #
+  #   class Firetruck
+  #     def put_out_fire(option)
+  #       "Put out #{option}"
+  #     end
+  #   end
+  #
+  #   module FastFiretruck
+  #     def put_out_fire(option)
+  #       super("very #{option}!")
+  #     end
+  #   end
+  #
+  #   Firetruck.preallocate(FastFiretruck)
+  #
+  #   ft = Firetruck.new
+  #   ft.put_out_fire('fast') #=> "Put out very fast!"
+  #
+  # This method is very similar to the idea of #prepend, but it has some
+  # limitations in that it works by overriding #new and #allocate and extends
+  # an object with the aspect modules on instantiation. A true #prepend
+  # implementation would not have to do this --but would be a natural part
+  # of the class heirarchy instead. For this reason, this method has been
+  # named #preallocate, rather than #prepend.
+  #
+  # NOTE: This is not (presently) a common core extension and is not
+  # loaded automatically when using <code>require 'facets'</code>.
+  #
+  # CREDIT: Trans
+
+  def preallocate(aspect)
+    _new      = method(:new)
+    _allocate = method(:allocate)
+    (class << self; self; end).class_eval do
+      define_method(:new) do |*args|
+        o = _new.call(*args)
+        o.extend aspect
+        o
+      end
+      define_method(:allocate) do |*args|
+        o = _allocate.call(*args)
+        o.extend aspect
+        o
+      end
+    end
+  end
+
+end
+

data/src/core-uncommon/facets/class/singleton.rb

@@ -0,0 +1,8 @@
+class Class 
+
+  #
+  def singleton? 
+    ! ancestors.include?( self ) rescue false 
+  end
+
+end 

data/src/core-uncommon/facets/enumerable/has.rb

@@ -0,0 +1,22 @@
+module Enumerable
+  
+  # The same as #include?() but equality is tested using ===.
+  # 
+  #   [1, 2, "a"].has?(2)       #=> true
+  #   [1, 2, "a"].has?(String)  #=> true
+  #   [1, 2, "a"].has?(3)       #=> false
+  # 
+  # NOTE: This is not (presently) a common core extension and is not
+  # loaded automatically when using <code>require 'facets'</code>.
+  #
+  # TODO: Perhaps #matches? would be a better name?
+  #
+  # CREDIT: Lavir the Whiolet
+  def has?(what)
+    any? { |x| what === x }
+  end
+  
+  # Alias for #has?
+  alias have? has?
+  
+end

data/src/core-uncommon/facets/enumerable/have.rb

@@ -0,0 +1 @@
+require 'facets/enumerable/has'

data/src/core-uncommon/facets/integer/roman.rb

@@ -0,0 +1,77 @@
+class Integer
+
+  #
+  ROMAN_MAX = 3999 unless const_defined?(:ROMAN_MAX)
+
+  #
+  ROMAN_VALUES = [
+    ["M", 1000],
+    ["CM", 900],
+    ["D",  500],
+    ["CD", 400],
+    ["C",  100],
+    ["XC",  90],
+    ["L",   50],
+    ["XL",  40],
+    ["X",   10],
+    ["IX",   9],
+    ["V",    5],
+    ["IV",   4],
+    ["I",    1]
+  ] unless const_defined?(:ROMAN_VALUES)
+
+  # Converts this integer to a roman numeral.
+  #
+  # NOTE: This is not (presently) a common core extension and is not
+  # loaded automatically when using <code>require 'facets'</code>.
+  def roman
+    int = self
+    #return nil if integer > ROMAN_MAX
+    return "-#{(-int).roman}" if int < 0
+    return "" if int == 0
+    ROMAN_VALUES.each do |(i, v)|
+      return(i + (int-v).roman) if v <= int 
+    end
+  end
+
+end
+
+
+class String
+
+  # Taken from O'Reilly's Perl Cookbook 6.23. Regular Expression Grabbag.
+  ROMAN = /^M*(D?C{0,3}|C[DM])(L?X{0,3}|X[LC])(V?I{0,3}|I[VX])$/i unless const_defined?(:ROMAN)
+
+  ROMAN_VALUES = Integer::ROMAN_VALUES.inject({}) do |h,(r,a)|
+    h[r] = a; h
+  end unless const_defined?(:ROMAN_VALUES)
+
+  # Considers string a Roman numeral numeral,
+  # and converts it to the corresponding integer.
+  #
+  # NOTE: This is not (presently) a common core extension and is not
+  # loaded automatically when using <code>require 'facets'</code>.
+  def roman
+    roman = upcase
+    raise unless roman?
+    last = roman[-1,1]
+    roman.reverse.split('').inject(0) do |result, c|
+      if ROMAN_VALUES[c] < ROMAN_VALUES[last]
+        result -= ROMAN_VALUES[c]
+      else
+        last = c
+        result += ROMAN_VALUES[c]
+      end
+    end
+  end
+
+  # Returns true iif the subject is a valid Roman numeral.
+  #
+  # NOTE: This is not (presently) a common core extension and is not
+  # loaded automatically when using <code>require 'facets'</code>.
+  def roman?
+    ROMAN =~ upcase
+  end
+
+end
+

data/src/core-uncommon/facets/kernel/demo.rb

@@ -0,0 +1,27 @@
+module Kernel
+
+  # For debugging and showing examples. Currently this
+  # takes an argument of a string in a block...
+  #
+  #   demo {%{ a = [1,2,3] }}
+  #   demo {%{ a.slice(1,2) }}
+  #   demo {%{ a.map { |x| x**3 } }}
+  #
+  # produces ...
+  #
+  #   a = [1,2,3]             #=>  [1, 2, 3]
+  #   a.slice(1,2)            #=>  [2, 3]
+  #   a.map { |x| x**3 }      #=>  [1, 8, 27]
+  #
+  # TODO: Is there a way to do this without the eval string in block?
+  # Preferably just a block and no string.
+  #
+  # NOTE: This is not (presently) a common core extension and is not
+  # loaded automatically when using <code>require 'facets'</code>.
+
+  def demo(out=$stdout,&block)
+    out << sprintf("%-25s#=>  %s\n", expr = block.call, eval(expr, block.binding).inspect)
+  end
+
+end
+

data/src/core-uncommon/facets/kernel/eigenclass.rb

@@ -0,0 +1,21 @@
+module Kernel
+
+  # During this trying time when no one can get their
+  # techie catchwords to stick to the refrigerator no
+  # matter how hard they slap it with the enchanted
+  # magnetic spatula, it’s good to know that the
+  # contrived phrases really do fly, graceful and
+  # unclasped and bearing north toward chilled shrimp.
+  # I know what my Hallowe’en pumpkin is going to say.
+  #
+  # NOTE: This is not (presently) a common core extension and is not
+  # loaded automatically when using <code>require 'facets'</code>.
+  #
+  # CREDIT: WhyTheLuckyStiff
+
+  def eigenclass
+    (class << self; self; end)
+  end
+
+end
+

data/src/core-uncommon/facets/kernel/instance_exec.rb

@@ -0,0 +1,44 @@
+class Object #module Kernel
+
+  unless method_defined?(:instance_exec) # 1.9
+
+    require 'thread'
+
+    module InstanceExecMethods #:nodoc:
+    end
+
+    include InstanceExecMethods
+
+    # Evaluate the block with the given arguments within the context of
+    # this object, so self is set to the method receiver.
+    #
+    # From Mauricio's http://eigenclass.org/hiki/bounded+space+instance_exec
+    #
+    # This version has been borrowed from Rails for compatibility sake.
+    #
+    # NOTE: This is not a common core extension (due to the use of thread.rb)
+    # and is not loaded automatically when using <code>require 'facets'</code>.
+    # However it is a core method in Ruby 1.9, so this only matters for users
+    # of Ruby 1.8.x or below.
+
+    def instance_exec(*args, &block)
+      begin
+        old_critical, Thread.critical = Thread.critical, true
+        n = 0
+        n += 1 while respond_to?(method_name = "__instance_exec#{n}")
+        InstanceExecMethods.module_eval { define_method(method_name, &block) }
+      ensure
+        Thread.critical = old_critical
+      end
+
+      begin
+        __send__(method_name, *args)
+      ensure
+        InstanceExecMethods.module_eval { remove_method(method_name) } rescue nil
+      end
+    end
+
+  end
+
+end
+

data/src/core-uncommon/facets/kernel/memo.rb

@@ -0,0 +1,41 @@
+require 'facets/binding/eval'
+require 'facets/kernel/__method__'
+
+module Kernel
+
+  # Global memo cache.
+  $MEMO ||= {}
+
+  # Memoize a method.
+  # 
+  #   class MemoExample
+  #     attr_accessor :a
+  #     def m
+  #       memo{ @a }
+  #     end
+  #   end
+  #
+  #   ex = MemoExample.new
+  #
+  #   ex.a = 10
+  #   ex.m  #=> 10
+  #
+  #   ex.a = 20
+  #   ex.m  #=> 10
+  #
+  # NOTE: This is not (presently) a common core extension and is not
+  # loaded automatically when using <code>require 'facets'</code>.
+
+  def memo(*args, &block)
+    if args.empty?
+      args = block.binding.eval('[self, __method__]')
+    end
+    if $MEMO.key?(args)
+      $MEMO[args]
+    else
+      $MEMO[args] = block.call
+    end
+  end
+
+end
+

data/src/core-uncommon/facets/kernel/trap_chain.rb

@@ -0,0 +1,23 @@
+module Kernel
+  # Calling Kernel#trap() by itself will replace any previously registered
+  # handler code. Kernel#trap_chain(), on the other hand, will add the block
+  # you supply to the existing "list" of registered handler blocks. Similar
+  # to the way Kernel#at_exit() works, Kernel#trap_chain() will prepend the
+  # given block to the call chain for the given signal_name. When the signal
+  # occurs, your block will be executed first and then the previously
+  # registered handler will be invoked. This can be called repeatedly
+  # to create a "chain" of handlers. 
+  #
+  # NOTE: This is not (presently) a common core extension and is not
+  # loaded automatically when using <code>require 'facets'</code>.
+  #
+  # CREDIT: Tyler Rick
+  def trap_chain(signal_name, *args, &block)
+    previous_interrupt_handler = trap(signal_name, *args) {}
+    trap(signal_name, *args) do
+      block.call
+      previous_interrupt_handler.call unless previous_interrupt_handler == "DEFAULT"
+    end
+  end
+
+end

data/src/core-uncommon/facets/kernel/y.rb

@@ -0,0 +1,20 @@
+module Kernel
+
+  # Y-combinator.
+  #
+  #  f = Y do |n, acc, &b|
+  #    n < 2 ? acc : b.(n-1, n * acc) 
+  #  end
+  #
+  #  f.call(5, 1) #=> 120
+  #
+  # NOTE: This is not (presently) a common core extension and is not
+  # loaded automatically when using <code>require 'facets'</code>.
+  #
+  # CREDIT: Michael Fellinger
+
+  def Y(*args, &block)
+    y = lambda{|*args| block.call(*args, &y) }
+  end
+
+end

data/src/core-uncommon/facets/method/memoize.rb

@@ -0,0 +1,13 @@
+class Method
+
+  # Memoize a method by defining a singleton override.
+  #
+  # NOTE: This is not (presently) a common core extension and is not
+  # loaded automatically when using <code>require 'facets'</code>.
+  def memoize(value)
+    singleton = (class << receiver; self; end)
+    singleton.__send__(:define_method, name){ value }
+  end
+
+end
+

data/src/core-uncommon/facets/module/attr_class_accessor.rb

@@ -0,0 +1,39 @@
+class Module
+
+  #
+  # NOTE: This is not (presently) a common core extension and is not
+  # loaded automatically when using <code>require 'facets'</code>.
+  def attr_class_accessor(name)
+    attr_class_reader(name)
+    attr_class_writer(name)
+  end
+
+  #
+  # NOTE: This is not (presently) a common core extension and is not
+  # loaded automatically when using <code>require 'facets'</code>.
+  def attr_class_reader(name)
+    module_eval(<<-EOS, __FILE__, __LINE__)
+      def self.#{name}
+        @#{name}
+      end
+      def #{name}
+        self.class.#{name}
+      end
+    EOS
+  end
+
+  #
+  # NOTE: This is not (presently) a common core extension and is not
+  # loaded automatically when using <code>require 'facets'</code>.
+  def attr_class_writer(name)
+    module_eval(<<-EOS, __FILE__, __LINE__)
+      def self.#{name}=(x)
+        @#{name} = x
+      end
+      def #{name}=(x)
+        self.class.#{name} = x
+      end
+    EOS
+  end
+
+end