Class

Object

Inheritance
Included Modules
Kernel, PP::ObjectMixin

Object is the parent class of all classes in Ruby. Its methods are therefore available to all objects unless explicitly overridden.

Object mixes in the Kernel module, making the built-in kernel functions globally accessible. Although the instance methods of Object are defined by the Kernel module, we have chosen to document them here for clarity.

In the descriptions of Object‘s methods, the parameter symbol refers to a symbol, which is either a quoted string or a Symbol (such as :name).

Constants

Name   Description
ARGF = argf
ARGV = rb_argv
DATA = f
ENV = envtbl
ENV = envtbl
FALSE = Qfalse
IPsocket = rb_cIPSocket
MatchingData = rb_cMatch
NIL = Qnil
PLATFORM = p
RELEASE_DATE = d
RUBY_COPYRIGHT = tmp
RUBY_DESCRIPTION = tmp
RUBY_PATCHLEVEL = INT2FIX(RUBY_PATCHLEVEL)
RUBY_PLATFORM = p
RUBY_RELEASE_DATE = d
RUBY_VERSION = v
SOCKSsocket = rb_cSOCKSSocket
STDERR = rb_stderr
STDIN = rb_stdin constants to hold original stdin/stdout/stderr
STDOUT = rb_stdout
TCPserver = rb_cTCPServer
TCPsocket = rb_cTCPSocket
TOPLEVEL_BINDING = rb_f_binding(ruby_top_self)
TRUE = Qtrue
UDPsocket = rb_cUDPSocket
UNIXserver = rb_cUNIXServer
UNIXsocket = rb_cUNIXSocket
VERSION = v obsolete constants

Aliases

Method Alias Description
load → __original__load__IRB_use_loader__
require → __original__require__IRB_use_loader__

Methods

Class

Visibility Signature
public new ()

Instance

Visibility Signature
public == (p1)
public === (p1)
public =~ (p1)
public __id__ ()
public __send__ (...)
public class ()
public clone ()
public dclone ()
public display (...)
public dup ()
public enum_for (...)
public eql? (p1)
public equal? (p1)
public extend (...)
public freeze ()
public frozen? ()
public hash ()
public id ()
public inspect ()
public instance_eval (...)
public instance_exec (...)
public instance_of? (p1)
public instance_variable_defined? (p1)
public instance_variable_get (ivarname)
public instance_variable_get (p1)
public instance_variable_set (ivarname, value)
public instance_variable_set (p1, p2)
public instance_variables ()
public is_a? (p1)
public kind_of? (p1)
public method (p1)
public methods (...)
public nil? ()
public object_id ()
public private_methods (...)
public protected_methods (...)
public public_methods (...)
public remove_instance_variable (p1)
public respond_to? (...)
public send (...)
public singleton_method_added (p1)
public singleton_method_removed (p1)
public singleton_method_undefined (p1)
public singleton_methods (...)
public taint ()
public tainted? ()
public tap ()
public to_a ()
public to_enum (...)
public to_s ()
public to_yaml ( opts = {} )
public to_yaml_properties ()
public to_yaml_style ()
public type ()
public untaint ()

Class Method Detail

new()

Not documented

Instance Method Detail

obj == other => true or false
obj.equal?(other) => true or false
obj.eql?(other) => true or false

Equality—At the Object level, == returns true only if obj and other are the same object. Typically, this method is overridden in descendent classes to provide class-specific meaning.

Unlike ==, the equal? method should never be overridden by subclasses: it is used to determine object identity (that is, a.equal?(b) iff a is the same object as b).

The eql? method returns true if obj and anObject have the same value. Used by Hash to test members for equality. For objects of class Object, eql? is synonymous with ==. Subclasses normally continue this tradition, but there are exceptions. Numeric types, for example, perform type conversion across ==, but not across eql?, so:

   1 == 1.0     #=> true
   1.eql? 1.0   #=> false

obj === other => true or false

Case Equality—For class Object, effectively the same as calling #==, but typically overridden by descendents to provide meaningful semantics in case statements.

obj =~ other => false

Pattern Match—Overridden by descendents (notably Regexp and String) to provide meaningful pattern-match semantics.

