Returns true if the receiver is false, empty, or a string of whitespace:

"Keep calm and carry on".blank? # => false
"    ".blank?                   # => true
"".blank?                       # => true
[].blank?                       # => true
["apple"].blank?                # => false
42.blank?                       # => false
true.blank?                     # => false
nil.blank?                      # => true

This behaviour means you can replace code like this

if !title.nil? && !title.empty?
  # do something
end

with this instead:

if !title.blank?
  # do something
end

Returns the negation of Object#blank? – let’s use that to reduce the previous example to just

if title.present?
  # do something
end

Returns a URL query string using the key as the parameter name and the receiver as the value:

"Snow".to_query("white")     # => "white=Snow"
7.to_query("stinky dwarves") # => "stinky+dwarves=7"

Attempts to call a method with whatever arguments and optional block. In the event the method doesn’t exist, it returns nil instead of raising a NoMethod exception.

What this means is that you can turn lines like

@video && @person.title

into

@video.try(:title)

Provides a more complete interface compared to just using alias or alias_method to give another name to an Active Record model’s attribute:

class Video < ActiveRecord::Base

  # Adds #name-version aliases for:
  #   #title
  #   #title?
  #   #title=
  alias_attribute :name, :title
end

v = Video.first

v.name  # => "John Candy"
v.name?  # => true
v.name = "Canadian Bacon"  # => "Canadian Bacon"
v.title  # => "Canadian Bacon"

Makes writing method wrappers using aliases easy.

Let’s say that you want to wrap each call to a method Video#calculate_rating with a logging statement indicating that a rating has been calculated.

One way to do it would be the following:

class Video < ActiveRecord::Base
  def calculate_rating
    # does some kind of rating calculation
  end
  
  def calculate_rating_with_logging(*args)
    logger.info "Calulating a rating!"
    calculate_rating_without_logging(*args)
  end
  
  alias_method :calculate_rating_without_logging, :calculate_rating
  alias_method :calculate_rating, :calculate_rating_with_logging
end

By using aliases to wrap the #calculate_rating method we’ve unobtrusively added logging. This pattern is popular enough that Active Support extended Module to have a method alias_method_chain(target, feature) which does some meta-programming to specifically look for a method named target_with_feature and constructs the corresponding aliases for you to use. Here’s how to rewrite the above using it:

class Video < ActiveRecord::Base
  def calculate_rating
    # does some kind of rating calculation
  end
  
  def calculate_rating_with_logging(*args)
    logger.info "Calulating a rating!"
    calculate_rating_without_logging(*args)
  end
  
  alias_method_chain :calculate_rating, :logging
end

The key to alias_method_chain is that we’ve written a method according to the expected pattern named correctly: calculate_rating_with_logging – again, going by the method definintion, that’s target_with_feature and making use of target_without_feature inside of it.

Returns true or false whether the integer is evenly divisible by number:

8.multiple_of?(2)  # => true
9.multiple_of?(3)  # => true
10.multiple_of?(3) # => false

Rounds the Float by the given precision:

x = 1.337
x.round    # => 1
x.round(1) # => 1.3
x.round(2) # => 1.34

Returns a Hash consisting of the strict difference between the Hash and the other_hash:

        {1 => 2}.diff(1 => 2) # => {}
        {1 => 2}.diff(1 => 3) # => {1 => 2}
              {}.diff(1 => 2) # => {1 => 2}
{1 => 2, 3 => 4}.diff(1 => 2) # => {3 => 4}

Returns a copy of the Hash with only the given keys. Useful for limiting an options hash to a set of valid keys prior to processing.

{:mass => 2, :speed => 4, :deliciosity => 6}.slice(:mass, :speed)
# => {:mass=>2, :speed=>4}

When limiting based on an Array of keys, splat the Array when passing it to #slice:

valid_keys = [:mass, :speed]

