class Array

@return [Object] a random item from the array

@example

[1,2,3,4].choice => 2
[1,2,3,4].choice => 4
[1,2,3,4].choice => 3

Implemented in Ruby 1.9

# File lib/sixarm_ruby_ramp/array.rb, line 47
def choice
  self[Kernel.rand(size)]
end

@return [Array] a new array filled with count calls to choice

@example

[1,2,3,4].choices(2) => [3,1]
[1,2,3,4].choices(3) => [4,2,3]

# File lib/sixarm_ruby_ramp/array.rb, line 58
def choices(count)
  arr = Array.new
  count.times { arr << self.choice }
  return arr
end

Divvy the array– REMOVED. Change to sixarm_ruby_array_slice gem Array#slice_by_share method.

# File lib/sixarm_ruby_ramp/array.rb, line 97
def divvy
  raise "Change to sixarm_ruby_array_slice gem Array#slice_by_share method."
end

@return [Array] the intersection of the array's items.

In typical usage, each item is an array.

@example

arr=[[1,2,3,4],[3,4,5,6]]
arr.intersect
=> [3,4]

@example with proc

arr.map(&:foo).intersect
=> foos that are in all of the array items

@example with nil

[].intersect => []

# File lib/sixarm_ruby_ramp/array.rb, line 145
def intersect
  inject{|inj,item| inj & item.to_a } || []
end

Concatenate the items into a string by join.

@return [String] concatenated string

@example Join with infix

list=['a','b','c']
list.join("*") => "a*b*c"

@example Join with prefix and suffix

list=['a','b','c']
list.join("[","]") => "[a][b][c]"

@example Join with prefix, suffix, and infix

list=['a','b','c']
list.join("*","[","]") => "[a]*[b]*[c]"

# File lib/sixarm_ruby_ramp/array/join.rb, line 23
def join(*fixes)
  if fixes.is_a?(String) then return self.ruby_join(fixes) end
  return case fixes.size
  when 0
    ruby_join
  when 1
    ruby_join(fixes[0].to_s)
  when 2
    join_prefix_suffix(*fixes)
  when 3
    join_prefix_suffix_infix(*fixes)
  else
    raise ArgumentError, "join() takes 0-3 arguments; you gave #{fixes.size}]"
  end
end

Concatenate the items by joining using a prefix string and suffix string.

@return [String] concatenated string

@example

list=['a','b','c']
list.join("[","]") => "[a][b][c]"

# File lib/sixarm_ruby_ramp/array/join.rb, line 47
def join_prefix_suffix(prefix, suffix)
  prefix = prefix.to_s
  suffix = suffix.to_s
  return self.map{|item| prefix + item.to_s + suffix}.ruby_join()
end

Concatenate the items by joining using a prefix string, suffix string, and infix string.

@return [String] concatenated string

@example

list=['a','b','c']
list.join("*","[","]") => "[a]*[b]*[c]"

# File lib/sixarm_ruby_ramp/array/join.rb, line 61
def join_prefix_suffix_infix(prefix, suffix, infix)
  prefix = prefix.to_s
  suffix = suffix.to_s
  infix = infix.to_s
  return self.map{|item| prefix + item.to_s + suffix}.ruby_join(infix)
end

@return [Hash] a hash of this array's items as keys,

mapped onto another array's items as values.

@example

foo=[:a,:b,:c]
goo=[:x,:y,:z]
foo.onto(goo) => {:a=>:x, :b=>:y, :c=>:z}

This is identical to calling foo.zip(values).to_h

# File lib/sixarm_ruby_ramp/array.rb, line 75
def onto(values)
  size==values.size or raise ArgumentError, "Array size #{size} must match values size #{size}"
  zip(values).to_h
end

@return [Array] the rest of the items of self, after a shift.

@example

list=['a','b','c']
list.shift => 'a'
list.shifted => ['b','c']

@example with length

list.shifted(0) => ['a','b','c']
list.shifted(1) => ['b','c']
list.shifted(2) => ['c']
list.shifted(3) => []

Ruby programmers may prefer this alias wording:

list.first => 'a'
list.rest => ['b','c']

LISP programmers may prefer this alias wording:

list.car => 'a'
list.cdr => ['b','c']

