class Array

Public Class Methods

wrap(object) click to toggle source

Wraps its argument in an array unless it is already an array (or array-like).

Specifically:

  • If the argument is nil an empty list is returned.

  • Otherwise, if the argument responds to to_ary it is invoked, and its result returned.

  • Otherwise, returns an array with the argument as its single element.

@example nil: an empty list

Array.wrap(nil)       # => []

@example an array: itself

Array.wrap([1, 2, 3]) # => [1, 2, 3]

@example an atom: array of length 1

Array.wrap(0)         # => [0]

This method is similar in purpose to ‘Kernel#Array`, but there are some differences:

  • If the argument responds to to_ary the method is invoked. ‘Kernel#Array`

moves on to try to_a if the returned value is nil, but ‘Array.wrap` returns such a nil right away.

  • If the returned value from to_ary is neither nil nor an Array object, ‘Kernel#Array`

raises an exception, while ‘Array.wrap` does not, it just returns the value.

  • It does not call to_a on the argument, though special-cases nil to return an empty array.

The last point is particularly worth comparing for some enumerables:

@example It does not molest hashes

Array(:foo => :bar)      # => [[:foo, :bar]]
Array.wrap(:foo => :bar) # => [{:foo => :bar}]

@example It does not do insane things to strings

Array("foo\nbar")        # => ["foo\n", "bar"], in Ruby 1.8
Array.wrap("foo\nbar")   # => ["foo\nbar"]

There’s also a related idiom that uses the splat operator:

[*object]

which returns ‘[nil]` for nil, and calls to `Array(object)` otherwise.

Thus, in this case the behavior is different for nil, and the differences with ‘Kernel#Array` explained above apply to the rest of +object+s.

# File lib/gorillib/array/wrap.rb, line 44
def self.wrap(object)
  if object.nil?
    []
  elsif object.respond_to?(:to_ary)
    object.to_ary || [object]
  else
    [object]
  end
end

Public Instance Methods

at_fraction(fraction) click to toggle source

@return the element that fraction of the way along the indexes

@example halfway point:

[1,4,9,16,25].at_fraction(0.5)      #  9

@example note that indexes are rounded down:

[1,4,9,16,25].at_fraction(0.74999)  #  9
[1,4,9,16,25].at_fraction(0.75)     # 16

@example blank array:

[].at_fraction(0.1)       # nil
# File lib/gorillib/array/simple_statistics.rb, line 26
def at_fraction(fraction)
  raise ArgumentError, "fraction should be between 0.0 and 1.0: got #{fraction.inspect}" unless (0.0 .. 1.0).include?(fraction)
  return nil if empty?
  self[ ((size - 1) * Float(fraction)).round ]
end
average() click to toggle source

The average of my elements. precondition: Each element must be convertible to a float.

@return [Float] average of all elements

# File lib/gorillib/array/simple_statistics.rb, line 8
def average
  return nil if empty?
  inject(:+) / size.to_f
end
compact_blank() click to toggle source

remove all key-value pairs where the value is blank

# File lib/gorillib/array/compact_blank.rb, line 7
def compact_blank
  reject{|val| val.blank? }
end
compact_blank!() click to toggle source

Replace the array with its compact_blank‘ed self

# File lib/gorillib/array/compact_blank.rb, line 14
def compact_blank!
  replace(compact_blank)
end
deep_compact!() click to toggle source

deep_compact! removes all ‘blank?’ elements in the array in place, recursively

# File lib/gorillib/array/deep_compact.rb, line 8
def deep_compact!
  self.map! do |val|
    val.deep_compact! if val.respond_to?(:deep_compact!)
    val unless val.blank?
  end.compact!
end
extract_options!() click to toggle source

Extracts options from a set of arguments. Removes and returns the last element in the array if it’s a hash, otherwise returns a blank hash.

def options(*args)
  args.extract_options!
end

options(1, 2)           # => {}
options(1, 2, :a => :b) # => {:a=>:b}
# File lib/gorillib/array/extract_options.rb, line 22
def extract_options!
  if last.is_a?(Hash) && last.extractable_options?
    pop
  else
    {}
  end