{:mass => 2, :speed => 4, :deliciosity => 6}.slice(*valid_keys)
# => {:mass=>2, :speed=>4}

Hash#slice! is also available, replacing the Hash in-place.

Returns a copy of the Hash without the given keys:

{:a => 1, :b => 2}.except(:a)    # => {:b => 2}

If the Hash or Hash class-descendent responds to #convert_key, that method is called on each key prior to determining if the key/value pair should be included in the returned results. (This is how Rails’ hashes with indifferent access work:

{:a => 1}.with_indifferent_access.except("a") # => {}

Hash#except! also exists, destructively modifying the Hash in-place.

Returns a Hash using the given keys, removing those key/value pairs extracted.

h = {"rock" => "lobster", "king" => "crimson"}

h.extract!("king") # => {"king" => "crimson"}
h  # => {"rock" => "lobster"}

Asserts that the Hash’s keys are valid_keys, raising ArgumentError upon a mismatch or absence.

h = {:name => "Edward", :age => 26}
                                
h.assert_valid_keys(:name, :age)  # => no exception raised
h.assert_valid_keys(:name, :hair_colour) # => mismatch; exception raised
h.assert_valid_keys(:name)  # => absence; exception raised

Merges an other_hash with the Hash, giving precedent to the Hash this method is called on.

{:red => "Swingline"}.reverse_merge(:blue => "Whale")
# => {:blue=>"Whale", :red=>"Swingline"}

{:red => "Swingline"}.reverse_merge(:red => "Ninja Turtle")
# => {:red=>"Swingline"}

Hash#reverse_merge!, the in-place, destructive version, is particularly useful for initializing an option hash with default values in a way that reads nicely:

def setup(options = {})
  options.reverse_merge! :size => 25, :velocity => 10
end

This example setup method sets a default :size and :velocity if the options hash passed in didn’t set them.

Returns a new Hash produced from merging the Hash this method is called on, and the other_hash, merged recursively with precedence given to other_hash.

hash_1 = { :a => "a",
           :b => "b",
           :c => { :c1 => "c1", 
                   :c2 => "c2", 
                   :c3 => { :d1 => "d1" } } }
hash_2 = { :a => 1, 
           :c => { :c1 => 2, 
                   :c3 => { :d2 => "d2" } } }
                                
hash_1.deep_merge!(hash_2)
# => { :a => 1, 
#      :b => "b", 
#      :c => { :c1 => 2, 
#              :c2 => "c2", 
#              :c3 => { :d1 => "d1", 
#                       :d2 => "d2" } } }

A Hash#deep_merge! variant also exists, destructively altering the Hash in-place.

Returns a URL query string using the keys and values of the Hash this method is called on:

{ :name => 'Edward', :nationality => 'Canadian' }.to_param
# => "name=Edward&nationality=Canadian"

When an optional namespace is provided, it’s used accordingly:

{ :name => 'Edward', :nationality => 'Canadian' }.to_param('author')
# => "author[name]=Edward&author[nationality]=Canadian"

An alias for #to_param.

Splits up an Array into groups containing number elements, optionally filling in remainder slots with fill_with unless it’s false:

[1, 2, 3, 4, 5, 6, 7].in_groups_of(3)
# => [[1, 2, 3], [4, 5, 6], [7, nil, nil]]

[1, 2, 3, 4, 5, 6, 7].in_groups_of(3, ' ')
# => [[1, 2, 3], [4, 5, 6], [7, " ", " "]]

[1, 2, 3, 4, 5, 6, 7].in_groups_of(3, false)
# => [[1, 2, 3], [4, 5, 6], [7]]

Array#in_groups_of also conveniently yields each group when passed a block:

[1, 2, 3, 4, 5, 6, 7].in_groups_of(3, false) {|group| puts group.size }
# => prints "3\n3\n1"

Splits up an Array into number groups, optionally filling in remainder slots with fill_with unless it’s false:

[1, 2, 3, 4, 5, 6, 7].in_groups(3)
# => [[1, 2, 3], [4, 5, nil], [6, 7, nil]]

[1, 2, 3, 4, 5, 6, 7].in_groups(3, ' ')
# => [[1, 2, 3], [4, 5, " "], [6, 7, " "]]

[1, 2, 3, 4, 5, 6, 7].in_groups(3, false)
# => [[1, 2, 3], [4, 5], [6, 7]]

Array#in_groups also conveniently yields each group when passed a block:

[1, 2, 3, 4, 5, 6, 7].in_groups(3, false) {|group| puts group.size }
# => prints "3\n2\n2"

Splits up an Array into 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]]

Returns a random element from the Array:

[1, 2, 3, 4, 5].sample # => 5

This method is backported from Ruby 1.9

Returns a String to be used as part of a URL. Produced by calling #to_param on each element and joining the results with forward-slashes. Used by Action Pack’s url_for:

["brave", "new", "world"].to_param # => "brave/new/world"

Returns a URL query string using the given key as the parameter name and the Array this method is called on as the values:

['Documenting', 'makes me thirsty'].to_query('thoughts')
# => "thoughts%5B%5D=Documenting&thoughts%5B%5D=makes+me+thirsty"

Returns an Array of unique elements based on criteria in a supplied block.

[1, 2, 3, 4].uniq_by { |i| i.odd? }    # => [1, 2]

Array#uniq_by! is also available, doing the same thing but modifies the Array in-place.

Extracts options from a set of arguments, removing and returning the last element if it's a Hash or an empty Hash if not. Particularly useful when writing a method that takes *args as arguments, yet still needs to take a Hash of options:

def awesome(*args)
  options = args.extract_options!

  puts "The options are #{options.inspect}"
  puts "The arguments are #{args.inspect}"
end

awesome("dogs", "cats", "bears", :ruby_slippers => true)
# => prints "The options are {:ruby_slippers=>true}\nThe arguments are [\"dogs\", \"cats\", \"bears\"]"

Wraps the object in an Array, converting it using #to_ary if the object implements it. Does nothing on an existing Array.

Array(:chunky => :bacon)      # => [[:chunky, :bacon]]
Array.wrap(:chunky => :bacon) # => [{:chunky=>:bacon}]

Use this instead of Array() when you don’t want the implicit #to_a call on the object:

Array("lol\ncats")        # => ["lol\n", "cats"], in Ruby 1.8
Array.wrap("lol\ncats")   # => ["lol\ncats"]

Returns true or false depending on if a Range overlaps an other Range.

(1..5).overlaps?(4..6) # => true
(1..5).overlaps?(7..9) # => false

Same as Ruby’s own Range#step which iterates over the Range instance, passing each nth element to a passed block, but extended by Active Support to return an Array of values when invoked without a block:

(1..10).step(2) { |x| puts x } # => prints "1\n3\n5\n7\n9"

(1..10).step(2) # => [1, 3, 5, 7, 9]

Extended to return whether the enumeration of a Range includes a given element or other Range:

(1..5).include?(1..5)    # => true
(1..5).include?(2..3)    # => true
(1..5).include?(2..6)    # => false

("a".."f").include?("c") # => true
(5..9).include?(11)      # => false

Sums up a total from the enumerable object’s elements. Optionally takes a block to augment summation.

Usage without a block looks like what you would expect:

[5, 5, 5].sum # => 15

Calling sum with a block lets you specify the addition, much like an inject call:

products.sum { |p| p.price * tax }

You can also use a shortcut syntax to have the summation add up the results of a call on each element:

products.sum(&:price)  # Adds up all product prices
                                
# This is the same as writing:
#
#   products.inject(0) {|sum, p| sum + p.price }

You can also specify the value of an empty enumerable collection:

# By default, the sum of an empty list is 0
[].sum # => 0

# Specify the identity value by passing in a value for it:
[].sum("Nothing") # => "Nothing"