# File lib/sixarm_ruby_ramp/array.rb, line 179
def shifted(number_of_items=1)
  (number_of_items.is_a? Integer) or (raise ArgumentError, "number_of_items must be an integer")
  (number_of_items >= 0) or (raise ArgumentError, "number_of_items must be >= 0")
  slice(number_of_items,self.length-number_of_items)
end

Delete the first number_of_items items.

@return [Array] the array, minus the deleted items.

@example

list=['a','b','c']
list.shifted!
list => ['b','c']

@example with length:

list=['a','b','c']
list.shifted!(2)
list => ['c']

If n is greater than the array size, then return []

# File lib/sixarm_ruby_ramp/array.rb, line 206
def shifted!(number_of_items=1)
  (number_of_items.is_a? Integer) or (raise ArgumentError, "number_of_items must be an integer")
  (number_of_items >= 0) or (raise ArgumentError, "number_of_items must be >= 0")
  slice!(0,number_of_items)
  return self
end

Randomly arrange the array items.

@return [Array] a new array with the items shuffled.

This implementation is optimized for speed, not for memory use. See codeidol.com/other/rubyckbk/Arrays/Shuffling-an-Array/

@example

list=
list=['a','b','c']
list.shuffle!
list => ['c','a','b']

# File lib/sixarm_ruby_ramp/array/shuffle.rb, line 19
def shuffle
  dup.shuffle!
end

Randomly arrange the array items.

@return [Array] the array, with its items shuffled.

This implementation is optimized for speed, not for memory use. See codeidol.com/other/rubyckbk/Arrays/Shuffling-an-Array/

@example

list=
list=['a','b','c']
list.shuffle!
list => ['c','a','b']

# File lib/sixarm_ruby_ramp/array/shuffle.rb, line 40
def shuffle!
  each_index do |i|
    j = rand(length-i) + i
    self[j], self[i] = self[i], self[j]
  end
end

@return [Boolean] true if size > 0

@example

[1,2,3].size? => true
[].size? => false

# File lib/sixarm_ruby_ramp/array.rb, line 11
def size?
  return size>0
end

Slice the array by size– REMOVED. Change to sixarm_ruby_array_slice gem Array#slice_by_size method.

# File lib/sixarm_ruby_ramp/array.rb, line 90
def slices
  raise "Change to sixarm_ruby_array_slice gem Array#slice_by_size method."
end

@return [String] a CSV (Comma Separated Value) lines

representation of a multi-dimensional array.

Each subarray becomes one line in the output.

@example of a multi-dimensional array

[[1,2,3],[4,5,6]] => ["1,2,3\n", "4,5,6\n"]

# File lib/sixarm_ruby_ramp/array.rb, line 236
def to_csv_lines(ops={})
  map{|row| row.to_csv}
end

@return [String] a CSV (Comma Separated Value) string

representation of a multi-dimensional array.

Each subarray becomes one line in the output.

@example of a multi-dimensional array

[[1,2,3],[4,5,6]] => "1,2,3\n4,5,6\n"

# File lib/sixarm_ruby_ramp/array.rb, line 249
def to_csv_text(ops={})
  to_csv_lines.join
end

@return [String] a TSV (Tab Separated Value) lines

representation of a multi-dimensional array.

Each subarray becomes one line in the output.

@example of a blank array

[[1,2,3],[4,5,6]] => ["1\t2\t3\n", "4\t5\t6\n"]

# File lib/sixarm_ruby_ramp/array.rb, line 263
def to_tsv_lines(ops={})
  map{|row| row.join("\t")+"\n"}
end

@return [String] a TSV (Tab Separated Value) string

representation of a multi-dimensional array.

Each subarray becomes one 'line' in the output.

@example of a blank array

[[1,2,3],[4,5,6]] => "1\t2\t3\n4\t5\t6\n"

# File lib/sixarm_ruby_ramp/array.rb, line 277
def to_tsv_text(ops={})
  to_tsv_lines.join
end

@return [Array] the union of the array's items.

In typical use, each item is an array.

@example using Ruby Array pipe

arr=[[1,2,3,4],[3,4,5,6]]
arr.union => [1,2,3,4,5,6]

@example with proc

arr.map(&:foo).union
=> foos that are in any of the array items

@example with nil

[].union => []

# File lib/sixarm_ruby_ramp/array.rb, line 124
def union
  inject{|inj,item| inj | item.to_a } || []
end