obj.__id__ => fixnum
obj.object_id => fixnum

Document-method: object_id

Returns an integer identifier for obj. The same number will be returned on all calls to id for a given object, and no two active objects will share an id. Object#object_id is a different concept from the :name notation, which returns the symbol id of name. Replaces the deprecated Object#id.

obj.send(symbol [, args...]) => obj
obj.__send__(symbol [, args...]) => obj

Invokes the method identified by symbol, passing it any arguments specified. You can use __send__ if the name send clashes with an existing method in obj.

   class Klass
     def hello(*args)
       "Hello " + args.join(' ')
     end
   end
   k = Klass.new
   k.send :hello, "gentle", "readers"   #=> "Hello gentle readers"

obj.class => class

Returns the class of obj, now preferred over Object#type, as an object‘s type in Ruby is only loosely tied to that object‘s class. This method must always be called with an explicit receiver, as class is also a reserved word in Ruby.

   1.class      #=> Fixnum
   self.class   #=> Object

obj.clone → an_object

Produces a shallow copy of obj—the instance variables of obj are copied, but not the objects they reference. Copies the frozen and tainted state of obj. See also the discussion under Object#dup.

   class Klass
      attr_accessor :str
   end
   s1 = Klass.new      #=> #<Klass:0x401b3a38>
   s1.str = "Hello"    #=> "Hello"
   s2 = s1.clone       #=> #<Klass:0x401b3998 @str="Hello">
   s2.str[1,4] = "i"   #=> "i"
   s1.inspect          #=> "#<Klass:0x401b3a38 @str=\"Hi\">"
   s2.inspect          #=> "#<Klass:0x401b3998 @str=\"Hi\">"

This method may have class-specific behavior. If so, that behavior will be documented under the #initialize_copy method of the class.

dclone()

obj.display(port=$>) => nil

Prints obj on the given port (default $>). Equivalent to:

   def display(port=$>)
     port.write self
   end

For example:

   1.display
   "cat".display
   [ 4, 5, 6 ].display
   puts

produces:

   1cat456

obj.dup → an_object

Produces a shallow copy of obj—the instance variables of obj are copied, but not the objects they reference. dup copies the tainted state of obj. See also the discussion under Object#clone. In general, clone and dup may have different semantics in descendent classes. While clone is used to duplicate an object, including its internal state, dup typically uses the class of the descendent object to create the new instance.

This method may have class-specific behavior. If so, that behavior will be documented under the #initialize_copy method of the class.

obj.to_enum(method = :each, *args)
obj.enum_for(method = :each, *args)

Returns Enumerable::Enumerator.new(self, method, *args).

e.g.:

   str = "xyz"

   enum = str.enum_for(:each_byte)
   a = enum.map {|b| '%02x' % b } #=> ["78", "79", "7a"]

   # protects an array from being modified
   a = [1, 2, 3]
   some_method(a.to_enum)

obj == other => true or false
obj.equal?(other) => true or false
obj.eql?(other) => true or false

Equality—At the Object level, == returns true only if obj and other are the same object. Typically, this method is overridden in descendent classes to provide class-specific meaning.

Unlike ==, the equal? method should never be overridden by subclasses: it is used to determine object identity (that is, a.equal?(b) iff a is the same object as b).

The eql? method returns true if obj and anObject have the same value. Used by Hash to test members for equality. For objects of class Object, eql? is synonymous with ==. Subclasses normally continue this tradition, but there are exceptions. Numeric types, for example, perform type conversion across ==, but not across eql?, so:

   1 == 1.0     #=> true
   1.eql? 1.0   #=> false

obj == other => true or false
obj.equal?(other) => true or false
obj.eql?(other) => true or false

Equality—At the Object level, == returns true only if obj and other are the same object. Typically, this method is overridden in descendent classes to provide class-specific meaning.

Unlike ==, the equal? method should never be overridden by subclasses: it is used to determine object identity (that is, a.equal?(b) iff a is the same object as b).

