class Object - activesupport-4.2.4 Documentation

# class Object

### Constants

HashWithIndifferentAccess

  Implements a hash where keys `:foo` and `"foo"` are considered to be the same.

      rgb = ActiveSupport::HashWithIndifferentAccess.new

      rgb[:black] = '#000000'
      rgb[:black]  # => '#000000'
      rgb['black'] # => '#000000'

      rgb['white'] = '#FFFFFF'
      rgb[:white]  # => '#FFFFFF'
      rgb['white'] # => '#FFFFFF'

  Internally symbols are mapped to strings when used as keys in the entire writing interface (calling `[]=`, `merge`, etc). This mapping belongs to the public interface. For example, given:

      hash = ActiveSupport::HashWithIndifferentAccess.new(a: 1)

  You are guaranteed that the key is returned as a string:

      hash.keys # => ["a"]

  Technically other types of keys are accepted:

      hash = ActiveSupport::HashWithIndifferentAccess.new(a: 1)
      hash[0] = 0
      hash # => {"a"=>1, 0=>0}

  but this class is intended for use cases where strings or symbols are the expected keys and it is convenient to understand both as the same. For example the `params` hash in Ruby on Rails.

  Note that core extensions define `Hash#with_indifferent_access`:

      rgb = { black: '#000000', white: '#FFFFFF' }.with_indifferent_access

  which may be handy.

MissingSourceFile

### Public Instance Methods

acts_like?(duck) click to toggle source

A duck-type assistant method. For example, Active Support extends Date to define an `acts_like_date?` method, and extends Time to define `acts_like_time?`. As a result, we can do `x.acts_like?(:time)` and `x.acts_like?(:date)` to do duck-type-safe comparisons, since classes that we want to act like Time simply need to define an `acts_like_time?` method.

    # File lib/active_support/core_ext/object/acts_like.rb, line 7
    def acts_like?(duck)
      respond_to? :"acts_like_#{duck}?"
    end

blank?() click to toggle source

An object is blank if it's false, empty, or a whitespace string. For example, '', ' ', `nil`, [], and {} are all blank.

This simplifies

    address.nil? || address.empty?

to

    address.blank?

@return [true, false]

    # File lib/active_support/core_ext/object/blank.rb, line 15
    def blank?
      respond_to?(:empty?) ? !!empty? : !self
    end

deep_dup() click to toggle source

Returns a deep copy of object if it's duplicable. If it's not duplicable, returns `self`.

    object = Object.new
    dup    = object.deep_dup
    dup.instance_variable_set(:@a, 1)

    object.instance_variable_defined?(:@a) # => false
    dup.instance_variable_defined?(:@a)    # => true

    # File lib/active_support/core_ext/object/deep_dup.rb, line 13
    def deep_dup
      duplicable? ? dup : self
    end

duplicable?() click to toggle source

Can you safely dup this object?

False for `nil`, `false`, `true`, symbol, number and BigDecimal(in 1.9.x) objects; true otherwise.

    # File lib/active_support/core_ext/object/duplicable.rb, line 24
    def duplicable?
      true
    end

html_safe?() click to toggle source

    # File lib/active_support/core_ext/string/output_safety.rb, line 120
    def html_safe?
      false
    end

in?(another_object) click to toggle source

Returns true if this object is included in the argument. Argument must be any object which responds to `#include?`. Usage:

    characters = ["Konata", "Kagami", "Tsukasa"]
    "Konata".in?(characters) # => true

This will throw an ArgumentError if the argument doesn't respond to `#include?`.

    # File lib/active_support/core_ext/object/inclusion.rb, line 10
    def in?(another_object)
      another_object.include?(self)
    rescue NoMethodError
      raise ArgumentError.new("The parameter passed to #in? must respond to #include?")
    end

instance_values() click to toggle source

Returns a hash with string keys that maps instance variable names without “@” to their corresponding values.

    class C
      def initialize(x, y)
        @x, @y = x, y
      end
    end

    C.new(0, 1).instance_values # => {"x" => 0, "y" => 1}

    # File lib/active_support/core_ext/object/instance_variables.rb, line 12
    def instance_values
      Hash[instance_variables.map { |name| [name[1..-1], instance_variable_get(name)] }]
    end

instance_variable_names() click to toggle source

Returns an array of instance variable names as strings including “@”.

    class C
      def initialize(x, y)
        @x, @y = x, y
      end
    end

    C.new(0, 1).instance_variable_names # => ["@y", "@x"]

    # File lib/active_support/core_ext/object/instance_variables.rb, line 25
    def instance_variable_names
      instance_variables.map { |var| var.to_s }
    end

itself() click to toggle source

Returns the object itself.

Useful for chaining methods, such as Active Record scopes:

    Event.public_send(state.presence_in([ :trashed, :drafted ]) || :itself).order(:created_at)

@return Object

    # File lib/active_support/core_ext/object/itself.rb, line 11
    def itself
      self
    end

presence() click to toggle source

Returns the receiver if it's present otherwise returns `nil`. `object.presence` is equivalent to

    object.present? ? object : nil

For example, something like

    state   = params[:state]   if params[:state].present?
    country = params[:country] if params[:country].present?
    region  = state || country || 'US'

becomes

    region = params[:state].presence || params[:country].presence || 'US'

@return [Object]

    # File lib/active_support/core_ext/object/blank.rb, line 42
    def presence
      self if present?
    end

presence_in(another_object) click to toggle source

Returns the receiver if it's included in the argument otherwise returns `nil`. Argument must be any object which responds to `#include?`. Usage:

    params[:bucket_type].presence_in %w( project calendar )

