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

Constant Summary collapse

Bignum =

An obsolete class, use Integer

rb_cInteger
Fixnum =

An obsolete class, use Integer

rb_cInteger

Instance Method Summary collapse

Methods included from Kernel

#Array, #Complex, #Hash, #Integer, #Rational, #String, #__callee__, #__dir__, #__method__, #`, #abort, #at_exit, #autoload, #autoload?, #binding, #block_given?, #callcc, #caller, #caller_locations, #catch, #eval, #exec, #exit, #exit!, #fail, #fork, #format, #gets, #global_variables, #iterator?, #lambda, #load, #local_variables, #loop, #open, #p, #print, #printf, #proc, #putc, #puts, #raise, #rand, #readline, #readlines, #require, #require_relative, #select, #set_trace_func, #sleep, #spawn, #sprintf, #srand, #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)

1606
1607
1608
1609
1610
1611
# File 'object.c', line 1606

static VALUE
rb_obj_not_match(VALUE obj1, VALUE obj2)
{
    VALUE result = rb_funcall(obj1, id_match, 1, obj2);
    return RTEST(result) ? Qfalse : Qtrue;
}

#<=>(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)

1632
1633
1634
1635
1636
1637
1638
# File 'object.c', line 1632

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

#===Object

#=~(other) ⇒ nil

This method is deprecated.

This is not only useless but also troublesome because it may hide a type error.

Returns:

  • (nil)

1588
1589
1590
1591
1592
1593
1594
1595
1596
# File 'object.c', line 1588

static VALUE
rb_obj_match(VALUE obj1, VALUE obj2)
{
    if (rb_warning_category_enabled_p(RB_WARN_CATEGORY_DEPRECATED)) {
        rb_category_warn(RB_WARN_CATEGORY_DEPRECATED, "deprecated Object#=~ is called on %"PRIsVALUE
                "; it always returns nil", rb_obj_class(obj1));
    }
    return Qnil;
}

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

Defines a 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:


2276
2277
2278
2279
2280
2281
2282
# File 'proc.c', line 2276

static VALUE
rb_obj_define_method(int argc, VALUE *argv, VALUE obj)
{
    VALUE klass = rb_singleton_class(obj);

    return rb_mod_define_method(argc, argv, klass);
}

#display(port = $>) ⇒ nil

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

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

For example:

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

produces:

1cat[4, 5, 6]

Returns:

  • (nil)

8028
8029
8030
8031
8032
8033
8034
8035
8036
8037
# File 'io.c', line 8028

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;
}

#dupObject

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:


558
559
560
561
562
563
564
565
566
567
568
569
570
571
# File 'object.c', line 558

VALUE
rb_obj_dup(VALUE obj)
{
    VALUE dup;

    if (special_object_p(obj)) {
	return obj;
    }
    dup = rb_obj_alloc(rb_obj_class(obj));
    init_copy(dup, obj);
    rb_funcall(dup, id_init_dup, 1, obj);

    return 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:


368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
# File 'enumerator.c', line 368

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()) {
	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)

234
235
236
237
238
239
# File 'object.c', line 234

MJIT_FUNC_EXPORTED VALUE
rb_obj_equal(VALUE obj1, VALUE obj2)
{
    if (obj1 == obj2) return Qtrue;
    return Qfalse;
}

#extendObject

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:


1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
# File 'eval.c', line 1790

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);
    while (argc--) {
	rb_funcall(argv[argc], id_extend_object, 1, obj);
	rb_funcall(argv[argc], id_extended, 1, obj);
    }
    return obj;
}

#freezeObject

Prevents further modifications to obj. A RuntimeError 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:


1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
# File 'object.c', line 1277

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;
}

#hashObject


241
# File 'object.c', line 241

VALUE rb_obj_hash(VALUE obj);

#initialize_clone(*args) ⇒ Object

!

:nodoc:

647
648
649
650
651
652
653
654
655
656
# File 'object.c', line 647

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

#initialize_copy(orig) ⇒ Object

:nodoc:


610
611
612
613
614
615
616
617
618
619
# File 'object.c', line 610

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:

630
631
632
633
634
635
# File 'object.c', line 630

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

#inspectString

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:


777
778
779
780
781
782
783
784
785
786
787
788
789
790
# File 'object.c', line 777

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)

833
834
835
836
837
838
839
# File 'object.c', line 833

VALUE
rb_obj_is_instance_of(VALUE obj, VALUE c)
{
    c = class_or_module_required(c);
    if (rb_obj_class(obj) == c) return Qtrue;
    return Qfalse;
}

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

