Methods
D
E
F
I
S
T
W
Class Public methods
wrap(object)

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

Specifically:

  • If the argument is nil an empty array 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 an array with the argument as its single element 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, if the argument does not respond to to_ary it returns an array with the argument as its single element.

The last point is easily explained with some enumerables:

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

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

[*object]

which returns [] for nil, but calls to Array(object) otherwise.

The differences with Kernel#Array explained above apply to the rest of objects.

   # File activesupport/lib/active_support/core_ext/array/wrap.rb
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
Instance Public methods
deep_dup()

Returns a deep copy of array.

array = [1, [2, 3]]
dup   = array.deep_dup
dup[1][2] = 4

array[1][2] # => nil
dup[1][2]   # => 4
   # File activesupport/lib/active_support/core_ext/object/deep_dup.rb
29 def deep_dup
30   map(&:deep_dup)
31 end
excluding(*elements)

Returns a copy of the Array excluding the specified elements.

["David", "Rafael", "Aaron", "Todd"].excluding("Aaron", "Todd") # => ["David", "Rafael"]
[ [ 0, 1 ], [ 1, 0 ] ].excluding([ [ 1, 0 ] ]) # => [ [ 0, 1 ] ]

Note: This is an optimization of Enumerable#excluding that uses Array#- instead of Array#reject for performance reasons.

   # File activesupport/lib/active_support/core_ext/array/access.rb
47 def excluding(*elements)
48   self - elements.flatten(1)
49 end
extract!()

Removes and returns the elements for which the block returns a true value. If no block is given, an Enumerator is returned instead.

numbers = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
odd_numbers = numbers.extract! { |number| number.odd? } # => [1, 3, 5, 7, 9]
numbers # => [0, 2, 4, 6, 8]
   # File activesupport/lib/active_support/core_ext/array/extract.rb
10 def extract!
11   return to_enum(:extract!) { size } unless block_given?
12 
13   extracted_elements = []
14 
15   reject! do |element|
16     extracted_elements << element if yield(element)
17   end
18 
19   extracted_elements
20 end
extract_options!()

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 activesupport/lib/active_support/core_ext/array/extract_options.rb
24 def extract_options!
25   if last.is_a?(Hash) && last.extractable_options?
26     pop
27   else
28     {}
29   end
30 end
fifth()

Equal to self[4].

%w( a b c d e ).fifth # => "e"
   # File activesupport/lib/active_support/core_ext/array/access.rb
80 def fifth
81   self[4]
82 end
forty_two()

Equal to self[41]. Also known as accessing “the reddit”.

(1..42).to_a.forty_two # => 42
   # File activesupport/lib/active_support/core_ext/array/access.rb
87 def forty_two
88   self[41]
89 end
fourth()

Equal to self[3].

%w( a b c d e ).fourth # => "d"
   # File activesupport/lib/active_support/core_ext/array/access.rb
73 def fourth
74   self[3]
75 end
from(position)

Returns the tail of the array from position.

%w( a b c d ).from(0)  # => ["a", "b", "c", "d"]
%w( a b c d ).from(2)  # => ["c", "d"]
%w( a b c d ).from(10) # => []
%w().from(0)           # => []
%w( a b c d ).from(-2) # => ["c", "d"]
%w( a b c ).from(-10)  # => []
   # File activesupport/lib/active_support/core_ext/array/access.rb
12 def from(position)
13   self[position, length] || []
14 end
in_groups(number, fill_with = nil)

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 8 9 10).in_groups(3, '&nbsp;') {|group| p group}
["1", "2", "3", "4"]
["5", "6", "7", "&nbsp;"]
["8", "9", "10", "&nbsp;"]

%w(1 2 3 4 5 6 7).in_groups(3, false) {|group| p group}
["1", "2", "3"]
["4", "5"]
["6", "7"]
   # File activesupport/lib/active_support/core_ext/array/grouping.rb
62 def in_groups(number, fill_with = nil)
63   # size.div number gives minor group size;
64   # size % number gives how many objects need extra accommodation;
65   # each group hold either division or division + 1 items.
66   division = size.div number
67   modulo = size % number
68 
69   # create a new array avoiding dup
70   groups = []
71   start = 0
72 
73   number.times do |index|
74     length = division + (modulo > 0 && modulo > index ? 1 : 0)
75     groups << last_group = slice(start, length)
76     last_group << fill_with if fill_with != false &&
77       modulo > 0 && length == division
78     start += length
79   end
80 
81   if block_given?
82     groups.each { |g| yield(g) }
83   else
84     groups
85   end
86 end
in_groups_of(number, fill_with = nil)

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 8 9 10).in_groups_of(3) {|group| p group}
["1", "2", "3"]
["4", "5", "6"]
["7", "8", "9"]
["10", nil, nil]

