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.
Array.wrap(nil) # => [] Array.wrap([1, 2, 3]) # => [1, 2, 3] 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:
Array(:foo => :bar) # => [[:foo, :bar]] Array.wrap(:foo => :bar) # => [{:foo => :bar}] 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/active_support/core_ext/array/wrap.rb, line 39 39: def self.wrap(object) 40: if object.nil? 41: [] 42: elsif object.respond_to?(:to_ary) 43: object.to_ary || [object] 44: else 45: [object] 46: end 47: end
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/active_support/core_ext/array/extract_options.rb, line 22 22: def extract_options! 23: if last.is_a?(Hash) && last.extractable_options? 24: pop 25: else 26: {} 27: end 28: end
Equal to self[4].
# File lib/active_support/core_ext/array/access.rb, line 38 38: def fifth 39: self[4] 40: end
Equal to self[41]. Also known as accessing “the reddit”.
# File lib/active_support/core_ext/array/access.rb, line 43 43: def forty_two 44: self[41] 45: end
Equal to self[3].
# File lib/active_support/core_ext/array/access.rb, line 33 33: def fourth 34: self[3] 35: end
Returns the tail of the array from position.
%w( a b c d ).from(0) # => %w( a b c d ) %w( a b c d ).from(2) # => %w( c d ) %w( a b c d ).from(10) # => %w() %w().from(0) # => %w()
# File lib/active_support/core_ext/array/access.rb, line 8 8: def from(position) 9: self[position, length] || [] 10: end
Splits or iterates over the array in number of groups, padding any remaining slots with fill_with unless it is false.
%w(1 2 3 4 5 6 7 8 9 10).in_groups(3) {|group| p group} ["1", "2", "3", "4"] ["5", "6", "7", nil] ["8", "9", "10", nil] %w(1 2 3 4 5 6 7).in_groups(3, ' ') {|group| p group} ["1", "2", "3"] ["4", "5", " "] ["6", "7", " "] %w(1 2 3 4 5 6 7).in_groups(3, false) {|group| p group} ["1", "2", "3"] ["4", "5"] ["6", "7"]
# File lib/active_support/core_ext/array/grouping.rb, line 56 56: def in_groups(number, fill_with = nil) 57: # size / number gives minor group size; 58: # size % number gives how many objects need extra accommodation; 59: # each group hold either division or division + 1 items. 60: division = size / number 61: modulo = size % number 62: 63: # create a new array avoiding dup 64: groups = [] 65: start = 0 66: 67: number.times do |index| 68: length = division + (modulo > 0 && modulo > index ? 1 : 0) 69: padding = fill_with != false && 70: modulo > 0 && length == division ? 1 : 0 71: groups << slice(start, length).concat([fill_with] * padding) 72: start += length 73: end 74: 75: if block_given? 76: groups.each { |g| yield(g) } 77: else 78: groups 79: end 80: end
Splits or iterates over the array in groups of size number, padding any remaining slots with fill_with unless it is false.
%w(1 2 3 4 5 6 7).in_groups_of(3) {|group| p group} ["1", "2", "3"] ["4", "5", "6"] ["7", nil, nil] %w(1 2 3).in_groups_of(2, ' ') {|group| p group} ["1", "2"] ["3", " "] %w(1 2 3).in_groups_of(2, false) {|group| p group} ["1", "2"] ["3"]
# File lib/active_support/core_ext/array/grouping.rb, line 19 19: def in_groups_of(number, fill_with = nil) 20: if fill_with == false 21: collection = self 22: else 23: # size % number gives how many extra we have; 24: # subtracting from number gives how many to add; 25: # modulo number ensures we don't add group of just fill. 26: padding = (number - size % number) % number 27: collection = dup.concat([fill_with] * padding) 28: end 29: 30: if block_given? 31: collection.each_slice(number) { |slice| yield(slice) } 32: else 33: groups = [] 34: collection.each_slice(number) { |group| groups << group } 35: groups 36: end 37: end
Backport of Array#sample based on Marc-Andre Lafortune’s github.com/marcandre/backports/ Returns a random element or n random elements from the array. If the array is empty and n is nil, returns nil. If n is passed and its value is less than 0, it raises an ArgumentError exception. If the value of n is equal or greater than 0 it returns [].
[1,2,3,4,5,6].sample # => 4 [1,2,3,4,5,6].sample(3) # => [2, 4, 5] [1,2,3,4,5,6].sample(-3) # => ArgumentError: negative array size [].sample # => nil [].sample(3) # => []
# File lib/active_support/core_ext/array/random_access.rb, line 13 13: def sample(n=nil) 14: return self[Kernel.rand(size)] if n.nil? 15: n = n.to_int 16: rescue Exception => e 17: raise TypeError, "Coercion error: #{n.inspect}.to_int => Integer failed:\n(#{e.message})" 18: else 19: raise TypeError, "Coercion error: obj.to_int did NOT return an Integer (was #{n.class})" unless n.kind_of? Integer 20: raise ArgumentError, "negative array size" if n < 0 21: n = size if n > size 22: result = Array.new(self) 23: n.times do |i| 24: r = i + Kernel.rand(size - i) 25: result[i], result[r] = result[r], result[i] 26: end 27: result[n..size] = [] 28: result 29: end
Equal to self[1].
# File lib/active_support/core_ext/array/access.rb, line 23 23: def second 24: self[1] 25: end
Divides the array into one or more subarrays based on a delimiting value or the result of an optional block.
[1, 2, 3, 4, 5].split(3) # => [[1, 2], [4, 5]] (1..10).to_a.split { |i| i % 3 == 0 } # => [[1, 2], [4, 5], [7, 8], [10]]
# File lib/active_support/core_ext/array/grouping.rb, line 87 87: def split(value = nil) 88: using_block = block_given? 89: 90: inject([[]]) do |results, element| 91: if (using_block && yield(element)) || (value == element) 92: results << [] 93: else 94: results.last << element 95: end 96: 97: results 98: end 99: end
Equal to self[2].
# File lib/active_support/core_ext/array/access.rb, line 28 28: def third 29: self[2] 30: end
Returns the beginning of the array up to position.
%w( a b c d ).to(0) # => %w( a ) %w( a b c d ).to(2) # => %w( a b c ) %w( a b c d ).to(10) # => %w( a b c d ) %w().to(0) # => %w()
# File lib/active_support/core_ext/array/access.rb, line 18 18: def to(position) 19: self.first position + 1 20: end
Converts a collection of elements into a formatted string by calling to_s on all elements and joining them:
Blog.all.to_formatted_s # => "First PostSecond PostThird Post"
Adding in the :db argument as the format yields a comma separated id list:
Blog.all.to_formatted_s(:db) # => "1,2,3"
# File lib/active_support/core_ext/array/conversions.rb, line 46 46: def to_formatted_s(format = :default) 47: case format 48: when :db 49: if respond_to?(:empty?) && self.empty? 50: "null" 51: else 52: collect { |element| element.id }.join(",") 53: end 54: else 55: to_default_s 56: end 57: end
Calls to_param on all its elements and joins the result with slashes. This is used by url_for in Action Pack.
# File lib/active_support/core_ext/object/to_param.rb, line 29 29: def to_param 30: collect { |e| e.to_param }.join '/' 31: end
Converts an array into a string suitable for use as a URL query string, using the given key as the param name.
['Rails', 'coding'].to_query('hobbies') # => "hobbies%5B%5D=Rails&hobbies%5B%5D=coding"
# File lib/active_support/core_ext/object/to_query.rb, line 19 19: def to_query(key) 20: prefix = "#{key}[]" 21: collect { |value| value.to_query(prefix) }.join '&' 22: end
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/active_support/core_ext/array/conversions.rb, line 11 11: def to_sentence(options = {}) 12: if defined?(I18n) 13: default_words_connector = I18n.translate(:'support.array.words_connector', :locale => options[:locale]) 14: default_two_words_connector = I18n.translate(:'support.array.two_words_connector', :locale => options[:locale]) 15: default_last_word_connector = I18n.translate(:'support.array.last_word_connector', :locale => options[:locale]) 16: else 17: default_words_connector = ", " 18: default_two_words_connector = " and " 19: default_last_word_connector = ", and " 20: end 21: 22: options.assert_valid_keys(:words_connector, :two_words_connector, :last_word_connector, :locale) 23: options.reverse_merge! :words_connector => default_words_connector, :two_words_connector => default_two_words_connector, :last_word_connector => default_last_word_connector 24: 25: case length 26: when 0 27: "" 28: when 1 29: self[0].to_s.dup 30: when 2 31: "#{self[0]}#{options[:two_words_connector]}#{self[1]}" 32: else 33: "#{self[0...-1].join(options[:words_connector])}#{options[:last_word_connector]}#{self[-1]}" 34: end 35: end
Returns a string that represents the array in XML by invoking to_xml on each element. Active Record collections delegate their representation in XML to this method.
All elements are expected to respond to to_xml, if any of them does not then an exception is raised.
The root node reflects the class name of the first element in plural if all elements belong to the same type and that’s not Hash:
customer.projects.to_xml <?xml version="1.0" encoding="UTF-8"?> <projects type="array"> <project> <amount type="decimal">20000.0</amount> <customer-id type="integer">1567</customer-id> <deal-date type="date">2008-04-09</deal-date> ... </project> <project> <amount type="decimal">57230.0</amount> <customer-id type="integer">1567</customer-id> <deal-date type="date">2008-04-15</deal-date> ... </project> </projects>
Otherwise the root element is “records”:
[{:foo => 1, :bar => 2}, {:baz => 3}].to_xml <?xml version="1.0" encoding="UTF-8"?> <records type="array"> <record> <bar type="integer">2</bar> <foo type="integer">1</foo> </record> <record> <baz type="integer">3</baz> </record> </records>
If the collection is empty the root element is “nil-classes” by default:
[].to_xml <?xml version="1.0" encoding="UTF-8"?> <nil-classes type="array"/>
To ensure a meaningful root element use the :root option:
customer_with_no_projects.projects.to_xml(:root => "projects") <?xml version="1.0" encoding="UTF-8"?> <projects type="array"/>
By default name of the node for the children of root is root.singularize. You can change it with the :children option.
The options hash is passed downwards:
Message.all.to_xml(:skip_types => true) <?xml version="1.0" encoding="UTF-8"?> <messages> <message> <created-at>2008-03-07T09:58:18+01:00</created-at> <id>1</id> <name>1</name> <updated-at>2008-03-07T09:58:18+01:00</updated-at> <user-id>1</user-id> </message> </messages>
# File lib/active_support/core_ext/array/conversions.rb, line 136 136: def to_xml(options = {}) 137: require 'active_support/builder' unless defined?(Builder) 138: 139: options = options.dup 140: options[:indent] ||= 2 141: options[:builder] ||= Builder::XmlMarkup.new(:indent => options[:indent]) 142: options[:root] ||= if first.class.to_s != "Hash" && all? { |e| e.is_a?(first.class) } 143: underscored = ActiveSupport::Inflector.underscore(first.class.name) 144: ActiveSupport::Inflector.pluralize(underscored).tr('/', '_') 145: else 146: "objects" 147: end 148: 149: builder = options[:builder] 150: builder.instruct! unless options.delete(:skip_instruct) 151: 152: root = ActiveSupport::XmlMini.rename_key(options[:root].to_s, options) 153: children = options.delete(:children) || root.singularize 154: 155: attributes = options[:skip_types] ? {} : {:type => "array"} 156: return builder.tag!(root, attributes) if empty? 157: 158: builder.__send__(:method_missing, root, attributes) do 159: each { |value| ActiveSupport::XmlMini.to_tag(children, value, options) } 160: yield builder if block_given? 161: end 162: end
Returns an unique array based on the criteria given as a Proc.
[1, 2, 3, 4].uniq_by { |i| i.odd? } # => [1, 2]
# File lib/active_support/core_ext/array/uniq_by.rb, line 6 6: def uniq_by 7: hash, array = {}, [] 8: each { |i| hash[yield(i)] ||= (array << i) } 9: array 10: end
Same as uniq_by, but modifies self.
# File lib/active_support/core_ext/array/uniq_by.rb, line 13 13: def uniq_by! 14: replace(uniq_by{ |i| yield(i) }) 15: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.