Class: Object

Inherits:
BasicObject
Includes:
Kernel
Defined in:
object.c,
class.c,
object.c

Overview

Object is the default root of all Ruby objects. Object inherits from BasicObject which allows creating alternate object hierarchies. Methods on Object are available to all classes 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.

When referencing constants in classes inheriting from Object you do not need to use the full namespace. For example, referencing File inside YourClass will find the top-level File class.

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

What’s Here

First, what’s elsewhere. Class Object:

Here, class Object provides methods for:

Querying

  • #!~: Returns true if self does not match the given object, otherwise false.

  • #<=>: Returns 0 if self and the given object object are the same object, or if self == object; otherwise returns nil.

  • #===: Implements case equality, effectively the same as calling #==.

  • #eql?: Implements hash equality, effectively the same as calling #==.

  • #kind_of? (aliased as #is_a?): Returns whether given argument is an ancestor of the singleton class of self.

  • #instance_of?: Returns whether self is an instance of the given class.

  • #instance_variable_defined?: Returns whether the given instance variable is defined in self.

  • #method: Returns the Method object for the given method in self.

  • #methods: Returns an array of symbol names of public and protected methods in self.

  • #nil?: Returns false. (Only nil responds true to method nil?.)

  • #object_id: Returns an integer corresponding to self that is unique for the current process

  • #private_methods: Returns an array of the symbol names of the private methods in self.

  • #protected_methods: Returns an array of the symbol names of the protected methods in self.

  • #public_method: Returns the Method object for the given public method in self.

  • #public_methods: Returns an array of the symbol names of the public methods in self.

  • #respond_to?: Returns whether self responds to the given method.

  • #singleton_class: Returns the singleton class of self.

  • #singleton_method: Returns the Method object for the given singleton method in self.

  • #singleton_methods: Returns an array of the symbol names of the singleton methods in self.

  • #define_singleton_method: Defines a singleton method in self for the given symbol method-name and block or proc.

  • #extend: Includes the given modules in the singleton class of self.

  • #public_send: Calls the given public method in self with the given argument.

  • #send: Calls the given method in self with the given argument.

Instance Variables

  • #instance_variable_get: Returns the value of the given instance variable in self, or nil if the instance variable is not set.

  • #instance_variable_set: Sets the value of the given instance variable in self to the given object.

  • #instance_variables: Returns an array of the symbol names of the instance variables in self.

  • #remove_instance_variable: Removes the named instance variable from self.

Other

  • #clone: Returns a shallow copy of self, including singleton class and frozen state.

  • #define_singleton_method: Defines a singleton method in self for the given symbol method-name and block or proc.

  • #display: Prints self to the given IO stream or $stdout.

  • #dup: Returns a shallow unfrozen copy of self.

  • #enum_for (aliased as #to_enum): Returns an Enumerator for self using the using the given method, arguments, and block.

  • #extend: Includes the given modules in the singleton class of self.

  • #freeze: Prevents further modifications to self.

  • #hash: Returns the integer hash value for self.

  • #inspect: Returns a human-readable string representation of self.

  • #itself: Returns self.

  • #method_missing: Method called when an undefined method is called on self.

  • #public_send: Calls the given public method in self with the given argument.

  • #send: Calls the given method in self with the given argument.

  • #to_s: Returns a string representation of self.

Instance Method Summary collapse

Methods included from Kernel

#Array, #Complex, #Hash, #Rational, #String, #__callee__, #__dir__, #__method__, #`, #abort, #at_exit, #autoload, #autoload?, #binding, #block_given?, #callcc, #caller, #caller_locations, #catch, #chomp, #chop, #eval, #exec, #exit, #exit!, #fail, #fork, #format, #gets, #global_variables, #gsub, #iterator?, #lambda, #load, #local_variables, #open, #p, #print, #printf, #proc, #putc, #puts, #raise, #rand, #readline, #readlines, #require, #require_relative, #select, #set_trace_func, #sleep, #spawn, #sprintf, #srand, #sub, #syscall, #system, #test, #throw, #trace_var, #trap, #untrace_var

Instance Method Details

#!~(other) ⇒ Boolean

Returns true if two objects do not match (using the =~ method), otherwise false.

Returns:

  • (Boolean) 


1677
1678
1679
1680
1681
1682
 
# File 'object.c', line 1677

static VALUE
rb_obj_not_match(VALUE obj1, VALUE obj2)
{
    VALUE result = rb_funcall(obj1, id_match, 1, obj2);
    return rb_obj_not(result);
}

#<=>(other) ⇒ 0?

Returns 0 if obj and other are the same object or obj == other, otherwise nil.

The #<=> is used by various methods to compare objects, for example Enumerable#sort, Enumerable#max etc.

Your implementation of #<=> should return one of the following values: -1, 0, 1 or nil. -1 means self is smaller than other. 0 means self is equal to other. 1 means self is bigger than other. Nil means the two values could not be compared.

When you define #<=>, you can include Comparable to gain the methods #<=, #<, #==, #>=, #> and #between?.

