functional-ruby 0.7.4 → 0.7.5

data/lib/functional/collection.rb

@@ -0,0 +1,403 @@
+module Functional
+
+  module Collection
+    extend self
+
+    # Returns a random sample of #size integers between 0 and 100 or
+    # the provided :min and/or :max options.
+    #
+    # @param [Integer] size the size of the sample to create
+    # @param [Hash] opts processing options
+    #
+    # @option opts [Integer] :min the minimum value in the sample
+    # @option opts [Integer] :max the maximun value in the sample
+    #
+    # @return [Array] an array of integers
+    def random_sample(size, opts={})
+      min = opts[:min].to_i
+      max = opts[:max] || 100
+      sample = []
+      size.times do
+        sample << rand(max-min) + min
+      end
+      return sample
+    end
+
+    # Return the index where to insert item x in list a, assuming a is sorted.
+    #   
+    # The return value i is such that all e in a[:i] have e < x, and all e in
+    # a[i:] have e >= x.  So if x already appears in the list, a.insert(x) will
+    # insert just before the leftmost x already there.
+    #
+    # Optional args lo (default 0) and hi (default len(a)) bound the
+    # slice of a to be searched.
+    #
+    # @see http://docs.python.org/3/library/bisect.html
+    # @see http://hg.python.org/cpython/file/3.3/Lib/bisect.py
+    # @see http://effbot.org/librarybook/bisect.htm
+    def bisect_left(a, x, opts={})
+      return nil if a.nil?
+      return 0 if a.empty?
+
+      lo = (opts[:lo] || opts[:low]).to_i
+      hi = opts[:hi] || opts[:high] || a.length
+
+      while lo < hi
+        mid = (lo + hi) / 2
+        v = (block_given? ? yield(a[mid]) : a[mid])
+        if v < x
+          lo = mid + 1
+        else
+          hi = mid
+        end
+      end
+      return lo
+    end
+
+    # Return the index where to insert item x in list a, assuming a is sorted.
+    #
+    # The return value i is such that all e in a[:i] have e <= x, and all e in
+    # a[i:] have e > x.  So if x already appears in the list, a.insert(x) will
+    # insert just after the rightmost x already there.
+    #
+    # Optional args lo (default 0) and hi (default len(a)) bound the
+    # slice of a to be searched.
+    #
+    # @see http://docs.python.org/3/library/bisect.html
+    # @see http://hg.python.org/cpython/file/3.3/Lib/bisect.py
+    # @see http://effbot.org/librarybook/bisect.htm
+    def bisect_right(a, x, opts={})
+      return nil if a.nil?
+      return 0 if a.empty?
+
+      lo = (opts[:lo] || opts[:low]).to_i
+      hi = opts[:hi] || opts[:high] || a.length
+
+      while lo < hi
+        mid = (lo + hi) / 2
+        v = (block_given? ? yield(a[mid]) : a[mid])
+        if x < v
+          hi = mid
+        else
+          lo = mid + 1
+        end
+      end
+      return lo
+    end
+
+    alias_method :bisect, :bisect_right
+
+    # Insert item x in list a, and keep it sorted assuming a is sorted.
+    # 
+    # If x is already in a, insert it to the left of the leftmost x.
+    #
+    # Optional args lo (default 0) and hi (default len(a)) bound the
+    # slice of a to be searched. 
+    #
+    # @see http://docs.python.org/3/library/bisect.html
+    # @see http://hg.python.org/cpython/file/3.3/Lib/bisect.py
+    # @see http://effbot.org/librarybook/bisect.htm
+    def insort_left(a, x, opts={}, &block)
+      return [x] if a.nil?
+      if a.respond_to?(:dup)
+        a = a.dup
+      else
+        a = collect(a)
+      end
+      return insort_left!(a, x, opts, &block)
+    end
+
+    # Insert item x in list a, and keep it sorted assuming a is sorted.
+    # Returns a duplicate of the original list, leaving it intact.
+    # 
+    # If x is already in a, insert it to the left of the leftmost x.
+    #
+    # Optional args lo (default 0) and hi (default len(a)) bound the
+    # slice of a to be searched. 
+    #
+    # @see http://docs.python.org/3/library/bisect.html
+    # @see http://hg.python.org/cpython/file/3.3/Lib/bisect.py
+    # @see http://effbot.org/librarybook/bisect.htm
+    def insort_left!(a, x, opts={}, &block)
+      return [x] if a.nil?
+      return a << x if a.empty?
+
+      v = (block_given? ? yield(x) : x)
+      index = bisect_left(a, v, opts, &block)
+      return a.insert(index, x)
+    end
+
+    # Insert item x in list a, and keep it sorted assuming a is sorted.
+    # Returns a duplicate of the original list, leaving it intact.
+    #
+    # If x is already in a, insert it to the right of the rightmost x.
+    #
+    # Optional args lo (default 0) and hi (default len(a)) bound the
+    # slice of a to be searched. 
+    #
+    # @see http://docs.python.org/3/library/bisect.html
+    # @see http://hg.python.org/cpython/file/3.3/Lib/bisect.py
+    # @see http://effbot.org/librarybook/bisect.htm
+    def insort_right(a, x, opts={}, &block)
+      return [x] if a.nil?
+      if a.respond_to?(:dup)
+        a = a.dup
+      else
+        a = collect(a)
+      end
+      return insort_right!(a, x, opts, &block)
+    end
+
+    alias_method :insort, :insort_right
+
+    # Insert item x in list a, and keep it sorted assuming a is sorted.
+    #
+    # If x is already in a, insert it to the right of the rightmost x.
+    #
+    # Optional args lo (default 0) and hi (default len(a)) bound the
+    # slice of a to be searched. 
+    #
+    # @see http://docs.python.org/3/library/bisect.html
+    # @see http://hg.python.org/cpython/file/3.3/Lib/bisect.py
+    # @see http://effbot.org/librarybook/bisect.htm
+    def insort_right!(a, x, opts={}, &block)
+      return [x] if a.nil?
+      return a << x if a.empty?
+
+      v = (block_given? ? yield(x) : x)
+      index = bisect_right(a, v, opts, &block)
+      return a.insert(index, x)
+    end
+
+    alias_method :insort!, :insort_right!
+
+    # Collect sample data from a generic collection, processing each item
+    # with a block when given. Returns an array of the items from +data+
+    # in order.
+    # 
+    # When a block is given the block will be applied to both arguments.
+    # Using a block in this way allows computation against a specific field
+    # in a data set of hashes or objects.
+    #
+    # @yield iterates over each element in the data set
+    # @yieldparam item each element in the data set
+    #
+    # @param [Enumerable] data the data set to be collected
+    #
+    # @return [Array] an array of zero or more items
+    def collect(data, opts={})
+      return [] if data.nil?
+      sample = []
+      data.each do |datum|
+        datum = yield(datum) if block_given?
+        sample << datum
+      end
+      return sample
+    end
+
+    # Collect sample data from a generic collection, processing each item
+    # with a block when given. Returns an array of arrays. Each element
+    # is a two-element array where the first element is the index within
+    # the outer array and the second element is the corresponding item
+    # from within +data+. The elements in the returned array are in the
+    # same order as the original +data+ collection.
+    #
+    # @example
+    #   sample = [5, 1, 9, 3, 14, 9, 7]
+    #   Collection.catalog(sample) #=> [[0, 5], [1, 1], [2, 9], [3, 3], [4, 14], [5, 9], [6, 7]]
+    # 
+    # When a block is given the block will be applied to both arguments.
+    # Using a block in this way allows computation against a specific field
+    # in a data set of hashes or objects.
+    #
+    # @yield iterates over each element in the data set
+    # @yieldparam item each element in the data set
+    #
+    # @param [Enumerable] data the data set to be collected
+    #
+    # @return [Array] an array of zero or more items
+    def index_and_catalog(data, opts={})
+      return [] if data.nil?
+      sample = []
+      index = 0
+      data.each do |datum|
+        datum = yield(datum) if block_given?
+        sample << [index, datum]
+        index += 1
+      end
+      return sample
+    end
+
+    alias_method :index_and_catalogue, :index_and_catalog
+
+    # Convert a hash to catalog.
+    # 
+    # When a block is given the block will be applied to both arguments.
+    # Using a block in this way allows computation against a specific field
+    # in a data set of hashes or objects.
+    #
+    # @yield iterates over each element in the data set
+    # @yieldparam item each element in the data set
+    #
+    # @param [Enumerable] data the data to convert
+    # @param [Hash] opts search options
+    #
+    # @return [Array] if the data set is in ascending order
+    def catalog_hash(data, opts={})
+      return [] if data.nil? || data.empty?
+      catalog = []
+      data.each do |key, value|
+        value = yield(value) if block_given?
+        catalog << [key, value]
+      end
+      return catalog
+    end
+
+    alias_method :catalogue_hash, :catalog_hash
+
+    # Convert a catalog to a hash. Keeps the last value when keys are
+    # duplicated.
+    # 
+    # When a block is given the block will be applied to both arguments.
+    # Using a block in this way allows computation against a specific field
+    # in a data set of hashes or objects.
+    #
+    # @yield iterates over each element in the data set
+    # @yieldparam item each element in the data set
+    #
+    # @param [Enumerable] data the data to convert
+    # @param [Hash] opts search options
+    #
+    # @return [Hash] if the data set is in ascending order
+    def hash_catalog(data, opts={})
+      return {} if data.nil? || data.empty?
+      hash = {}
+      data.each do |item|
+        value = (block_given? ? yield(item.last) : item.last)
+        hash[item.first] = value
+      end
+      return hash
+    end
+
+    alias_method :hash_catalogue, :hash_catalog
+
+    # Scan a collection and determine if the elements are all in
+    # ascending order. Returns true for an empty set and false for
+    # a nil sample.
+    # 
+    # When a block is given the block will be applied to both arguments.
+    # Using a block in this way allows computation against a specific field
+    # in a data set of hashes or objects.
+    #
+    # @yield iterates over each element in the data set
+    # @yieldparam item each element in the data set
+    #
+    # @param [Enumerable] data the data set to search
+    # @param [Hash] opts search options
+    #
+    # @return [true, false] if the data set is in ascending order
+    def ascending?(data, opts={})
+      return false if data.nil?
+      (data.size-1).times do |i|
+        if block_given?
+          return false if yield(data[i]) > yield(data[i+1])
+        else
+          return false if data[i] > data[i+1]
+        end
+      end
+      return true
+    end
+
+    # Scan a collection and determine if the elements are all in
+    # descending order. Returns true for an empty set and false for
+    # a nil sample.
+    # 
+    # When a block is given the block will be applied to both arguments.
+    # Using a block in this way allows computation against a specific field
+    # in a data set of hashes or objects.
+    #
+    # @yield iterates over each element in the data set
+    # @yieldparam item each element in the data set
+    #
+    # @param [Enumerable] data the data set to search
+    # @param [Hash] opts search options
+    #
+    # @return [true, false] if the data set is in descending order
+    def descending?(data, opts={})
+      return false if data.nil?
+      (data.size-1).times do |i|
+        if block_given?
+          return false if yield(data[i]) < yield(data[i+1])
+        else
+          return false if data[i] < data[i+1]
+        end
+      end
+      return true
+    end
+
+    # Override of #slice from Ruby Array. Provides a consistent interface
+    # to slice data structures that do not have a native #slice method.
+    #
+    # Returns the element at index, or returns a subarray starting at
+    # start and continuing for length elements, or returns a subarray
+    # specified by range. Negative indices count backward from the end
+    # of the array (-1 is the last element). Returns nil if the index
+    # (or starting index) is out of range.
+    #
+    # @overload slice(data, index)
+    #   @param [Enumerable] data the collection to slice
+    #   @param [Integer] index the index to slice
+    #
+    # @overload slice(data, start, length)
+    #   @param [Enumerable] data the collection to slice
+    #   @param [Integer] start the start index for the slice
+    #   @param [Integer] length the length of the slice
+    #
+    # @overload slice(data, range)
+    #   @param [Enumerable] data the collection to slice
+    #   @param [Range] range range of indices to include in the slice
+    #
+    # @return [Array] the slice
+    def slice(data, *args)
+      index = args[0]
+      length = args[1]
+      if args.size == 1
+        if index.is_a? Range
+          slice_with_range(data, index)
+        else
+          slice_with_index(data, index)
+        end
+      elsif args.size == 2
+        slice_with_length(data, index, length)
+      else
+        raise ArgumentError.new("wrong number of arguments (#{args.size} for 2..3)")
+      end
+    end
+
+    # :nodoc:
+    # @private
+    def slice_with_index(data, index)
+      return data[index]
+    end
+
+    # :nodoc:
+    # @private
+    def slice_with_length(data, start, length)
+      range = Range.new(start, start+length-1)
+      slice_with_range(data, range)
+    end
+
+    # :nodoc:
+    # @private
+    def slice_with_range(data, range)
+      return nil if range.first < 0 || range.first >= data.size
+      last = [range.last, data.size-1].min
+      range = Range.new(range.first, last)
+      slice = []
+      range.each do |index|
+        slice << data[index]
+      end
+      return slice
+    end
+  end
+end