This will throw an ArgumentError if the argument doesn't respond to `#include?`.

@return [Object]

    # File lib/active_support/core_ext/object/inclusion.rb, line 24
    def presence_in(another_object)
      self.in?(another_object) ? self : nil
    end

present?() click to toggle source

An object is present if it's not blank.

@return [true, false]

    # File lib/active_support/core_ext/object/blank.rb, line 22
    def present?
      !blank?
    end

to_param() click to toggle source

Alias of `to_s`.

    # File lib/active_support/core_ext/object/to_query.rb, line 5
    def to_param
      to_s
    end

to_query(key) click to toggle source

Converts an object into a string suitable for use as a URL query string, using the given `key` as the param name.

    # File lib/active_support/core_ext/object/to_query.rb, line 11
    def to_query(key)
      "#{CGI.escape(key.to_param)}=#{CGI.escape(to_param.to_s)}"
    end

try(*a, &b) click to toggle source

Invokes the public method whose name goes as first argument just like `public_send` does, except that if the receiver does not respond to it the call returns `nil` rather than raising an exception.

This method is defined to be able to write

    @person.try(:name)

instead of

    @person.name if @person

`try` calls can be chained:

    @person.try(:spouse).try(:name)

instead of

    @person.spouse.name if @person && @person.spouse

`try` will also return `nil` if the receiver does not respond to the method:

    @person.try(:non_existing_method) #=> nil

instead of

    @person.non_existing_method if @person.respond_to?(:non_existing_method) #=> nil

`try` returns `nil` when called on `nil` regardless of whether it responds to the method:

    nil.try(:to_i) # => nil, rather than 0

Arguments and blocks are forwarded to the method if invoked:

    @posts.try(:each_slice, 2) do |a, b|
      ...
    end

The number of arguments in the signature must match. If the object responds to the method the call is attempted and `ArgumentError` is still raised in case of argument mismatch.

If `try` is called without arguments it yields the receiver to a given block unless it is `nil`:

    @person.try do |p|
      ...
    end

You can also call try with a block without accepting an argument, and the block will be instance_eval'ed instead:

    @person.try { upcase.truncate(50) }

Please also note that `try` is defined on `Object`. Therefore, it won't work with instances of classes that do not have `Object` among their ancestors, like direct subclasses of `BasicObject`. For example, using `try` with `SimpleDelegator` will delegate `try` to the target instead of calling it on the delegator itself.

    # File lib/active_support/core_ext/object/try.rb, line 62
    def try(*a, &b)
      try!(*a, &b) if a.empty? || respond_to?(a.first)
    end

try!(*a) { |self| ... } click to toggle source

Same as try, but will raise a NoMethodError exception if the receiver is not `nil` and does not implement the tried method.

    # File lib/active_support/core_ext/object/try.rb, line 69
    def try!(*a, &b)
      if a.empty? && block_given?
        if b.arity.zero?
          instance_eval(&b)
        else
          yield self
        end
      else
        public_send(*a, &b)
      end
    end

unescape(str, escaped = /%[a-fA-F\d]{2}/) click to toggle source

    # File lib/active_support/core_ext/uri.rb, line 9
    def unescape(str, escaped = /%[a-fA-F\d]{2}/)
      # TODO: Are we actually sure that ASCII == UTF-8?
      # YK: My initial experiments say yes, but let's be sure please
      enc = str.encoding
      enc = Encoding::UTF_8 if enc == Encoding::US_ASCII
      str.gsub(escaped) { [$&[1, 2].hex].pack('C') }.force_encoding(enc)
    end

with_options(options, &block) click to toggle source

An elegant way to factor duplication out of options passed to a series of method calls. Each method called in the block, with the block variable as the receiver, will have its options merged with the default `options` hash provided. Each method called on the block variable must take an options hash as its final argument.

Without `with_options>`, this code contains duplication:

    class Account < ActiveRecord::Base
      has_many :customers, dependent: :destroy
      has_many :products,  dependent: :destroy
      has_many :invoices,  dependent: :destroy
      has_many :expenses,  dependent: :destroy
    end

Using `with_options`, we can remove the duplication:

    class Account < ActiveRecord::Base
      with_options dependent: :destroy do |assoc|
        assoc.has_many :customers
        assoc.has_many :products
        assoc.has_many :invoices
        assoc.has_many :expenses
      end
    end

It can also be used with an explicit receiver:

    I18n.with_options locale: user.locale, scope: 'newsletter' do |i18n|
      subject i18n.t :subject
      body    i18n.t :body, user_name: user.name
    end

When you don't pass an explicit receiver, it executes the whole block in merging options context:

    class Account < ActiveRecord::Base
      with_options dependent: :destroy do
        has_many :customers
        has_many :products
        has_many :invoices
        has_many :expenses
      end
    end

`with_options` can also be nested since the call is forwarded to its receiver.

NOTE: Each nesting level will merge inherited defaults in addition to their own.

    class Post < ActiveRecord::Base
      with_options if: :persisted?, length: { minimum: 50 } do
        validates :content, if: -> { content.present? }
      end
    end

The code is equivalent to:

    validates :content, length: { minimum: 50 }, if: -> { content.present? }

Hence the inherited default for `if` key is ignored.

    # File lib/active_support/core_ext/object/with_options.rb, line 65
    def with_options(options, &block)
      option_merger = ActiveSupport::OptionMerger.new(self, options)
      block.arity.zero? ? option_merger.instance_eval(&block) : block.call(option_merger)
    end