Returns:

  • (0, nil) 


1703
1704
1705
1706
1707
1708
1709
 
# File 'object.c', line 1703

static VALUE
rb_obj_cmp(VALUE obj1, VALUE obj2)
{
    if (rb_equal(obj1, obj2))
        return INT2FIX(0);
    return Qnil;
}

#=== ⇒ Object

#define_singleton_method(symbol, method) ⇒ Object #define_singleton_method(symbol) { ... } ⇒ Object

Defines a public singleton method in the receiver. The method parameter can be a Proc, a Method or an UnboundMethod object. If a block is specified, it is used as the method body. If a block or a method has parameters, they’re used as method parameters.

class A
  class << self
    def class_name
      to_s
    end
  end
end
A.define_singleton_method(:who_am_i) do
  "I am: #{class_name}"
end
A.who_am_i   # ==> "I am: A"

guy = "Bob"
guy.define_singleton_method(:hello) { "#{self}: Hello there!" }
guy.hello    #=>  "Bob: Hello there!"

chris = "Chris"
chris.define_singleton_method(:greet) {|greeting| "#{greeting}, I'm Chris!" }
chris.greet("Hi") #=> "Hi, I'm Chris!"

Overloads:

  • #define_singleton_method(symbol) { ... } ⇒ Object

    Yields:



2395
2396
2397
2398
2399
2400
2401
2402
 
# File 'proc.c', line 2395

static VALUE
rb_obj_define_method(int argc, VALUE *argv, VALUE obj)
{
    VALUE klass = rb_singleton_class(obj);
    const rb_scope_visibility_t scope_visi = {METHOD_VISI_PUBLIC, FALSE};

    return rb_mod_define_method_with_visibility(argc, argv, klass, &scope_visi);
}

#display(port = $>) ⇒ nil

Writes self on the given port:

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

Output:

1cat[4, 5, 6]

Returns:

  • (nil) 


9124
9125
9126
9127
9128
9129
9130
9131
9132
9133
 
# File 'io.c', line 9124

static VALUE
rb_obj_display(int argc, VALUE *argv, VALUE self)
{
    VALUE out;

    out = (!rb_check_arity(argc, 0, 1) ? rb_ractor_stdout() : argv[0]);
    rb_io_write(out, self);

    return Qnil;
}

#dup ⇒ Object

Produces a shallow copy of obj—the instance variables of obj are copied, but not the objects they reference.

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

on dup vs clone

In general, #clone and #dup may have different semantics in descendant classes. While #clone is used to duplicate an object, including its internal state, #dup typically uses the class of the descendant object to create the new instance.

When using #dup, any modules that the object has been extended with will not be copied.

class Klass

attr_accessor :str

end

module Foo

def foo; 'foo'; end

end

s1 = Klass.new #=> #<Klass:0x401b3a38> s1.extend(Foo) #=> #<Klass:0x401b3a38> s1.foo #=> “foo”

s2 = s1.clone #=> #<Klass:0x401be280> s2.foo #=> “foo”

s3 = s1.dup #=> #<Klass:0x401c1084> s3.foo #=> NoMethodError: undefined method ‘foo’ for #<Klass:0x401c1084>

Returns:



625
626
627
628
629
630
631
632
633
634
635
 
# File 'object.c', line 625

VALUE
rb_obj_dup(VALUE obj)
{
    VALUE dup;

    if (special_object_p(obj)) {
        return obj;
    }
    dup = rb_obj_alloc(rb_obj_class(obj));
    return rb_obj_dup_setup(obj, dup);
}

#to_enum(method = :each, *args) ⇒ Enumerator #enum_for(method = :each, *args) ⇒ Enumerator #to_enum(method = :each, *args) {|*args| ... } ⇒ Enumerator #enum_for(method = :each, *args) {|*args| ... } ⇒ Enumerator

Creates a new Enumerator which will enumerate by calling method on obj, passing args if any. What was yielded by method becomes values of enumerator.