end
hashify() click to toggle source

Gets value of block on each element; constructs a hash of element-value pairs

@return [Hash] hash of key-value pairs

# File lib/gorillib/array/hashify.rb, line 7
def hashify
  raise ArgumentError, 'hashify requires a block' unless block_given?
  Hash[ self.map{|el| [el, yield(el)] } ]
end
random_element() click to toggle source

Choose a random element from the array

# File lib/gorillib/deprecated/array/random.rb, line 5
def random_element
  warn "Deprecated; use built-in #sample instead"
  sample
end
sorted_median() click to toggle source

Returns the middle element of odd-sized arrays. For even arrays, it will return one of the two middle elements. Precisely which is undefined, except that it will consistently return one or the other.

The array must be sorted for this to be useful.

# File lib/gorillib/array/simple_statistics.rb, line 61
def sorted_median
  at_fraction(0.5)
end
sorted_percentile(percentile) click to toggle source

Returns the element at the position closest to the given percentile. For example, sorted_percentile 0.0 will return the first element and sorted_percentile 100.0 will return the last element.

The array must be sorted for this to be useful.

# File lib/gorillib/array/simple_statistics.rb, line 73
def sorted_percentile(percentile)
  at_fraction(percentile / 100.0)
end
sorted_sample(num) click to toggle source

DEPRECATED – use uniq_nths(num) (sample is already a method on Array, so this name is confusing)

# File lib/gorillib/deprecated/array/sorted_sample.rb, line 9
def sorted_sample(num)
  sorted_nths(num)
end
take_nths(num) click to toggle source

@return the 1/nth, 2/nth, … n/nth (last) elements in the array.

@example

[1,4,9,16,25,36,49].take_nths(3)  # [4, 16, 36]
[ 4,9,  16,  36,49].take_nths(3)  # [4, 16, 36]
[1,4,9,16,25,36,49].take_nths(5)  # [1, 4, 16, 25, 36]

@example edge cases

[1,4,9,16,25,36,49].take_nths(99) # [1,4,9,16,25,36,49]
[1,4,9,16,25,36,49].take_nths(1)  # [16]
[1,4,9,16,25,36,49].take_nths(0)  # []
[].take_nths(3)                   # []

The array must be sorted for this to be useful.

# File lib/gorillib/array/simple_statistics.rb, line 48
def take_nths(num)
  return [] if empty?
  (0 .. num-1).map{|step| at_fraction( (step + 0.5)/(num)) }.uniq
end
to_sentence(options = {}) click to toggle source

Converts the array to a comma-separated sentence where the last element is joined by the connector word. Options:

  • :words_connector - The sign or word used to join the elements in arrays with two or more elements (default: “, ”)

  • :two_words_connector - The sign or word used to join the elements in arrays with two elements (default: “ and ”)

  • :last_word_connector - The sign or word used to join the last element in arrays with three or more elements (default: “, and ”)

# File lib/gorillib/string/human.rb, line 33
def to_sentence(options = {})
  default_words_connector     = ", "
  default_two_words_connector = " and "
  default_last_word_connector = ", and "
  options = { :words_connector => default_words_connector, :two_words_connector => default_two_words_connector, :last_word_connector => default_last_word_connector }.merge(options)

  case length
    when 0
      ""
    when 1
      self[0].to_s.dup
    when 2
      "#{self[0]}#{options[:two_words_connector]}#{self[1]}"
    else
      "#{self[0...-1].join(options[:words_connector])}#{options[:last_word_connector]}#{self[-1]}"
  end
end
to_tsv() click to toggle source
# File lib/gorillib/model/serialization.rb, line 4
def to_tsv
  to_wire.join("\t")
end
to_wire(options={}) click to toggle source
# File lib/gorillib/serialization/to_wire.rb, line 35
def to_wire(options={})
  map{|item| item.respond_to?(:to_wire) ? item.to_wire : item }
end