The eql? method returns true if obj and anObject have the same value. Used by Hash to test members for equality. For objects of class Object, eql? is synonymous with ==. Subclasses normally continue this tradition, but there are exceptions. Numeric types, for example, perform type conversion across ==, but not across eql?, so:

   1 == 1.0     #=> true
   1.eql? 1.0   #=> false

obj.extend(module, ...) => obj

Adds to obj the instance methods from each module given as a parameter.

   module Mod
     def hello
       "Hello from Mod.\n"
     end
   end

   class Klass
     def hello
       "Hello from Klass.\n"
     end
   end

   k = Klass.new
   k.hello         #=> "Hello from Klass.\n"
   k.extend(Mod)   #=> #<Klass:0x401b3bc8>
   k.hello         #=> "Hello from Mod.\n"

obj.freeze => obj

Prevents further modifications to obj. A TypeError will be raised if modification is attempted. There is no way to unfreeze a frozen object. See also Object#frozen?.

   a = [ "a", "b", "c" ]
   a.freeze
   a << "z"

produces:

   prog.rb:3:in `<<': can't modify frozen array (TypeError)
    from prog.rb:3

obj.frozen? => true or false

Returns the freeze status of obj.

   a = [ "a", "b", "c" ]
   a.freeze    #=> ["a", "b", "c"]
   a.frozen?   #=> true

obj.hash => fixnum

Generates a Fixnum hash value for this object. This function must have the property that a.eql?(b) implies a.hash == b.hash. The hash value is used by class Hash. Any hash value that exceeds the capacity of a Fixnum will be truncated before being used.

obj.id => fixnum

Soon-to-be deprecated version of Object#object_id.

obj.inspect => string

Returns a string containing a human-readable representation of obj. If not overridden, uses the to_s method to generate the string.

   [ 1, 2, 3..4, 'five' ].inspect   #=> "[1, 2, 3..4, \"five\"]"
   Time.new.inspect                 #=> "Wed Apr 09 08:54:39 CDT 2003"

obj.instance_eval(string [, filename [, lineno]] ) => obj
obj.instance_eval {| | block } => obj

Evaluates a string containing Ruby source code, or the given block, within the context of the receiver (obj). In order to set the context, the variable self is set to obj while the code is executing, giving the code access to obj‘s instance variables. In the version of instance_eval that takes a String, the optional second and third parameters supply a filename and starting line number that are used when reporting compilation errors.

   class Klass
     def initialize
       @secret = 99
     end
   end
   k = Klass.new
   k.instance_eval { @secret }   #=> 99

obj.instance_exec(arg...) {|var...| block } => obj

Executes the given block within the context of the receiver (obj). In order to set the context, the variable self is set to obj while the code is executing, giving the code access to obj‘s instance variables. Arguments are passed as block parameters.

   class KlassWithSecret
     def initialize
       @secret = 99
     end
   end
   k = KlassWithSecret.new
   k.instance_exec(5) {|x| @secret+x }   #=> 104

obj.instance_of?(class) => true or false

Returns true if obj is an instance of the given class. See also Object#kind_of?.

obj.instance_variable_defined?(symbol) => true or false

Returns true if the given instance variable is defined in obj.

   class Fred
     def initialize(p1, p2)
       @a, @b = p1, p2
     end
   end
   fred = Fred.new('cat', 99)
   fred.instance_variable_defined?(:@a)    #=> true
   fred.instance_variable_defined?("@b")   #=> true
   fred.instance_variable_defined?("@c")   #=> false

instance_variable_get(ivarname)

obj.instance_variable_get(symbol) => obj

Returns the value of the given instance variable, or nil if the instance variable is not set. The @ part of the variable name should be included for regular instance variables. Throws a NameError exception if the supplied symbol is not valid as an instance variable name.

   class Fred
     def initialize(p1, p2)
       @a, @b = p1, p2
     end
   end
   fred = Fred.new('cat', 99)
   fred.instance_variable_get(:@a)    #=> "cat"
   fred.instance_variable_get("@b")   #=> 99

instance_variable_set(ivarname, value)

obj.instance_variable_set(symbol, obj) => obj

Sets the instance variable names by symbol to object, thereby frustrating the efforts of the class‘s author to attempt to provide proper encapsulation. The variable did not have to exist prior to this call.

   class Fred
     def initialize(p1, p2)
       @a, @b = p1, p2
     end
   end
   fred = Fred.new('cat', 99)
   fred.instance_variable_set(:@a, 'dog')   #=> "dog"
   fred.instance_variable_set(:@c, 'cat')   #=> "cat"
   fred.inspect                             #=> "#<Fred:0x401b3da8 @a=\"dog\", @b=99, @c=\"cat\">"

obj.instance_variables => array

Returns an array of instance variable names for the receiver. Note that simply defining an accessor does not create the corresponding instance variable.

   class Fred
     attr_accessor :a1
     def initialize
       @iv = 3
     end
   end
   Fred.new.instance_variables   #=> ["@iv"]

obj.is_a?(class) => true or false
obj.kind_of?(class) => true or false

Returns true if class is the class of obj, or if class is one of the superclasses of obj or modules included in obj.

   module M;    end
   class A
     include M
   end
   class B < A; end
   class C < B; end
   b = B.new
   b.instance_of? A   #=> false
   b.instance_of? B   #=> true
   b.instance_of? C   #=> false
   b.instance_of? M   #=> false
   b.kind_of? A       #=> true
   b.kind_of? B       #=> true
   b.kind_of? C       #=> false
   b.kind_of? M       #=> true

obj.is_a?(class) => true or false
obj.kind_of?(class) => true or false

Returns true if class is the class of obj, or if class is one of the superclasses of obj or modules included in obj.

   module M;    end
   class A
     include M
   end
   class B < A; end
   class C < B; end
   b = B.new
   b.instance_of? A   #=> false
   b.instance_of? B   #=> true
   b.instance_of? C   #=> false
   b.instance_of? M   #=> false
   b.kind_of? A       #=> true
   b.kind_of? B       #=> true
   b.kind_of? C       #=> false
   b.kind_of? M       #=> true

obj.method(sym) => method

Looks up the named method as a receiver in obj, returning a Method object (or raising NameError). The Method object acts as a closure in obj‘s object instance, so instance variables and the value of self remain available.

   class Demo
     def initialize(n)
       @iv = n
     end
     def hello()
       "Hello, @iv = #{@iv}"
     end
   end

   k = Demo.new(99)
   m = k.method(:hello)
   m.call   #=> "Hello, @iv = 99"

   l = Demo.new('Fred')
   m = l.method("hello")
   m.call   #=> "Hello, @iv = Fred"

obj.methods => array

Returns a list of the names of methods publicly accessible in obj. This will include all the methods accessible in obj‘s ancestors.

   class Klass
     def kMethod()
     end
   end
   k = Klass.new
   k.methods[0..9]    #=> ["kMethod", "freeze", "nil?", "is_a?",
                           "class", "instance_variable_set",
                            "methods", "extend", "__send__", "instance_eval"]
   k.methods.length   #=> 42

nil?()

call_seq:

  nil.nil?               => true
  <anything_else>.nil?   => false

Only the object nil responds true to nil?.

obj.__id__ => fixnum
obj.object_id => fixnum

Returns an integer identifier for obj. The same number will be returned on all calls to id for a given object, and no two active objects will share an id. Object#object_id is a different concept from the :name notation, which returns the symbol id of name. Replaces the deprecated Object#id.

obj.private_methods(all=true) => array

Returns the list of private methods accessible to obj. If the all parameter is set to false, only those methods in the receiver will be listed.

obj.protected_methods(all=true) => array

Returns the list of protected methods accessible to obj. If the all parameter is set to false, only those methods in the receiver will be listed.

obj.public_methods(all=true) => array

Returns the list of public methods accessible to obj. If the all parameter is set to false, only those methods in the receiver will be listed.

obj.remove_instance_variable(symbol) => obj

Removes the named instance variable from obj, returning that variable‘s value.

   class Dummy
     attr_reader :var
     def initialize
       @var = 99
     end
     def remove
       remove_instance_variable(:@var)
     end
   end
   d = Dummy.new
   d.var      #=> 99
   d.remove   #=> 99
   d.var      #=> nil

obj.respond_to?(symbol, include_private=false) => true or false

Returns true> if obj responds to the given method. Private methods are included in the search only if the optional second parameter evaluates to true.

obj.send(symbol [, args...]) => obj
obj.__send__(symbol [, args...]) => obj

Invokes the method identified by symbol, passing it any arguments specified. You can use __send__ if the name send clashes with an existing method in obj.

   class Klass
     def hello(*args)
       "Hello " + args.join(' ')
     end
   end
   k = Klass.new
   k.send :hello, "gentle", "readers"   #=> "Hello gentle readers"

singleton_method_added(symbol)

Invoked as a callback whenever a singleton method is added to the receiver.

   module Chatty
     def Chatty.singleton_method_added(id)
       puts "Adding #{id.id2name}"
     end
     def self.one()     end
     def two()          end
     def Chatty.three() end
   end

produces:

   Adding singleton_method_added
   Adding one
   Adding three

singleton_method_removed(symbol)

Invoked as a callback whenever a singleton method is removed from the receiver.

   module Chatty
     def Chatty.singleton_method_removed(id)
       puts "Removing #{id.id2name}"
     end
     def self.one()     end
     def two()          end
     def Chatty.three() end
     class <<self
       remove_method :three
       remove_method :one
     end
   end

produces:

   Removing three
   Removing one

singleton_method_undefined(symbol)

Invoked as a callback whenever a singleton method is undefined in the receiver.

   module Chatty
     def Chatty.singleton_method_undefined(id)
       puts "Undefining #{id.id2name}"
     end
     def Chatty.one()   end
     class << self
        undef_method(:one)
     end
   end

produces:

   Undefining one

obj.singleton_methods(all=true) => array

Returns an array of the names of singleton methods for obj. If the optional all parameter is true, the list will include methods in modules included in obj.

   module Other
     def three() end
   end

   class Single
     def Single.four() end
   end

   a = Single.new

   def a.one()
   end

   class << a
     include Other
     def two()
     end
   end

   Single.singleton_methods    #=> ["four"]
   a.singleton_methods(false)  #=> ["two", "one"]
   a.singleton_methods         #=> ["two", "one", "three"]

obj.taint → obj

Marks obj as tainted—if the $SAFE level is set appropriately, many method calls which might alter the running programs environment will refuse to accept tainted strings.

obj.tainted? => true or false

Returns true if the object is tainted.

obj.tap{|x|...} => obj

Yields x to the block, and then returns x. The primary purpose of this method is to "tap into" a method chain, in order to perform operations on intermediate results within the chain.

    (1..10).tap {
      |x| puts "original: #{x.inspect}"
    }.to_a.tap {
      |x| puts "array: #{x.inspect}"
    }.select {|x| x%2==0}.tap {
      |x| puts "evens: #{x.inspect}"
    }.map {|x| x*x}.tap {
      |x| puts "squares: #{x.inspect}"
    }

obj.to_a → anArray

Returns an array representation of obj. For objects of class Object and others that don‘t explicitly override the method, the return value is an array containing self. However, this latter behavior will soon be obsolete.

   self.to_a       #=> -:1: warning: default `to_a' will be obsolete
   "hello".to_a    #=> ["hello"]
   Time.new.to_a   #=> [39, 54, 8, 9, 4, 2003, 3, 99, true, "CDT"]

obj.to_enum(method = :each, *args)
obj.enum_for(method = :each, *args)

Returns Enumerable::Enumerator.new(self, method, *args).

e.g.:

   str = "xyz"

   enum = str.enum_for(:each_byte)
   a = enum.map {|b| '%02x' % b } #=> ["78", "79", "7a"]

   # protects an array from being modified
   a = [1, 2, 3]
   some_method(a.to_enum)

obj.to_s => string

Returns a string representing obj. The default to_s prints the object‘s class and an encoding of the object id. As a special case, the top-level object that is the initial execution context of Ruby programs returns ``main.’‘

to_yaml( opts = {} )

to_yaml_properties()

to_yaml_style()

obj.type => class

Deprecated synonym for Object#class.

obj.untaint => obj

Removes the taint from obj.