If a block is given, it will be used to calculate the size of the enumerator without the need to iterate it (see Enumerator#size).

Examples

str = "xyz"

enum = str.enum_for(:each_byte)
enum.each { |b| puts b }
# => 120
# => 121
# => 122

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

# String#split in block form is more memory-effective:
very_large_string.split("|") { |chunk| return chunk if chunk.include?('DATE') }
# This could be rewritten more idiomatically with to_enum:
very_large_string.to_enum(:split, "|").lazy.grep(/DATE/).first

It is typical to call to_enum when defining methods for a generic Enumerable, in case no block is passed.

Here is such an example, with parameter passing and a sizing block:

module Enumerable
  # a generic method to repeat the values of any enumerable
  def repeat(n)
    raise ArgumentError, "#{n} is negative!" if n < 0
    unless block_given?
      return to_enum(__method__, n) do # __method__ is :repeat here
        sz = size     # Call size and multiply by n...
        sz * n if sz  # but return nil if size itself is nil
      end
    end
    each do |*val|
      n.times { yield *val }
    end
  end
end

%i[hello world].repeat(2) { |w| puts w }
  # => Prints 'hello', 'hello', 'world', 'world'
enum = (1..14).repeat(3)
  # => returns an Enumerator when called without a block
enum.first(4) # => [1, 1, 1, 2]
enum.size # => 42

Overloads:



381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
 
# File 'enumerator.c', line 381

static VALUE
obj_to_enum(int argc, VALUE *argv, VALUE obj)
{
    VALUE enumerator, meth = sym_each;

    if (argc > 0) {
        --argc;
        meth = *argv++;
    }
    enumerator = rb_enumeratorize_with_size(obj, meth, argc, argv, 0);
    if (rb_block_given_p()) {
        RB_OBJ_WRITE(enumerator, &enumerator_ptr(enumerator)->size, rb_block_proc());
    }
    return enumerator;
}

#==(other) ⇒ Boolean #equal?(other) ⇒ Boolean #eql?(other) ⇒ Boolean

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

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

obj = "a"
other = obj.dup

obj == other      #=> true
obj.equal? other  #=> false
obj.equal? obj    #=> true

The #eql? method returns true if obj and other refer to the same hash key. This is used by Hash to test members for equality. For any pair of objects where #eql? returns true, the #hash value of both objects must be equal. So any subclass that overrides #eql? should also override #hash appropriately.

For objects of class Object, #eql? is synonymous with #==. Subclasses normally continue this tradition by aliasing #eql? to their overridden #== method, 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

Overloads:

  • #==(other) ⇒ Boolean

    Returns:

    • (Boolean)
  • #equal?(other) ⇒ Boolean

    Returns:

    • (Boolean)
  • #eql?(other) ⇒ Boolean

    Returns:

    • (Boolean) 


245
246
247
248
249
 
# File 'object.c', line 245

VALUE
rb_obj_equal(VALUE obj1, VALUE obj2)
{
    return RBOOL(obj1 == obj2);
}

#extend ⇒ Object

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"

Returns:



1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
 
# File 'eval.c', line 1820

static VALUE
rb_obj_extend(int argc, VALUE *argv, VALUE obj)
{
    int i;
    ID id_extend_object, id_extended;

    CONST_ID(id_extend_object, "extend_object");
    CONST_ID(id_extended, "extended");

    rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);
    for (i = 0; i < argc; i++) {
        Check_Type(argv[i], T_MODULE);
        if (FL_TEST(argv[i], RMODULE_IS_REFINEMENT)) {
            rb_raise(rb_eTypeError, "Cannot extend object with refinement");
        }
    }
    while (argc--) {
        rb_funcall(argv[argc], id_extend_object, 1, obj);
        rb_funcall(argv[argc], id_extended, 1, obj);
    }
    return obj;
}

#freeze ⇒ Object

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

This method returns self.

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

produces:

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

Objects of the following classes are always frozen: Integer, Float, Symbol.

Returns:



1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
 
# File 'object.c', line 1318

VALUE
rb_obj_freeze(VALUE obj)
{
    if (!OBJ_FROZEN(obj)) {
        OBJ_FREEZE(obj);
        if (SPECIAL_CONST_P(obj)) {
            rb_bug("special consts should be frozen.");
        }
    }
    return obj;
}

#hash ⇒ Object 



251
 
# File 'object.c', line 251

VALUE rb_obj_hash(VALUE obj);

#initialize_clone(*args) ⇒ Object

:nodoc:



705
706
707
708
709
710
711
712
713
714
715
 
# File 'object.c', line 705

static VALUE
rb_obj_init_clone(int argc, VALUE *argv, VALUE obj)
{
    VALUE orig, opts;
    if (rb_scan_args(argc, argv, "1:", &orig, &opts) < argc) {
        /* Ignore a freeze keyword */
        rb_get_freeze_opt(1, &opts);
    }
    rb_funcall(obj, id_init_copy, 1, orig);
    return obj;
}

#initialize_copy(orig) ⇒ Object

:nodoc:



668
669
670
671
672
673
674
675
676
677
 
# File 'object.c', line 668

VALUE
rb_obj_init_copy(VALUE obj, VALUE orig)
{
    if (obj == orig) return obj;
    rb_check_frozen(obj);
    if (TYPE(obj) != TYPE(orig) || rb_obj_class(obj) != rb_obj_class(orig)) {
        rb_raise(rb_eTypeError, "initialize_copy should take same class object");
    }
    return obj;
}

#initialize_dup(orig) ⇒ Object

:nodoc:



688
689
690
691
692
693
 
# File 'object.c', line 688

VALUE
rb_obj_init_dup_clone(VALUE obj, VALUE orig)
{
    rb_funcall(obj, id_init_copy, 1, orig);
    return obj;
}

#inspect ⇒ String

Returns a string containing a human-readable representation of obj. The default #inspect shows the object’s class name, an encoding of its memory address, and a list of the instance variables and their values (by calling #inspect on each of them). User defined classes should override this method to provide a better representation of obj. When overriding this method, it should return a string whose encoding is compatible with the default external encoding.