%w(1 2 3 4 5).in_groups_of(2, '&nbsp;') {|group| p group}
["1", "2"]
["3", "4"]
["5", "&nbsp;"]

%w(1 2 3 4 5).in_groups_of(2, false) {|group| p group}
["1", "2"]
["3", "4"]
["5"]
   # File activesupport/lib/active_support/core_ext/array/grouping.rb
22 def in_groups_of(number, fill_with = nil)
23   if number.to_i <= 0
24     raise ArgumentError,
25       "Group size must be a positive integer, was #{number.inspect}"
26   end
27 
28   if fill_with == false
29     collection = self
30   else
31     # size % number gives how many extra we have;
32     # subtracting from number gives how many to add;
33     # modulo number ensures we don't add group of just fill.
34     padding = (number - size % number) % number
35     collection = dup.concat(Array.new(padding, fill_with))
36   end
37 
38   if block_given?
39     collection.each_slice(number) { |slice| yield(slice) }
40   else
41     collection.each_slice(number).to_a
42   end
43 end
including(*elements)

Returns a new array that includes the passed elements.

[ 1, 2, 3 ].including(4, 5) # => [ 1, 2, 3, 4, 5 ]
[ [ 0, 1 ] ].including([ [ 1, 0 ] ]) # => [ [ 0, 1 ], [ 1, 0 ] ]
   # File activesupport/lib/active_support/core_ext/array/access.rb
36 def including(*elements)
37   self + elements.flatten(1)
38 end
inquiry()

Wraps the array in an ArrayInquirer object, which gives a friendlier way to check its string-like contents.

pets = [:cat, :dog].inquiry

pets.cat?     # => true
pets.ferret?  # => false

pets.any?(:cat, :ferret)  # => true
pets.any?(:ferret, :alligator)  # => false
   # File activesupport/lib/active_support/core_ext/array/inquiry.rb
16 def inquiry
17   ActiveSupport::ArrayInquirer.new(self)
18 end
second()

Equal to self[1].

%w( a b c d e ).second # => "b"
   # File activesupport/lib/active_support/core_ext/array/access.rb
59 def second
60   self[1]
61 end
second_to_last()

Equal to self[-2].

%w( a b c d e ).second_to_last # => "d"
    # File activesupport/lib/active_support/core_ext/array/access.rb
101 def second_to_last
102   self[-2]
103 end
split(value = nil)

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 activesupport/lib/active_support/core_ext/array/grouping.rb
 93 def split(value = nil)
 94   arr = dup
 95   result = []
 96   if block_given?
 97     while (idx = arr.index { |i| yield i })
 98       result << arr.shift(idx)
 99       arr.shift
100     end
101   else
102     while (idx = arr.index(value))
103       result << arr.shift(idx)
104       arr.shift
105     end
106   end
107   result << arr
108 end
third()

Equal to self[2].

%w( a b c d e ).third # => "c"
   # File activesupport/lib/active_support/core_ext/array/access.rb
66 def third
67   self[2]
68 end
third_to_last()

Equal to self[-3].

%w( a b c d e ).third_to_last # => "c"
   # File activesupport/lib/active_support/core_ext/array/access.rb
94 def third_to_last
95   self[-3]
96 end
to(position)

Returns the beginning of the array up to position.

%w( a b c d ).to(0)  # => ["a"]
%w( a b c d ).to(2)  # => ["a", "b", "c"]
%w( a b c d ).to(10) # => ["a", "b", "c", "d"]
%w().to(0)           # => []
%w( a b c d ).to(-2) # => ["a", "b", "c"]
%w( a b c ).to(-10)  # => []
   # File activesupport/lib/active_support/core_ext/array/access.rb
24 def to(position)
25   if position >= 0
26     take position + 1
27   else
28     self[0..position]
29   end
30 end
to_default_s(format = :default)
Alias for: to_s
to_formatted_s(format = :default)

Extends Array#to_s to convert a collection of elements into a comma separated id list if :db argument is given as the format.

Blog.all.to_formatted_s(:db)  # => "1,2,3"
Blog.none.to_formatted_s(:db) # => "null"
[1,2].to_formatted_s          # => "[1, 2]"
Also aliased as: to_s
    # File activesupport/lib/active_support/core_ext/array/conversions.rb
 93 def to_formatted_s(format = :default)
 94   case format
 95   when :db
 96     if empty?
 97       "null"
 98     else
 99       collect(&:id).join(",")
100     end
101   else
102     to_default_s
103   end
104 end
to_param()