Converts an Enumerable to a Hash by iterating over the collection and building key/value pairs using what the block returns as the key, and the current element as the value:

["dogs", "cats", "turtles"].index_by {|e| e[0...1] }
# => {"c"=>"cats", "d"=>"dogs", "t"=>"turtles"}

Author.all.index_by(&:first_name)
# => {"Cody"=> <Author ... >, "Edward" => <Author ... >, 
#     "James" => <Author ... >, "John" => <Author ... >}

Returns true if the collection has more than 1 element:

["The Art of Conversation", "On Simplicity"].many? # => true

[1].many? # => false

{}.many? # => false

When provided an optional block, #many? passes iterates through the collection, passing each element to the block and counts how many times the block returns true. If it’s more than once, #many? returns true:

[2, 4, 6].many? {|n| n.even? } # => true

[2, 4, 6].many? {|n| n.odd? } # => false

The negative of Enumerable#include? – returns true if the collection does not include object

[2, 4, 6].exclude?(1) # => true

[2, 4, 6].exclude?(2) # => false

Iterates over a collection, passing the current element and memo object to the block. Handy for reducing a collection of objects down to a single one, like a numerical value. Also useful for transforming a collection into another, like from an Array to a Hash.

(1..10).each_with_object([1, 1]) do |i, memo|
  memo[0] = i + (memo[0] || 1)
  memo[1] = i * (memo[1] || 1)
end # => [56, 3628800]

["Some", "words"].each_with_object({}) do |word, word_counts|
  word_counts[word] = word.length
end # => {"Some"=>4, "words"=>5}

Curious about what the difference between this and Enumerable#inject is? With #each_with_object, you don’t need to worry about what the block returns. With #inject, the block must return the accumulated object, or memo. Here’s what the last example would look like using #inject:

["Some", "words"].inject({}) do |word_counts, word|
  word_counts[word] = word.length
  word_counts
end # => {"Some"=>4, "words"=>5}

By using #each_with_object you save a line of code as well as tend not to fall into head-scratching debugging situations where you see the following because you forgot to return the memo at the end of the block:

["Some", "words"].inject({}) do |word_counts, word|
  word_counts[word] = word.length
end

# ~> -:3: syntax error, unexpected kEND
# ~> ...mp_1277015147_730_23377 = (end);$stderr.puts("!XMP1277015147...
# ~>                               ^
# ~> -:3: syntax error, unexpected $end, expecting ')'

A final note: the memo must be mutable, so you can’t use immutable objects like numbers, true, or false. Your code will not raise any exceptions, but your results will be surprising:

(1..5).each_with_object(1) { |value, memo| memo *= value } # => 1

Enumerable#each_with_object is backported from Ruby 1.9.

Groups an enumerable into sets using the resulting value from the provided block. Useful for grouping records by date or another attribute. Here’s an example where we want to group a list of names by their first character:

people = ["Harry", "Tom", "Dick", "Darcy", "Dwemthy", "Harold", "Tim"]
                                
people.group_by {|name| name[0...1] }
# => #<OrderedHash {"D"=>["Dick", "Darcy", "Dwemthy"], "H"=>["Harry", "Harold"], "T"=>["Tom", "Tim"]}>

Generates a random hex String of length 2n:

SecureRandom.hex(10) # => "c0a0e3b1c8f70c9fb2e9"

If n is nil, 16 is assumed.

Raises NotImplementedError when a secure random number generator is not available.

Genrates a random base64 String of length ≈ 4/3n:

# Random 10-character base64 string 
SecureRandom.base64(10) # => "vA1N9RKHBD5n8Q=="

If n is nil, 16 is assumed.

Raises NotImplementedError when a secure random number generator is not available.

Generates a random integer between 0 (inclusive) and n when n > 0:

SecureRandom.random_number(20) # => 13

Generates a random float between 0.0 (inclusive) and 1.0 when n is 0 or nil:

SecureRandom.random_number # => 0.405922930890556

Generates a random binary String of length n:

SecureRandom.random_bytes(10) # => "\f\205\206M@\245\362\217\027\212"

Encodes a String data to its base-64 representation. Each 60 characters of output is separated by a newline (\n) character.

ActiveSupport::Base64.encode64("Original unencoded string")
# => "T3JpZ2luYWwgdW5lbmNvZGVkIHN0cmluZw==\n"

Decodes a base-64 encoded String data to its original representation.

ActiveSupport::Base64.decode64("T3JpZ2luYWwgdW5lbmNvZGVkIHN0cmluZw==")
# => "Original unencoded string"

Encodes the String data to its base-64 representation. Does not separate output with newlines. Useful for encoding URI parameters or memcache keys.

ActiveSupport::Base64.encode64s("Original unencoded string")
# => "T3JpZ2luYWwgdW5lbmNvZGVkIHN0cmluZw=="

Compresses a Gzip-ed String source.

ActiveSupport::Gzip.compress("Nutshell")
# => "\037\213\b\000\315\330\002L\000\003\363+-)\316H\315\311\001\000\r\372f\364\b\000\000\000"

Decompresses a Gzip-ed String source.

ActiveSupport::Gzip.decompress("\037\213\b\000\315\330\002L\000\003\363+-)\316H\315\311\001\000\r\372f\364\b\000\000\000")
# => "Nutshell"

Defines callback types. Example usage:

define_callbacks :ride, :terminator => "result == false"
define_callbacks :glide, :rescuable => false

The :terminator option specifies when a “before filter” should halt the callback chain. Here, we specify that if any ride callback returns false, halt the chain. By default, this is what it does.

The :rescuable option specifies whether or not “after filters” execute if the given block or a “before filter” raises an exception. By default, this is set to false.

Sets callbacks. See the previous example for usage, as well as the following on how to use the various filter list options:

set_callback :ride, :before, :check_the_weather
set_callback :ride, :after, :check_the_weather, :if => weather_is_a_big_deal?
set_callback :ride, :after, :check_the_weather, :unless => "weather == 'nice'"
set_callback :save, :around, lambda { |r| code_before; yield; code_after }

The conditions provided to the :if and :unless keys work the same way as they do for Active Record callback conditions: an Array of multiple conditions, the name of a method as a Symbol, a String which is eval-ed, a Proc to call with the object having its callback executed, or an Object that defines the after_ride method (for example).

Callbacks may be skipped in child classes by using this method. Example usage:

class Unicycle < Vehicle
  # [...]
  skip_callback :ride
  # [...]
end

Runs a given callback. See the Bicycle#ride method in the example at the start of this Callbacks section.

Expire just one memoized method’s cache:

thing = SomeOtherThing.new
                            
thing.some_long_running_computation  # Nothing cached; computation occurs
thing.some_long_running_computation  # Cache hit; computation skipped

thing.flush_cache(:some_long_running_computation)  # Flush just this method's cache

thing.some_long_running_computation  # Nothing cached; computation occurs

Expires the cache for all memoized methods in the instance:

class SomeOtherThing
  extend ActiveSupport::Memoizable

  def long_running_computation
    factorial(1000)
  end
  memoize :long_running_computation

  def other_long_running_computation
    sleep(42)
    factorial(100)
  end
  memoize :other_long_running_computation
end

thing = SomeOtherThing.new

thing.some_long_running_computation   # Nothing cached; computation occurs
thing.other_long_running_computation  # Nothing cached; computation occurs

thing.some_long_running_computation   # Cache hit; computation skipped
thing.other_long_running_computation  # Cache hit; computation skipped

thing.unmemoize_all  # Clear all memoized methods' cached results

thing.some_long_running_computation   # Nothing cached; computation occurs
thing.other_long_running_computation  # Nothing cached; computation occurs