[ 1, 2, 3..4, 'five' ].inspect   #=> "[1, 2, 3..4, \"five\"]"
Time.new.inspect                 #=> "2008-03-08 19:43:39 +0900"

class Foo
end
Foo.new.inspect                  #=> "#<Foo:0x0300c868>"

class Bar
  def initialize
    @bar = 1
  end
end
Bar.new.inspect                  #=> "#<Bar:0x0300c868 @bar=1>"

Returns:



818
819
820
821
822
823
824
825
826
827
828
829
830
831
 
# File 'object.c', line 818

static VALUE
rb_obj_inspect(VALUE obj)
{
    if (rb_ivar_count(obj) > 0) {
        VALUE str;
        VALUE c = rb_class_name(CLASS_OF(obj));

        str = rb_sprintf("-<%"PRIsVALUE":%p", c, (void*)obj);
        return rb_exec_recursive(inspect_obj, obj, str);
    }
    else {
        return rb_any_to_s(obj);
    }
}

#instance_of? ⇒ Boolean

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

class A;     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

Returns:

  • (Boolean) 


867
868
869
870
871
872
 
# File 'object.c', line 867

VALUE
rb_obj_is_instance_of(VALUE obj, VALUE c)
{
    c = class_or_module_required(c);
    return RBOOL(rb_obj_class(obj) == c);
}

#instance_variable_defined?(symbol) ⇒ Boolean #instance_variable_defined?(string) ⇒ Boolean

Returns true if the given instance variable is defined in obj. String arguments are converted to symbols.

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

Overloads:

  • #instance_variable_defined?(symbol) ⇒ Boolean

    Returns:

    • (Boolean)
  • #instance_variable_defined?(string) ⇒ Boolean

    Returns:

    • (Boolean) 


2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
 
# File 'object.c', line 2980

static VALUE
rb_obj_ivar_defined(VALUE obj, VALUE iv)
{
    ID id = id_for_var(obj, iv, instance);

    if (!id) {
        return Qfalse;
    }
    return rb_ivar_defined(obj, id);
}

#instance_variable_get(symbol) ⇒ Object #instance_variable_get(string) ⇒ Object

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. String arguments are converted to symbols.

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

Overloads:

  • #instance_variable_get(symbol) ⇒ Object

    Returns:

  • #instance_variable_get(string) ⇒ Object

    Returns:



2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
 
# File 'object.c', line 2918

static VALUE
rb_obj_ivar_get(VALUE obj, VALUE iv)
{
    ID id = id_for_var(obj, iv, instance);

    if (!id) {
        return Qnil;
    }
    return rb_ivar_get(obj, id);
}

#instance_variable_set(symbol, obj) ⇒ Object #instance_variable_set(string, obj) ⇒ Object

Sets the instance variable named by symbol to the given object. This may circumvent the encapsulation intended by the author of the class, so it should be used with care. The variable does not have to exist prior to this call. If the instance variable name is passed as a string, that string is converted to a symbol.

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\">"

Overloads:

  • #instance_variable_set(symbol, obj) ⇒ Object

    Returns:

  • #instance_variable_set(string, obj) ⇒ Object

    Returns:



2952
2953
2954
2955
2956
2957
2958
 
# File 'object.c', line 2952

static VALUE
rb_obj_ivar_set_m(VALUE obj, VALUE iv, VALUE val)
{
    ID id = id_for_var(obj, iv, instance);
    if (!id) id = rb_intern_str(iv);
    return rb_ivar_set(obj, id, val);
}

#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]

Returns:



2286
2287
2288
2289
2290
2291
2292
2293
2294
 
# File 'variable.c', line 2286

VALUE
rb_obj_instance_variables(VALUE obj)
{
    VALUE ary;

    ary = rb_ary_new();
    rb_ivar_foreach(obj, ivar_i, ary);
    return ary;
}

#is_a? ⇒ Boolean #kind_of? ⇒ Boolean

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.is_a? A          #=> true
b.is_a? B          #=> true
b.is_a? C          #=> false
b.is_a? M          #=> true

b.kind_of? A       #=> true
b.kind_of? B       #=> true
b.kind_of? C       #=> false
b.kind_of? M       #=> true

Overloads:

  • #is_a? ⇒ Boolean

    Returns:

    • (Boolean)
  • #kind_of? ⇒ Boolean

    Returns:

    • (Boolean) 


923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
 
# File 'object.c', line 923