2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
# File 'object.c', line 2932

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:


2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
# File 'object.c', line 2870

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:


2904
2905
2906
2907
2908
2909
2910
# File 'object.c', line 2904

static VALUE
rb_obj_ivar_set(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_variablesArray

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:


1800
1801
1802
1803
1804
1805
1806
1807
1808
# File 'variable.c', line 1800

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)

877
878
879
880
881
882
883
884
# File 'object.c', line 877

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

    c = class_or_module_required(c);
    return class_search_ancestor(cl, RCLASS_ORIGIN(c)) ? Qtrue : Qfalse;
}

#itselfObject

Returns the receiver.

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

Returns:


584
585
586
587
588
# File 'object.c', line 584

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)

877
878
879
880
881
882
883
884
# File 'object.c', line 877

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

    c = class_or_module_required(c);
    return class_search_ancestor(cl, RCLASS_ORIGIN(c)) ? Qtrue : 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)>]

1991
1992
1993
1994
1995
# File 'proc.c', line 1991

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:


1549
1550
1551
1552
1553
1554
1555
1556
1557
# File 'class.c', line 1549

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)

1571
1572
1573
1574
1575
# File 'object.c', line 1571

MJIT_FUNC_EXPORTED VALUE
rb_false(VALUE obj)
{
    return Qfalse;
}

#object_idObject

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

4115
4116
4117
4118
4119
4120
4121
4122
4123
4124
4125
4126
4127
4128
4129
4130
4131
4132
4133
4134
4135
4136
4137
4138
4139
4140
4141
4142
4143
4144
4145
4146
4147
4148
# File 'gc.c', line 4115

VALUE
rb_obj_id(VALUE obj)
{
    /*
     *                32-bit VALUE space
     *          MSB ------------------------ LSB
     *  false   00000000000000000000000000000000
     *  true    00000000000000000000000000000010
     *  nil     00000000000000000000000000000100
     *  undef   00000000000000000000000000000110
     *  symbol  ssssssssssssssssssssssss00001110
     *  object  oooooooooooooooooooooooooooooo00        = 0 (mod sizeof(RVALUE))
     *  fixnum  fffffffffffffffffffffffffffffff1
     *
     *                    object_id space
     *                                       LSB
     *  false   00000000000000000000000000000000
     *  true    00000000000000000000000000000010
     *  nil     00000000000000000000000000000100
     *  undef   00000000000000000000000000000110
     *  symbol   000SSSSSSSSSSSSSSSSSSSSSSSSSSS0        S...S % A = 4 (S...S = s...s * A + 4)
     *  object   oooooooooooooooooooooooooooooo0        o...o % A = 0
     *  fixnum  fffffffffffffffffffffffffffffff1        bignum if required
     *
     *  where A = sizeof(RVALUE)/4
     *
     *  sizeof(RVALUE) is
     *  20 if 32-bit, double is 4-byte aligned
     *  24 if 32-bit, double is 8-byte aligned
     *  40 if 64-bit
     */

    return rb_find_object_id(obj, cached_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:


1583
1584
1585
1586
1587
# File 'class.c', line 1583

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:


1568
1569
1570
1571
1572
# File 'class.c', line 1568

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.


2004
2005
2006
2007
2008
# File 'proc.c', line 2004

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:


1598
1599
1600
1601
1602
# File 'class.c', line 1598

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:


1154
1155
1156
1157
1158
# File 'vm_eval.c', line 1154

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

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:


1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
# File 'variable.c', line 1855

VALUE
rb_obj_remove_instance_variable(VALUE obj, VALUE name)
{
    VALUE val = Qnil;
    const ID id = id_for_var(obj, name, an, instance);
    st_data_t n, v;
    struct st_table *iv_index_tbl;
    uint32_t index;

    rb_check_frozen(obj);
    if (!id) {
	goto not_defined;
    }

    switch (BUILTIN_TYPE(obj)) {
      case T_OBJECT:
        iv_index_tbl = ROBJECT_IV_INDEX_TBL(obj);
        if (iv_index_tbl_lookup(iv_index_tbl, id, &index) &&
            index < ROBJECT_NUMIV(obj) &&
            (val = ROBJECT_IVPTR(obj)[index]) != Qundef) {
            ROBJECT_IVPTR(obj)[index] = Qundef;
            return val;
        }
	break;
      case T_CLASS:
      case T_MODULE:
        IVAR_ACCESSOR_SHOULD_BE_MAIN_RACTOR(id);
	n = id;
	if (RCLASS_IV_TBL(obj) && st_delete(RCLASS_IV_TBL(obj), &n, &v)) {
	    return (VALUE)v;
	}
	break;
      default:
	if (FL_TEST(obj, FL_EXIVAR)) {
	    if (generic_ivar_remove(obj, id, &val)) {
		return val;
	    }
	}
	break;
    }

  not_defined:
    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)

2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
# File 'vm_method.c', line 2547

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 (ret == Qundef) ret = Qfalse;
	return ret;
    }
    if (basic_obj_respond_to(ec, CLASS_OF(obj), obj, id, !RTEST(priv)))
	return Qtrue;
    return Qfalse;
}

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

