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

1655
1656
1657
1658
1659
1660
# File 'object.c', line 1655

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)

1681
1682
1683
1684
1685
1686
1687
# File 'object.c', line 1681

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

#===(other) ⇒ Boolean

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

Returns:

  • (Boolean)

144
145
146
147
148
149
150
151
152
153
154
155
156
# File 'object.c', line 144

VALUE
rb_equal(VALUE obj1, VALUE obj2)
{
    VALUE result;

    if (obj1 == obj2) return Qtrue;
    result = rb_equal_opt(obj1, obj2);
    if (result == Qundef) {
	result = rb_funcall(obj1, id_eq, 1, obj2);
    }
    if (RTEST(result)) return Qtrue;
    return Qfalse;
}

#=~(other) ⇒ nil

This method is deprecated.

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

Returns:

  • (nil)

1637
1638
1639
1640
1641
1642
1643
1644
1645
# File 'object.c', line 1637

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

#classClass

Returns the class of obj. This method must always be called with an explicit receiver, as #class is also a reserved word in Ruby.

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

Returns:


298
299
300
301
302
# File 'object.c', line 298

VALUE
rb_obj_class(VALUE obj)
{
    return rb_class_real(CLASS_OF(obj));
}

#clone(freeze: true) ⇒ Object

Produces a shallow copy of obj—the instance variables of obj are copied, but not the objects they reference. #clone copies the frozen (unless :freeze keyword argument is given with a false value) 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.

Returns:


417
418
419
420
421
422
423
424
# File 'object.c', line 417

static VALUE
rb_obj_clone2(int argc, VALUE *argv, VALUE obj)
{
    int kwfreeze = freeze_opt(argc, argv);
    if (!special_object_p(obj))
	return mutable_obj_clone(obj, kwfreeze);
    return immutable_obj_clone(obj, kwfreeze);
}

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


2157
2158
2159
2160
2161
2162
2163
# File 'proc.c', line 2157

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)

7910
7911
7912
7913
7914
7915
7916
7917
7918
7919
# File 'io.c', line 7910

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

    out = (!rb_check_arity(argc, 0, 1) ? rb_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:0x401b3a38> s2.foo #=> “foo”

s3 = s1.dup #=> #<Klass:0x401b3a38> s3.foo #=> NoMethodError: undefined method `foo' for #<Klass:0x401b3a38>

Returns:


543
544
545
546
547
548
549
550
551
552
553
554
555
556
# File 'object.c', line 543

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:


359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
# File 'enumerator.c', line 359

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)

222
223
224
225
226
227
# File 'object.c', line 222

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:


1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
# File 'eval.c', line 1776

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:


1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
# File 'object.c', line 1299

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

#frozen?Boolean

Returns the freeze status of obj.

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

Returns:

  • (Boolean)

1328
1329
1330
1331
1332
# File 'object.c', line 1328

VALUE
rb_obj_frozen_p(VALUE obj)
{
    return OBJ_FROZEN(obj) ? Qtrue : Qfalse;
}

#hashObject


229
# File 'object.c', line 229

VALUE rb_obj_hash(VALUE obj);

#initialize_clone(orig) ⇒ Object

!

:nodoc:

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

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

#initialize_copy(orig) ⇒ Object

:nodoc:


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

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:

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

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:


772
773
774
775
776
777
778
779
780
781
782
783
784
785
# File 'object.c', line 772

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)

830
831
832
833
834
835
836
# File 'object.c', line 830

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)

2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
# File 'object.c', line 2954

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:


2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
# File 'object.c', line 2892

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, thereby frustrating the efforts of the class's author to attempt to provide proper encapsulation. 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:


2926
2927
2928
2929
2930
2931
2932
# File 'object.c', line 2926

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:


1589
1590
1591
1592
1593
1594
1595
1596
1597
# File 'variable.c', line 1589

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)

874
875
876
877
878
879
880
881
# File 'object.c', line 874

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:


569
570
571
572
573
# File 'object.c', line 569

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)

874
875
876
877
878
879
880
881
# File 'object.c', line 874

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


1866
1867
1868
1869
1870
# File 'proc.c', line 1866

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:


1368
1369
1370
1371
1372
1373
1374
1375
1376
# File 'class.c', line 1368

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)

1620
1621
1622
1623
1624
# File 'object.c', line 1620

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

3802
3803
3804
3805
3806
3807
3808
3809
3810
3811
3812
3813
3814
3815
3816
3817
3818
3819
3820
3821
3822
3823
3824
3825
3826
3827
3828
3829
3830
3831
3832
3833
3834
3835
# File 'gc.c', line 3802

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:


1402
1403
1404
1405
1406
# File 'class.c', line 1402

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:


1387
1388
1389
1390
1391
# File 'class.c', line 1387

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.


1879
1880
1881
1882
1883
# File 'proc.c', line 1879

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:


1417
1418
1419
1420
1421
# File 'class.c', line 1417

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:


1207
1208
1209
1210
1211
# File 'vm_eval.c', line 1207

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:


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
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
# File 'variable.c', line 1644

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;
    st_data_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) break;
        if (!st_lookup(iv_index_tbl, (st_data_t)id, &index)) break;
        if (ROBJECT_NUMIV(obj) <= index) break;
        val = ROBJECT_IVPTR(obj)[index];
        if (val != Qundef) {
            ROBJECT_IVPTR(obj)[index] = Qundef;
            return val;
        }
	break;
      case T_CLASS:
      case T_MODULE:
	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)

2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
# File 'vm_method.c', line 2216

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

2250
2251
2252
2253
2254
# File 'vm_method.c', line 2250

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. You can use <code>__send__</code> if the name
+send+ clashes with an existing method in _obj_.
When the method is identified by a string, the string is converted
to a symbol.