VALUE
rb_obj_is_kind_of(VALUE obj, VALUE c)
{
    VALUE cl = CLASS_OF(obj);

    RUBY_ASSERT(RB_TYPE_P(cl, T_CLASS));

    // Fastest path: If the object's class is an exact match we know `c` is a
    // class without checking type and can return immediately.
    if (cl == c) return Qtrue;

    // Note: YJIT needs this function to never allocate and never raise when
    // `c` is a class or a module.

    if (LIKELY(RB_TYPE_P(c, T_CLASS))) {
        // Fast path: Both are T_CLASS
        return class_search_class_ancestor(cl, c);
    }
    else if (RB_TYPE_P(c, T_ICLASS)) {
        // First check if we inherit the includer
        // If we do we can return true immediately
        VALUE includer = RCLASS_INCLUDER(c);
        if (cl == includer) return Qtrue;

        // Usually includer is a T_CLASS here, except when including into an
        // already included Module.
        // If it is a class, attempt the fast class-to-class check and return
        // true if there is a match.
        if (RB_TYPE_P(includer, T_CLASS) && class_search_class_ancestor(cl, includer))
            return Qtrue;

        // We don't include the ICLASS directly, so must check if we inherit
        // the module via another include
        return RBOOL(class_search_ancestor(cl, RCLASS_ORIGIN(c)));
    }
    else if (RB_TYPE_P(c, T_MODULE)) {
        // Slow path: check each ancestor in the linked list and its method table
        return RBOOL(class_search_ancestor(cl, RCLASS_ORIGIN(c)));
    }
    else {
        rb_raise(rb_eTypeError, "class or module required");
        UNREACHABLE_RETURN(Qfalse);
    }
}

#itself ⇒ Object

Returns the receiver.

string = "my string"
string.itself.object_id == string.object_id   #=> true

Returns:



648
649
650
651
652
 
# File 'object.c', line 648

static VALUE
rb_obj_itself(VALUE obj)
{
    return obj;
}

#is_a? ⇒ Boolean #kind_of? ⇒ Boolean

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.is_a? A          #=> true
b.is_a? B          #=> true
b.is_a? C          #=> false
b.is_a? M          #=> true

b.kind_of? A       #=> true
b.kind_of? B       #=> true
b.kind_of? C       #=> false
b.kind_of? M       #=> true

Overloads:

  • #is_a? ⇒ Boolean

    Returns:

    • (Boolean)
  • #kind_of? ⇒ Boolean

    Returns:

    • (Boolean) 


923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
 
# File 'object.c', line 923

VALUE
rb_obj_is_kind_of(VALUE obj, VALUE c)
{
    VALUE cl = CLASS_OF(obj);

    RUBY_ASSERT(RB_TYPE_P(cl, T_CLASS));

    // Fastest path: If the object's class is an exact match we know `c` is a
    // class without checking type and can return immediately.
    if (cl == c) return Qtrue;

    // Note: YJIT needs this function to never allocate and never raise when
    // `c` is a class or a module.

    if (LIKELY(RB_TYPE_P(c, T_CLASS))) {
        // Fast path: Both are T_CLASS
        return class_search_class_ancestor(cl, c);
    }
    else if (RB_TYPE_P(c, T_ICLASS)) {
        // First check if we inherit the includer
        // If we do we can return true immediately
        VALUE includer = RCLASS_INCLUDER(c);
        if (cl == includer) return Qtrue;

        // Usually includer is a T_CLASS here, except when including into an
        // already included Module.
        // If it is a class, attempt the fast class-to-class check and return
        // true if there is a match.
        if (RB_TYPE_P(includer, T_CLASS) && class_search_class_ancestor(cl, includer))
            return Qtrue;

        // We don't include the ICLASS directly, so must check if we inherit
        // the module via another include
        return RBOOL(class_search_ancestor(cl, RCLASS_ORIGIN(c)));
    }
    else if (RB_TYPE_P(c, T_MODULE)) {
        // Slow path: check each ancestor in the linked list and its method table
        return RBOOL(class_search_ancestor(cl, RCLASS_ORIGIN(c)));
    }
    else {
        rb_raise(rb_eTypeError, "class or module required");
        UNREACHABLE_RETURN(Qfalse);
    }
}

#method(sym) ⇒ Object

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"

Note that Method implements to_proc method, which means it can be used with iterators.

[ 1, 2, 3 ].each(&method(:puts)) # => prints 3 lines to stdout

out = File.open('test.txt', 'w')
[ 1, 2, 3 ].each(&out.method(:puts)) # => prints 3 lines to file

require 'date'
%w[2017-03-01 2017-03-02].collect(&Date.method(:parse))
#=> [#<Date: 2017-03-01 ((2457814j,0s,0n),+0s,2299161j)>, #<Date: 2017-03-02 ((2457815j,0s,0n),+0s,2299161j)>]



2085
2086
2087
2088
2089
 
# File 'proc.c', line 2085

VALUE
rb_obj_method(VALUE obj, VALUE vid)
{
    return obj_method(obj, vid, FALSE);
}

#methods(regular = true) ⇒ Array

Returns a list of the names of public and protected methods of obj. This will include all the methods accessible in obj’s ancestors. If the optional parameter is false, it returns an array of obj’s public and protected singleton methods, the array will not include methods in modules included in obj.

class Klass
  def klass_method()
  end
end
k = Klass.new
k.methods[0..9]    #=> [:klass_method, :nil?, :===,
                   #    :==~, :!, :eql?
                   #    :hash, :<=>, :class, :singleton_class]