data/lib/functional/inflect.rb

@@ -0,0 +1,127 @@
+module Functional
+
+  module Inflect
+    extend self
+
+    # By default, +camelize+ converts strings to UpperCamelCase. If the argument
+    # to +camelize+ is set to <tt>:lower</tt> then +camelize+ produces
+    # lowerCamelCase.
+    #
+    # +camelize+ will also convert '/' to '::' which is useful for converting
+    # paths to namespaces.
+    #
+    #   'active_model'.camelize                # => "ActiveModel"
+    #   'active_model'.camelize(:lower)        # => "activeModel"
+    #   'active_model/errors'.camelize         # => "ActiveModel::Errors"
+    #   'active_model/errors'.camelize(:lower) # => "activeModel::Errors"
+    #
+    # As a rule of thumb you can think of +camelize+ as the inverse of
+    # +underscore+, though there are cases where that does not hold:
+    #
+    #   'SSLError'.underscore.camelize # => "SslError"
+    #
+    # @see https://github.com/rails/rails/blob/master/activesupport/lib/active_support/inflector/methods.rb
+    def camelize(term, uppercase_first_letter = true)
+      string = term.to_s
+      if uppercase_first_letter == true
+        string = string.sub(/^[a-z\d]*/) { $&.capitalize }
+      else
+        string = string.sub(/^(?:(?=\b|[A-Z_])|\w)/) { $&.downcase }
+      end
+      string.gsub(/(?:_|(\/))([a-z\d]*)/i) { "#{$1}#{$2.capitalize}" }.gsub('/', '::')
+    end
+
+    # Makes an underscored, lowercase form from the expression in the string.
+    #
+    # Changes '::' to '/' to convert namespaces to paths.
+    #
+    #   'ActiveModel'.underscore         # => "active_model"
+    #   'ActiveModel::Errors'.underscore # => "active_model/errors"
+    #
+    # As a rule of thumb you can think of +underscore+ as the inverse of
+    # +camelize+, though there are cases where that does not hold:
+    #
+    #   'SSLError'.underscore.camelize # => "SslError"
+    #
+    # @see https://github.com/rails/rails/blob/master/activesupport/lib/active_support/inflector/methods.rb
+    def underscore(camel_cased_word)
+      word = camel_cased_word.to_s.dup
+      word.gsub!('::', '/')
+      word.gsub!(/\s+/, '_')
+      word.gsub!(/([A-Z\d]+)([A-Z][a-z])/,'\1_\2')
+      word.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
+      word.tr!("-", "_")
+      word.downcase!
+      word
+    end
+
+    # Capitalizes the first word and turns underscores into spaces and strips a
+    # trailing "_id", if any. Like +titleize+, this is meant for creating pretty
+    # output.
+    #
+    #   'employee_salary'.humanize # => "Employee salary"
+    #   'author_id'.humanize       # => "Author"
+    #
+    # @see https://github.com/rails/rails/blob/master/activesupport/lib/active_support/inflector/methods.rb
+    def humanize(lower_case_and_underscored_word)
+      result = lower_case_and_underscored_word.to_s.dup
+      result.gsub!(/_id$/, "")
+      result.tr!('_', ' ')
+      result.gsub(/([a-z\d]*)/i) { |match| "#{match.downcase}" }.gsub(/^\w/) { $&.upcase }
+    end
+
+    # Capitalizes all the words and replaces some characters in the string to
+    # create a nicer looking title. +titleize+ is meant for creating pretty
+    # output. It is not used in the Rails internals.
+    #
+    # +titleize+ is also aliased as +titlecase+.
+    #
+    #   'man from the boondocks'.titleize   # => "Man From The Boondocks"
+    #   'x-men: the last stand'.titleize    # => "X Men: The Last Stand"
+    #   'TheManWithoutAPast'.titleize       # => "The Man Without A Past"
+    #   'raiders_of_the_lost_ark'.titleize  # => "Raiders Of The Lost Ark"
+    #
+    # @see https://github.com/rails/rails/blob/master/activesupport/lib/active_support/inflector/methods.rb
+    def titleize(word)
+      #humanize(underscore(word)).gsub(/\b(?<!['`])[a-z]/) { $&.capitalize }
+      humanize(underscore(word)).gsub(/\b["'`]?[a-z]/) { $&.capitalize }
+    end
+
+    # Replaces underscores with dashes in the string.
+    #
+    #   'puni_puni'.dasherize # => "puni-puni"
+    #
+    # @see https://github.com/rails/rails/blob/master/activesupport/lib/active_support/inflector/methods.rb
+    def dasherize(underscored_word)
+      underscored_word.to_s.dup.tr('_', '-')
+    end
+
+    # Add the given extension to the given file name. Removes the current
+    # extension if one exists. Strips trailing characters from the file name
+    # if present. Does nothing if the file name already has the given
+    # extension.
+    #
+    # @example
+    #   extensionize('my_file.png', :png) #=> 'my_file.png'
+    #   extensionize('my_file', :png)     #=> 'my_file.png'
+    #   extensionize('my_file.png', :jpg) #=> 'my_file.png.jpg'
+    #   extensionize('My File', :png)     #=> 'My File.png'
+    #   extensionize('My File    ', :png) #=> 'My File.png'
+    #   extensionize('my_file.png', :jpg, :chomp => true) #=> 'my_file.jpg'
+    #
+    # @param [String] fname the name of the file to add an extension to
+    # @param [String, Symbol] ext the extension to append, with or without a leading dot
+    # @param [Hash] opts processing options
+    #
+    # @option opts [Symbol] :chomp when true removes the existing entension
+    #   from the file name (default: false)
+    #
+    # @return [String] the *fname* with *ext* appended
+    def extensionize(fname, ext, opts={})
+      extname = File.extname(fname)
+      return fname if (extname =~ /\.?#{ext}$/i) == 0
+      fname = fname.gsub(/#{extname}$/, '') if opts[:chomp] == true
+      return fname.strip + '.' + ext.to_s.gsub(/^\./, '')
+    end
+  end
+end