2581
2582
2583
2584
2585
# File 'vm_method.c', line 2581

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:


1134
1135
1136
1137
1138
# File 'vm_eval.c', line 1134

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

#singleton_classClass

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:


317
318
319
320
321
# File 'object.c', line 317

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

2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
# File 'proc.c', line 2034

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

    if (NIL_P(klass)) {
        /* goto undef; */
    }
    else if (NIL_P(klass = RCLASS_ORIGIN(klass))) {
        /* 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 {
        const rb_method_entry_t *me = rb_method_entry_at(klass, id);
        vid = ID2SYM(id);

        if (UNDEFINED_METHOD_ENTRY_P(me)) {
            /* goto undef; */
        }
        else if (UNDEFINED_REFINED_METHOD_P(me->def)) {
            /* goto undef; */
        }
        else {
            return mnew_from_me(me, klass, klass, obj, id, rb_cMethod, FALSE);
        }
    }

  /* undef: */
    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:


1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
# File 'class.c', line 1637

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 (RB_TYPE_P(obj, T_CLASS) && FL_TEST(obj, FL_SINGLETON)) {
        rb_singleton_class(obj);
    }
    klass = CLASS_OF(obj);
    origin = RCLASS_ORIGIN(klass);
    me_arg.list = st_init_numtable();
    me_arg.recur = recur;
    if (klass && FL_TEST(klass, FL_SINGLETON)) {
	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 && (FL_TEST(klass, FL_SINGLETON) || 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;
}

#taintObject

Returns object. This method is deprecated and will be removed in Ruby 3.2.

Returns:


1173
1174
1175
1176
1177
1178
# File 'object.c', line 1173

VALUE
rb_obj_taint(VALUE obj)
{
    rb_warn_deprecated_to_remove("Object#taint", "3.2");
    return obj;
}

#tainted?false

Returns false. This method is deprecated and will be removed in Ruby 3.2.

Returns:

  • (false)

1159
1160
1161
1162
1163
1164
# File 'object.c', line 1159

VALUE
rb_obj_tainted(VALUE obj)
{
    rb_warn_deprecated_to_remove("Object#tainted?", "3.2");
    return Qfalse;
}

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


368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
# File 'enumerator.c', line 368

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()) {
	enumerator_ptr(enumerator)->size = rb_block_proc();
    }
    return enumerator;
}

#to_sString

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:


671
672
673
674
675
676
677
678
679
680
# File 'object.c', line 671

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;
}

#trustObject

Returns object. This method is deprecated and will be removed in Ruby 3.2.

Returns:


1231
1232
1233
1234
1235
1236
# File 'object.c', line 1231

VALUE
rb_obj_trust(VALUE obj)
{
    rb_warn_deprecated_to_remove("Object#trust", "3.2");
    return obj;
}

#untaintObject

Returns object. This method is deprecated and will be removed in Ruby 3.2.

Returns:


1188
1189
1190
1191
1192
1193
# File 'object.c', line 1188

VALUE
rb_obj_untaint(VALUE obj)
{
    rb_warn_deprecated_to_remove("Object#untaint", "3.2");
    return obj;
}

#untrustObject

Returns object. This method is deprecated and will be removed in Ruby 3.2.

Returns:


1216
1217
1218
1219
1220
1221
# File 'object.c', line 1216

VALUE
rb_obj_untrust(VALUE obj)
{
    rb_warn_deprecated_to_remove("Object#untrust", "3.2");
    return obj;
}

#untrusted?false

Returns false. This method is deprecated and will be removed in Ruby 3.2.

Returns:

  • (false)

1202
1203
1204
1205
1206
1207
# File 'object.c', line 1202

VALUE
rb_obj_untrusted(VALUE obj)
{
    rb_warn_deprecated_to_remove("Object#untrusted?", "3.2");
    return Qfalse;
}