k.methods.length   #=> 56

k.methods(false)   #=> []
def k.singleton_method; end
k.methods(false)   #=> [:singleton_method]

module M123; def m123; end end
k.extend M123
k.methods(false)   #=> [:singleton_method]

Returns:



2002
2003
2004
2005
2006
2007
2008
2009
2010
 
# File 'class.c', line 2002

VALUE
rb_obj_methods(int argc, const VALUE *argv, VALUE obj)
{
    rb_check_arity(argc, 0, 1);
    if (argc > 0 && !RTEST(argv[0])) {
        return rb_obj_singleton_methods(argc, argv, obj);
    }
    return class_instance_method_list(argc, argv, CLASS_OF(obj), 1, ins_methods_i);
}

#nil? ⇒ Boolean

Only the object nil responds true to nil?.

Object.new.nil?   #=> false
nil.nil?          #=> true

Returns:

  • (Boolean) 


1663
1664
1665
1666
1667
 
# File 'object.c', line 1663

VALUE
rb_false(VALUE obj)
{
    return Qfalse;
}

#object_id ⇒ Object

call-seq:

obj.__id__       -> integer
obj.object_id    -> integer

Returns an integer identifier for obj.

The same number will be returned on all calls to object_id for a given object, and no two active objects will share an id.

Note: that some objects of builtin classes are reused for optimization. This is the case for immediate values and frozen string literals.

BasicObject implements __id__, Kernel implements object_id.

Immediate values are not passed by reference but are passed by value: nil, true, false, Fixnums, Symbols, and some Floats.

Object.new.object_id  == Object.new.object_id  # => false
(21 * 2).object_id    == (21 * 2).object_id    # => true
"hello".object_id     == "hello".object_id     # => false
"hi".freeze.object_id == "hi".freeze.object_id # => true



1898
1899
1900
1901
1902
1903
1904
1905
1906
 
# File 'gc.c', line 1898

VALUE
rb_obj_id(VALUE obj)
{
    /* If obj is an immediate, the object ID is obj directly converted to a Numeric.
     * Otherwise, the object ID is a Numeric that is a non-zero multiple of
     * (RUBY_IMMEDIATE_MASK + 1) which guarantees that it does not collide with
     * any immediates. */
    return rb_find_object_id(rb_gc_get_objspace(), obj, rb_gc_impl_object_id);
}

#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.

Returns:



2036
2037
2038
2039
2040
 
# File 'class.c', line 2036

VALUE
rb_obj_private_methods(int argc, const VALUE *argv, VALUE obj)
{
    return class_instance_method_list(argc, argv, CLASS_OF(obj), 1, ins_methods_priv_i);
}

#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.

Returns:



2021
2022
2023
2024
2025
 
# File 'class.c', line 2021

VALUE
rb_obj_protected_methods(int argc, const VALUE *argv, VALUE obj)
{
    return class_instance_method_list(argc, argv, CLASS_OF(obj), 1, ins_methods_prot_i);
}

#public_method(sym) ⇒ Object

Similar to method, searches public method only.



2098
2099
2100
2101
2102
 
# File 'proc.c', line 2098

VALUE
rb_obj_public_method(VALUE obj, VALUE vid)
{
    return obj_method(obj, vid, TRUE);
}

#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.

Returns:



2051
2052
2053
2054
2055
 
# File 'class.c', line 2051

VALUE
rb_obj_public_methods(int argc, const VALUE *argv, VALUE obj)
{
    return class_instance_method_list(argc, argv, CLASS_OF(obj), 1, ins_methods_pub_i);
}

#public_send(symbol[, args...]) ⇒ Object #public_send(string[, args...]) ⇒ Object

Invokes the method identified by symbol, passing it any arguments specified. Unlike send, public_send calls public methods only. When the method is identified by a string, the string is converted to a symbol.

1.public_send(:puts, "hello")  # causes NoMethodError

Overloads:

  • #public_send(symbol[, args...]) ⇒ Object

    Returns:

  • #public_send(string[, args...]) ⇒ Object

    Returns:



1327
1328
1329
1330
1331
 
# File 'vm_eval.c', line 1327

static VALUE
rb_f_public_send(int argc, VALUE *argv, VALUE recv)
{
    return send_internal_kw(argc, argv, recv, CALL_PUBLIC);
}

#remove_instance_variable(symbol) ⇒ Object #remove_instance_variable(string) ⇒ Object

Removes the named instance variable from obj, returning that variable’s value. The name can be passed as a symbol or as a string.

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

Overloads:

  • #remove_instance_variable(symbol) ⇒ Object

    Returns:

  • #remove_instance_variable(string) ⇒ Object

    Returns:



2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
 
# File 'variable.c', line 2340

VALUE
rb_obj_remove_instance_variable(VALUE obj, VALUE name)
{
    const ID id = id_for_var(obj, name, an, instance);

    // Frozen check comes here because it's expected that we raise a
    // NameError (from the id_for_var check) before we raise a FrozenError
    rb_check_frozen(obj);

    if (id) {
        VALUE val = rb_ivar_delete(obj, id, Qundef);

        if (!UNDEF_P(val)) return val;
    }

    rb_name_err_raise("instance variable %1$s not defined",
                      obj, name);
    UNREACHABLE_RETURN(Qnil);
}