BasicObject implements +__send__+, Kernel implements +send+.

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

Overloads:


1187
1188
1189
1190
1191
# File 'vm_eval.c', line 1187

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:


321
322
323
324
325
# File 'object.c', line 321

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

1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
# File 'proc.c', line 1909

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

    if (NIL_P(klass) || NIL_P(klass = RCLASS_ORIGIN(klass))) {
      undef:
	rb_name_err_raise("undefined singleton method `%1$s' for `%2$s'",
			  obj, vid);
    }
    if (!id) {
        VALUE m = mnew_missing_by_name(klass, obj, &vid, FALSE, rb_cMethod);
        if (m) return m;
	goto undef;
    }
    me = rb_method_entry_at(klass, id);
    if (UNDEFINED_METHOD_ENTRY_P(me) ||
	UNDEFINED_REFINED_METHOD_P(me->def)) {
	vid = ID2SYM(id);
	goto undef;
    }
    return mnew_from_me(me, klass, klass, obj, id, rb_cMethod, FALSE);
}

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


1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
# File 'class.c', line 1456

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:


1195
1196
1197
1198
1199
1200
# File 'object.c', line 1195

VALUE
rb_obj_taint(VALUE obj)
{
    rb_warning("Object#taint is deprecated and will be removed in Ruby 3.2.");
    return obj;
}

#tainted?false

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

Returns:

  • (false)

1181
1182
1183
1184
1185
1186
# File 'object.c', line 1181

VALUE
rb_obj_tainted(VALUE obj)
{
    rb_warning("Object#tainted? is deprecated and will be removed in Ruby 3.2.");
    return Qfalse;
}

#tap {|x| ... } ⇒ Object

Yields self to the block, and then returns self. 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}" }
  .to_a                  .tap {|x| puts "array:    #{x}" }
  .select {|x| x.even? } .tap {|x| puts "evens:    #{x}" }
  .map {|x| x*x }        .tap {|x| puts "squares:  #{x}" }

Yields:

  • (x)

Returns:


921
922
923
924
925
926
# File 'object.c', line 921

VALUE
rb_obj_tap(VALUE obj)
{
    rb_yield(obj);
    return obj;
}

#then {|x| ... } ⇒ Object #yield_self {|x| ... } ⇒ Object

Yields self to the block and returns the result of the block.

3.next.then {|x| x**x }.to_s             #=> "256"
"my string".yield_self {|s| s.upcase }   #=> "MY STRING"

Good usage for then is value piping in method chains:

require 'open-uri'
require 'json'

construct_url(arguments).
  then {|url| open(url).read }.
  then {|response| JSON.parse(response) }

When called without block, the method returns Enumerator, which can be used, for example, for conditional circuit-breaking:

# meets condition, no-op
1.then.detect(&:odd?)            # => 1
# does not meet condition, drop value
2.then.detect(&:odd?)            # => nil

Overloads:

  • #then {|x| ... } ⇒ Object

    Yields:

    • (x)

    Returns:

  • #yield_self {|x| ... } ⇒ Object

    Yields:

    • (x)

    Returns:


611
612
613
614
615
616
# File 'object.c', line 611

static VALUE
rb_obj_yield_self(VALUE obj)
{
    RETURN_SIZED_ENUMERATOR(obj, 0, 0, rb_obj_size);
    return rb_yield_values2(1, &obj);
}

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


359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
# File 'enumerator.c', line 359

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:


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

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:


1253
1254
1255
1256
1257
1258
# File 'object.c', line 1253

VALUE
rb_obj_trust(VALUE obj)
{
    rb_warning("Object#trust is deprecated and will be removed in Ruby 3.2.");
    return obj;
}

#untaintObject

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

Returns:


1210
1211
1212
1213
1214
1215
# File 'object.c', line 1210

VALUE
rb_obj_untaint(VALUE obj)
{
    rb_warning("Object#untaint is deprecated and will be removed in Ruby 3.2.");
    return obj;
}

#untrustObject

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

Returns:


1238
1239
1240
1241
1242
1243
# File 'object.c', line 1238

VALUE
rb_obj_untrust(VALUE obj)
{
    rb_warning("Object#untrust is deprecated and will be removed in Ruby 3.2.");
    return obj;
}

#untrusted?false

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

Returns:

  • (false)

1224
1225
1226
1227
1228
1229
# File 'object.c', line 1224

VALUE
rb_obj_untrusted(VALUE obj)
{
    rb_warning("Object#untrusted? is deprecated and will be removed in Ruby 3.2.");
    return Qfalse;
}

#then {|x| ... } ⇒ Object #yield_self {|x| ... } ⇒ Object

Yields self to the block and returns the result of the block.

3.next.then {|x| x**x }.to_s             #=> "256"
"my string".yield_self {|s| s.upcase }   #=> "MY STRING"

Good usage for then is value piping in method chains:

require 'open-uri'
require 'json'

construct_url(arguments).
  then {|url| open(url).read }.
  then {|response| JSON.parse(response) }

When called without block, the method returns Enumerator, which can be used, for example, for conditional circuit-breaking:

# meets condition, no-op
1.then.detect(&:odd?)            # => 1
# does not meet condition, drop value
2.then.detect(&:odd?)            # => nil

Overloads:

  • #then {|x| ... } ⇒ Object

    Yields:

    • (x)

    Returns:

  • #yield_self {|x| ... } ⇒ Object

    Yields:

    • (x)

    Returns:


611
612
613
614
615
616
# File 'object.c', line 611

static VALUE
rb_obj_yield_self(VALUE obj)
{
    RETURN_SIZED_ENUMERATOR(obj, 0, 0, rb_obj_size);
    return rb_yield_values2(1, &obj);
}