Programming Ruby

The Pragmatic Programmer's Guide

Previous < Contents ^
Next >
class Object
Parent:
Version: 1.6

Index:

== === =~ __id__ __send__ class clone display dup eql? equal? extend freeze frozen? hash id inspect instance_eval instance_of? instance_variables is_a? kind_of? method method_missing methods nil? private_methods protected_methods public_methods respond_to? send singleton_methods taint tainted? to_a to_s type untaint



Subclasses: Array, Binding, Continuation, Data, Dir, Exception, FalseClass, File::Stat, Hash, IO, MatchingData, Method, Module, NilClass, Numeric, Proc, Range, Regexp, String, Struct, Symbol, Thread, Time, TrueClass

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

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

In the descriptions that follow, the parameter aSymbol refers to a symbol, which is either a quoted string or a Symbol (such as :name).

instance methods
== obj == anObject -> true or false

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

=== obj === anObject -> true or false

Case Equality---A synonym for Object#== , but typically overridden by descendents to provide meaningful semantics in case statements.

=~ obj =~ anObject -> false

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

__id__ obj.__id__ -> aFixnum

Synonym for Object#id .

__send__ obj.__send__( aSymbol [, args ]+ ) -> anObject

Synonym for Object#send .

class obj.class -> aClass

Returns the class of obj (synonym for Object#type ).

clone obj.clone -> anObject

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

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

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

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

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

dup obj.dup -> anObject

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

eql? obj.eql?( anObject ) -> true or false

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

1 == 1.0 » true
1.eql? 1.0 » false

equal? obj.equal?( anObject ) -> true or false

Returns true if obj and anObject have the same object ID. This method should not be overridden by subclasses.

a = [ 'cat', 'dog' ]
b = [ 'cat', 'dog' ]
a == b » true
a.id == b.id » false
a.eql?(b) » true
a.equal?(b) » false

extend obj.extend( [ aModule ]+ ) -> obj

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

module Mod
  def hello
    "Hello from Mod.\n"
  end
end
class Klass
  def hello
    "Hello from Klass.\n"
  end
end
k = Klass.new
k.hello » "Hello from Klass.\n"
k.extend(Mod) » #<Klass:0x401b598c>
k.hello » "Hello from Mod.\n"

freeze obj.freeze -> obj

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

a = [ "a", "b", "c" ]
a.freeze
a << "z"
produces:
prog.rb:3:in `<<': can't modify frozen array (TypeError)
	from prog.rb:3

frozen? obj.frozen? -> true or false

Returns the freeze status of obj.

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

hash obj.hash -> aFixnum

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

id obj.id -> aFixnum

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

inspect obj.inspect -> aString

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

[ 1, 2, 3..4, 'five' ].inspect » "[1, 2, 3..4, \"five\"]"
Time.new.inspect » "Sun Jun 09 00:18:15 CDT 2002"

instance_eval obj.instance_eval(aString [, file [ line ] ] ) -> anObject
obj.instance_eval {| | block } -> anObject

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

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

instance_of? obj.instance_of?( aClass ) -> true or false

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

instance_variables obj.instance_variables -> anArray

Returns an array of instance variable names for the receiver.

is_a? obj.is_a?( aClass ) -> true or false

Synonym for Object#kind_of? .

kind_of? obj.kind_of?( aClass ) -> true or false
Returns true if aClass is the class of obj, or if aClass is one of the superclasses of obj or modules included in obj.

a = 1
a.instance_of? Numeric » false
a.instance_of? Integer » false
a.instance_of? Fixnum » true
a.instance_of? Comparable » false
a.kind_of? Numeric » true
a.kind_of? Integer » true
a.kind_of? Fixnum » true
a.kind_of? Comparable » true

method obj.method( aSymbol ) -> aMethod

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"

method_missing obj.method_missing( aSymbol [, *args ] ) -> anObject
Invoked by Ruby when obj is sent a message it cannot handle. aSymbol is the symbol for the method called, and args are any arguments that were passed to it. The example below creates a class Roman, which responds to methods with names consisting of roman numerals, returning the corresponding integer values.

class Roman
  def romanToInt(str)
    # ...
  end
  def method_missing(methId)
    str = methId.id2name
    romanToInt(str)
  end
end

r = Roman.new
r.iv » 4
r.xxiii » 23
r.mm » 2000

methods obj.methods -> anArray

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

class Klass
  def kMethod()
  end
end
k = Klass.new
k.methods[0..9] » ["kMethod", "dup", "eql?", "protected_methods", "==", "frozen?", "===", "respond_to?", "class", "kind_of?"]
k.methods.length » 38

nil? obj.nil? -> true or false

All objects except nil return false.

private_methods obj.private_methods -> anArray

Returns a list of private methods accessible within obj. This will include the private methods in obj's ancestors, along with any mixed-in module functions.

protected_methods obj.protected_methods -> anArray

Returns the list of protected methods accessible to obj.

public_methods obj.public_methods -> anArray

Synonym for Object#methods .

respond_to? obj.respond_to?( aSymbol, includePriv=false ) -> true or false

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

send obj.send( aSymbol [, args ]* ) -> anObject

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

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

singleton_methods obj.singleton_methods -> anArray

Returns an array of the names of singleton methods for obj.

class Klass
  def Klass.classMethod
  end
end
k = Klass.new
def k.sm()
end
Klass.singleton_methods » ["classMethod"]
k.singleton_methods » ["sm"]

taint obj.taint -> obj

Marks obj as tainted (see Chapter 20, which begins on page 253).

tainted? obj.tainted? -> true or false

Returns true if the object is tainted.

to_a obj.to_a -> anArray

Returns an array representation of obj. For objects of class Object and others that don't explicitly override the method, the return value is an array containing self.

self.to_a » [main]
"hello".to_a » ["hello"]
Time.new.to_a » [15, 18, 0, 9, 6, 2002, 0, 160, true, "CDT"]

to_s obj.to_s -> aString

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

type obj.type -> aClass

Returns the class of obj.

untaint obj.untaint -> obj

Removes the taint from obj.


Previous < Contents ^
Next >

Extracted from the book "Programming Ruby - The Pragmatic Programmer's Guide"
Copyright © 2001 by Addison Wesley Longman, Inc. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/)).

Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder.

Distribution of the work or derivative of the work in any standard (paper) book form is prohibited unless prior permission is obtained from the copyright holder.