#respond_to?(symbol, include_all = false) ⇒ Boolean #respond_to?(string, include_all = false) ⇒ Boolean

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

If the method is not implemented, as Process.fork on Windows, File.lchmod on GNU/Linux, etc., false is returned.

If the method is not defined, respond_to_missing? method is called and the result is returned.

When the method name parameter is given as a string, the string is converted to a symbol.

Overloads:

  • #respond_to?(symbol, include_all = false) ⇒ Boolean

    Returns:

    • (Boolean)
  • #respond_to?(string, include_all = false) ⇒ Boolean

    Returns:

    • (Boolean) 


2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
 
# File 'vm_method.c', line 2986

static VALUE
obj_respond_to(int argc, VALUE *argv, VALUE obj)
{
    VALUE mid, priv;
    ID id;
    rb_execution_context_t *ec = GET_EC();

    rb_scan_args(argc, argv, "11", &mid, &priv);
    if (!(id = rb_check_id(&mid))) {
        VALUE ret = basic_obj_respond_to_missing(ec, CLASS_OF(obj), obj,
                                                 rb_to_symbol(mid), priv);
        if (UNDEF_P(ret)) ret = Qfalse;
        return ret;
    }
    return  RBOOL(basic_obj_respond_to(ec, obj, id, !RTEST(priv)));
}

#respond_to_missing?(symbol, include_all) ⇒ Boolean #respond_to_missing?(string, include_all) ⇒ Boolean

DO NOT USE THIS DIRECTLY.

Hook method to return whether the obj can respond to id method or not.

When the method name parameter is given as a string, the string is converted to a symbol.

See #respond_to?, and the example of BasicObject.

Overloads:

  • #respond_to_missing?(symbol, include_all) ⇒ Boolean

    Returns:

    • (Boolean)
  • #respond_to_missing?(string, include_all) ⇒ Boolean

    Returns:

    • (Boolean) 


3018
3019
3020
3021
3022
 
# File 'vm_method.c', line 3018

static VALUE
obj_respond_to_missing(VALUE obj, VALUE mid, VALUE priv)
{
    return Qfalse;
}

#send(symbol[, args...]) ⇒ Object #__send__(symbol[, args...]) ⇒ Object #send(string[, args...]) ⇒ Object #__send__(string[, args...]) ⇒ Object

Invokes the method identified by symbol, passing it any

arguments specified.
When the method is identified by a string, the string is converted
to a symbol.

BasicObject implements +__send__+, Kernel implements +send+.
<code>__send__</code> is safer than +send+
when _obj_ has the same method name like <code>Socket</code>.
See also <code>public_send</code>.

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

Overloads:



1307
1308
1309
1310
1311
 
# File 'vm_eval.c', line 1307

VALUE
rb_f_send(int argc, VALUE *argv, VALUE recv)
{
    return send_internal_kw(argc, argv, recv, CALL_FCALL);
}

#singleton_class ⇒ Class

Returns the singleton class of obj. This method creates a new singleton class if obj does not have one.

If obj is nil, true, or false, it returns NilClass, TrueClass, or FalseClass, respectively. If obj is an Integer, a Float or a Symbol, it raises a TypeError.

Object.new.singleton_class  #=> #<Class:#<Object:0xb7ce1e24>>
String.singleton_class      #=> #<Class:String>
nil.singleton_class         #=> NilClass

Returns:



319
320
321
322
323
 
# File 'object.c', line 319

static VALUE
rb_obj_singleton_class(VALUE obj)
{
    return rb_singleton_class(obj);
}

#singleton_method(sym) ⇒ Object

Similar to method, searches singleton method only.

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

k = Demo.new(99)
def k.hi
  "Hi, @iv = #{@iv}"
end
m = k.singleton_method(:hi)
m.call   #=> "Hi, @iv = 99"
m = k.singleton_method(:hello) #=> NameError



2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
 
# File 'proc.c', line 2141

VALUE
rb_obj_singleton_method(VALUE obj, VALUE vid)
{
    VALUE sc = rb_singleton_class_get(obj);
    VALUE klass;
    ID id = rb_check_id(&vid);

    if (NIL_P(sc) ||
        NIL_P(klass = RCLASS_ORIGIN(sc)) ||
        !NIL_P(rb_special_singleton_class(obj))) {
        /* goto undef; */
    }
    else if (! id) {
        VALUE m = mnew_missing_by_name(klass, obj, &vid, FALSE, rb_cMethod);
        if (m) return m;
        /* else goto undef; */
    }
    else {
        VALUE args[2] = {obj, vid};
        VALUE ruby_method = rb_rescue(rb_obj_singleton_method_lookup, (VALUE)args, rb_obj_singleton_method_lookup_fail, Qfalse);
        if (ruby_method) {
            struct METHOD *method = (struct METHOD *)RTYPEDDATA_GET_DATA(ruby_method);
            VALUE lookup_class = RBASIC_CLASS(obj);
            VALUE stop_class = rb_class_superclass(sc);
            VALUE method_class = method->iclass;

            /* Determine if method is in singleton class, or module included in or prepended to it */
            do {
                if (lookup_class == method_class) {
                    return ruby_method;
                }
                lookup_class = RCLASS_SUPER(lookup_class);
            } while (lookup_class && lookup_class != stop_class);
        }
    }

  /* undef: */
    vid = ID2SYM(id);
    rb_name_err_raise("undefined singleton method '%1$s' for '%2$s'",
                      obj, vid);
    UNREACHABLE_RETURN(Qundef);
}