Calls to_param on all its elements and joins the result with slashes. This is used by url_for in Action Pack.

   # File activesupport/lib/active_support/core_ext/object/to_query.rb
42 def to_param
43   collect(&:to_param).join "/"
44 end
to_query(key)

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 activesupport/lib/active_support/core_ext/object/to_query.rb
50 def to_query(key)
51   prefix = "#{key}[]"
52 
53   if empty?
54     nil.to_query(prefix)
55   else
56     collect { |value| value.to_query(prefix) }.join "&"
57   end
58 end
to_s(format = :default)
Also aliased as: to_default_s
Alias for: to_formatted_s
to_sentence(options = {})

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

You can pass the following options to change the default behavior. If you pass an option key that doesn't exist in the list below, it will raise an ArgumentError.

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 ”).

  • :locale - If i18n is available, you can set a locale and use the connector options defined on the 'support.array' namespace in the corresponding dictionary file.

Examples

[].to_sentence                      # => ""
['one'].to_sentence                 # => "one"
['one', 'two'].to_sentence          # => "one and two"
['one', 'two', 'three'].to_sentence # => "one, two, and three"

['one', 'two'].to_sentence(passing: 'invalid option')
# => ArgumentError: Unknown key: :passing. Valid keys are: :words_connector, :two_words_connector, :last_word_connector, :locale

['one', 'two'].to_sentence(two_words_connector: '-')
# => "one-two"

['one', 'two', 'three'].to_sentence(words_connector: ' or ', last_word_connector: ' or at least ')
# => "one or two or at least three"

Using :locale option:

# Given this locale dictionary:
#
#   es:
#     support:
#       array:
#         words_connector: " o "
#         two_words_connector: " y "
#         last_word_connector: " o al menos "

['uno', 'dos'].to_sentence(locale: :es)
# => "uno y dos"

['uno', 'dos', 'tres'].to_sentence(locale: :es)
# => "uno o dos o al menos tres"
   # File activesupport/lib/active_support/core_ext/array/conversions.rb
61 def to_sentence(options = {})
62   options.assert_valid_keys(:words_connector, :two_words_connector, :last_word_connector, :locale)
63 
64   default_connectors = {
65     words_connector: ", ",
66     two_words_connector: " and ",
67     last_word_connector: ", and "
68   }
69   if defined?(I18n)
70     i18n_connectors = I18n.translate(:'support.array', locale: options[:locale], default: {})
71     default_connectors.merge!(i18n_connectors)
72   end
73   options = default_connectors.merge!(options)
74 
75   case length
76   when 0
77     ""
78   when 1
79     "#{self[0]}"
80   when 2
81     "#{self[0]}#{options[:two_words_connector]}#{self[1]}"
82   else
83     "#{self[0...-1].join(options[:words_connector])}#{options[:last_word_connector]}#{self[-1]}"
84   end
85 end
to_xml(options = {})

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 “objects”:

[{ foo: 1, bar: 2}, { baz: 3}].to_xml

<?xml version="1.0" encoding="UTF-8"?>
<objects type="array">
  <object>
    <bar type="integer">2</bar>
    <foo type="integer">1</foo>
  </object>
  <object>
    <baz type="integer">3</baz>
  </object>
</objects>

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 activesupport/lib/active_support/core_ext/array/conversions.rb
183 def to_xml(options = {})
184   require "active_support/builder" unless defined?(Builder)
185 
186   options = options.dup
187   options[:indent]  ||= 2
188   options[:builder] ||= Builder::XmlMarkup.new(indent: options[:indent])
189   options[:root]    ||= \
190     if first.class != Hash && all? { |e| e.is_a?(first.class) }
191       underscored = ActiveSupport::Inflector.underscore(first.class.name)
192       ActiveSupport::Inflector.pluralize(underscored).tr("/", "_")
193     else
194       "objects"
195     end
196 
197   builder = options[:builder]
198   builder.instruct! unless options.delete(:skip_instruct)
199 
200   root = ActiveSupport::XmlMini.rename_key(options[:root].to_s, options)
201   children = options.delete(:children) || root.singularize
202   attributes = options[:skip_types] ? {} : { type: "array" }
203 
204   if empty?
205     builder.tag!(root, attributes)
206   else
207     builder.tag!(root, attributes) do
208       each { |value| ActiveSupport::XmlMini.to_tag(children, value, options) }
209       yield builder if block_given?
210     end
211   end
212 end
without(*elements)

Alias for excluding.

   # File activesupport/lib/active_support/core_ext/array/access.rb
52 def without(*elements)
53   excluding(*elements)
54 end