#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. Only public and protected singleton methods are returned.

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]

Returns:



2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
 
# File 'class.c', line 2090

VALUE
rb_obj_singleton_methods(int argc, const VALUE *argv, VALUE obj)
{
    VALUE ary, klass, origin;
    struct method_entry_arg me_arg;
    struct rb_id_table *mtbl;
    int recur = TRUE;

    if (rb_check_arity(argc, 0, 1)) recur = RTEST(argv[0]);
    if (RCLASS_SINGLETON_P(obj)) {
        rb_singleton_class(obj);
    }
    klass = CLASS_OF(obj);
    origin = RCLASS_ORIGIN(klass);
    me_arg.list = st_init_numtable();
    me_arg.recur = recur;
    if (klass && RCLASS_SINGLETON_P(klass)) {
        if ((mtbl = RCLASS_M_TBL(origin)) != 0) rb_id_table_foreach(mtbl, method_entry_i, &me_arg);
        klass = RCLASS_SUPER(klass);
    }
    if (recur) {
        while (klass && (RCLASS_SINGLETON_P(klass) || RB_TYPE_P(klass, T_ICLASS))) {
            if (klass != origin && (mtbl = RCLASS_M_TBL(klass)) != 0) rb_id_table_foreach(mtbl, method_entry_i, &me_arg);
            klass = RCLASS_SUPER(klass);
        }
    }
    ary = rb_ary_new2(me_arg.list->num_entries);
    st_foreach(me_arg.list, ins_methods_i, ary);
    st_free_table(me_arg.list);

    return ary;
}

#to_enum(method = :each, *args) ⇒ Enumerator #enum_for(method = :each, *args) ⇒ Enumerator #to_enum(method = :each, *args) {|*args| ... } ⇒ Enumerator #enum_for(method = :each, *args) {|*args| ... } ⇒ Enumerator

Creates a new Enumerator which will enumerate by calling method on obj, passing args if any. What was yielded by method becomes values of enumerator.

If a block is given, it will be used to calculate the size of the enumerator without the need to iterate it (see Enumerator#size).

Examples

str = "xyz"

enum = str.enum_for(:each_byte)
enum.each { |b| puts b }
# => 120
# => 121
# => 122

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

# String#split in block form is more memory-effective:
very_large_string.split("|") { |chunk| return chunk if chunk.include?('DATE') }
# This could be rewritten more idiomatically with to_enum:
very_large_string.to_enum(:split, "|").lazy.grep(/DATE/).first

It is typical to call to_enum when defining methods for a generic Enumerable, in case no block is passed.

Here is such an example, with parameter passing and a sizing block:

module Enumerable
  # a generic method to repeat the values of any enumerable
  def repeat(n)
    raise ArgumentError, "#{n} is negative!" if n < 0
    unless block_given?
      return to_enum(__method__, n) do # __method__ is :repeat here
        sz = size     # Call size and multiply by n...
        sz * n if sz  # but return nil if size itself is nil
      end
    end
    each do |*val|
      n.times { yield *val }
    end
  end
end

%i[hello world].repeat(2) { |w| puts w }
  # => Prints 'hello', 'hello', 'world', 'world'
enum = (1..14).repeat(3)
  # => returns an Enumerator when called without a block
enum.first(4) # => [1, 1, 1, 2]
enum.size # => 42

Overloads:



381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
 
# File 'enumerator.c', line 381

static VALUE
obj_to_enum(int argc, VALUE *argv, VALUE obj)
{
    VALUE enumerator, meth = sym_each;

    if (argc > 0) {
        --argc;
        meth = *argv++;
    }
    enumerator = rb_enumeratorize_with_size(obj, meth, argc, argv, 0);
    if (rb_block_given_p()) {
        RB_OBJ_WRITE(enumerator, &enumerator_ptr(enumerator)->size, rb_block_proc());
    }
    return enumerator;
}

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

Returns:



727
728
729
730
731
732
733
734
735
736
 
# File 'object.c', line 727

VALUE
rb_any_to_s(VALUE obj)
{
    VALUE str;
    VALUE cname = rb_class_name(CLASS_OF(obj));

    str = rb_sprintf("#<%"PRIsVALUE":%p>", cname, (void*)obj);

    return str;
}