1: /**********************************************************************
    2: 
    3:   object.c -
    4: 
    5:   $Author: akr $
    6:   $Date: 2007-12-24 16:52:39 +0900 (Mon, 24 Dec 2007) $
    7:   created at: Thu Jul 15 12:01:24 JST 1993
    8: 
    9:   Copyright (C) 1993-2007 Yukihiro Matsumoto
   10:   Copyright (C) 2000  Network Applied Communication Laboratory, Inc.
   11:   Copyright (C) 2000  Information-technology Promotion Agency, Japan
   12: 
   13: **********************************************************************/
   14: 
   15: #include "ruby/ruby.h"
   16: #include "ruby/st.h"
   17: #include "ruby/util.h"
   18: #include "debug.h"
   19: #include <stdio.h>
   20: #include <errno.h>
   21: #include <ctype.h>
   22: #include <math.h>
   23: 
   24: VALUE rb_cBasicObject;
   25: VALUE rb_mKernel;
   26: VALUE rb_cObject;
   27: VALUE rb_cModule;
   28: VALUE rb_cClass;
   29: VALUE rb_cData;
   30: 
   31: VALUE rb_cNilClass;
   32: VALUE rb_cTrueClass;
   33: VALUE rb_cFalseClass;
   34: 
   35: static ID id_eq, id_eql, id_match, id_inspect, id_init_copy;
   36: 
   37: /*
   38:  *  call-seq:
   39:  *     obj === other   => true or false
   40:  *  
   41:  *  Case Equality---For class <code>Object</code>, effectively the same
   42:  *  as calling  <code>#==</code>, but typically overridden by descendents
   43:  *  to provide meaningful semantics in <code>case</code> statements.
   44:  */
   45: 
   46: VALUE
   47: rb_equal(VALUE obj1, VALUE obj2)
   48: {
   49:     VALUE result;
   50: 
   51:     if (obj1 == obj2) return Qtrue;
   52:     result = rb_funcall(obj1, id_eq, 1, obj2);
   53:     if (RTEST(result)) return Qtrue;
   54:     return Qfalse;
   55: }
   56: 
   57: int
   58: rb_eql(VALUE obj1, VALUE obj2)
   59: {
   60:     return RTEST(rb_funcall(obj1, id_eql, 1, obj2));
   61: }
   62: 
   63: /*
   64:  *  call-seq:
   65:  *     obj == other        => true or false
   66:  *     obj.equal?(other)   => true or false
   67:  *     obj.eql?(other)     => true or false
   68:  *  
   69:  *  Equality---At the <code>Object</code> level, <code>==</code> returns
   70:  *  <code>true</code> only if <i>obj</i> and <i>other</i> are the
   71:  *  same object. Typically, this method is overridden in descendent
   72:  *  classes to provide class-specific meaning.
   73:  *
   74:  *  Unlike <code>==</code>, the <code>equal?</code> method should never be
   75:  *  overridden by subclasses: it is used to determine object identity
   76:  *  (that is, <code>a.equal?(b)</code> iff <code>a</code> is the same
   77:  *  object as <code>b</code>).
   78:  *
   79:  *  The <code>eql?</code> method returns <code>true</code> if
   80:  *  <i>obj</i> and <i>anObject</i> have the same value. Used by
   81:  *  <code>Hash</code> to test members for equality.  For objects of
   82:  *  class <code>Object</code>, <code>eql?</code> is synonymous with
   83:  *  <code>==</code>. Subclasses normally continue this tradition, but
   84:  *  there are exceptions. <code>Numeric</code> types, for example,
   85:  *  perform type conversion across <code>==</code>, but not across
   86:  *  <code>eql?</code>, so:
   87:  *     
   88:  *     1 == 1.0     #=> true
   89:  *     1.eql? 1.0   #=> false
   90:  */
   91: 
   92: VALUE
   93: rb_obj_equal(VALUE obj1, VALUE obj2)
   94: {
   95:     if (obj1 == obj2) return Qtrue;
   96:     return Qfalse;
   97: }
   98: 
   99: /*
  100:  *  call-seq:
  101:  *     !obj    => true or false
  102:  *
  103:  *  Boolean negate.
  104:  */
  105: 
  106: VALUE
  107: rb_obj_not(VALUE obj)
  108: {
  109:     return RTEST(obj) ? Qfalse : Qtrue;
  110: }
  111: 
  112: /*
  113:  *  call-seq:
  114:  *     obj != other        => true or false
  115:  *
  116:  *  Returns true if two objects are not-equal, otherwise false.
  117:  */
  118: 
  119: VALUE
  120: rb_obj_not_equal(VALUE obj1, VALUE obj2)
  121: {
  122:     VALUE result = rb_funcall(obj1, id_eq, 1, obj2);
  123:     return RTEST(result) ? Qfalse : Qtrue;
  124: }
  125: 
  126: VALUE
  127: rb_class_real(VALUE cl)
  128: {
  129:     if (cl == 0)
  130:         return 0;
  131:     while ((RBASIC(cl)->flags & FL_SINGLETON) || BUILTIN_TYPE(cl) == T_ICLASS) {
  132:         cl = RCLASS_SUPER(cl);
  133:     }
  134:     return cl;
  135: }
  136: 
  137: /*
  138:  *  call-seq:
  139:  *     obj.class    => class
  140:  *  
  141:  *  Returns the class of <i>obj</i>, now preferred over
  142:  *  <code>Object#type</code>, as an object's type in Ruby is only
  143:  *  loosely tied to that object's class. This method must always be
  144:  *  called with an explicit receiver, as <code>class</code> is also a
  145:  *  reserved word in Ruby.
  146:  *     
  147:  *     1.class      #=> Fixnum
  148:  *     self.class   #=> Object
  149:  */
  150: 
  151: VALUE
  152: rb_obj_class(VALUE obj)
  153: {
  154:     return rb_class_real(CLASS_OF(obj));
  155: }
  156: 
  157: static void
  158: init_copy(VALUE dest, VALUE obj)
  159: {
  160:     if (OBJ_FROZEN(dest)) {
  161:         rb_raise(rb_eTypeError, "[bug] frozen object (%s) allocated", rb_obj_classname(dest));
  162:     }
  163:     RBASIC(dest)->flags &= ~(T_MASK|FL_EXIVAR);
  164:     RBASIC(dest)->flags |= RBASIC(obj)->flags & (T_MASK|FL_EXIVAR|FL_TAINT);
  165:     rb_copy_generic_ivar(dest, obj);
  166:     rb_gc_copy_finalizer(dest, obj);
  167:     switch (TYPE(obj)) {
  168:       case T_OBJECT:
  169:         if (!(RBASIC(dest)->flags & ROBJECT_EMBED) && ROBJECT_PTR(dest)) {
  170:             xfree(ROBJECT_PTR(dest));
  171:             ROBJECT(dest)->as.heap.ptr = 0;
  172:             ROBJECT(dest)->as.heap.len = 0;
  173:         }
  174:         if (RBASIC(obj)->flags & ROBJECT_EMBED) {
  175:             MEMCPY(ROBJECT(dest)->as.ary, ROBJECT(obj)->as.ary, VALUE, ROBJECT_EMBED_LEN_MAX);
  176:             RBASIC(dest)->flags |= ROBJECT_EMBED;
  177:         }
  178:         else {
  179:             long len = ROBJECT(obj)->as.heap.len;
  180:             VALUE *ptr = ALLOC_N(VALUE, len);
  181:             MEMCPY(ptr, ROBJECT(obj)->as.heap.ptr, VALUE, len);
  182:             ROBJECT(dest)->as.heap.ptr = ptr;
  183:             ROBJECT(dest)->as.heap.len = len;
  184:             RBASIC(dest)->flags &= ~ROBJECT_EMBED;
  185:         }
  186:         break;
  187:       case T_CLASS:
  188:       case T_MODULE:
  189:         if (RCLASS_IV_TBL(dest)) {
  190:             st_free_table(RCLASS_IV_TBL(dest));
  191:             RCLASS_IV_TBL(dest) = 0;
  192:         }
  193:         if (RCLASS_IV_TBL(obj)) {
  194:             RCLASS_IV_TBL(dest) = st_copy(RCLASS_IV_TBL(obj));
  195:         }
  196:         break;
  197:     }
  198:     rb_funcall(dest, id_init_copy, 1, obj);
  199: }
  200: 
  201: /*
  202:  *  call-seq:
  203:  *     obj.clone -> an_object
  204:  *  
  205:  *  Produces a shallow copy of <i>obj</i>---the instance variables of
  206:  *  <i>obj</i> are copied, but not the objects they reference. Copies
  207:  *  the frozen and tainted state of <i>obj</i>. See also the discussion
  208:  *  under <code>Object#dup</code>.
  209:  *     
  210:  *     class Klass
  211:  *        attr_accessor :str
  212:  *     end
  213:  *     s1 = Klass.new      #=> #<Klass:0x401b3a38>
  214:  *     s1.str = "Hello"    #=> "Hello"
  215:  *     s2 = s1.clone       #=> #<Klass:0x401b3998 @str="Hello">
  216:  *     s2.str[1,4] = "i"   #=> "i"
  217:  *     s1.inspect          #=> "#<Klass:0x401b3a38 @str=\"Hi\">"
  218:  *     s2.inspect          #=> "#<Klass:0x401b3998 @str=\"Hi\">"
  219:  *
  220:  *  This method may have class-specific behavior.  If so, that
  221:  *  behavior will be documented under the #+initialize_copy+ method of
  222:  *  the class.
  223:  */
  224: 
  225: VALUE
  226: rb_obj_clone(VALUE obj)
  227: {
  228:     VALUE clone;
  229: 
  230:     if (rb_special_const_p(obj)) {
  231:         rb_raise(rb_eTypeError, "can't clone %s", rb_obj_classname(obj));
  232:     }
  233:     clone = rb_obj_alloc(rb_obj_class(obj));
  234:     RBASIC(clone)->klass = rb_singleton_class_clone(obj);
  235:     RBASIC(clone)->flags = (RBASIC(obj)->flags | FL_TEST(clone, FL_TAINT)) & ~(FL_FREEZE|FL_FINALIZE);
  236:     init_copy(clone, obj);
  237:     RBASIC(clone)->flags |= RBASIC(obj)->flags & FL_FREEZE;
  238: 
  239:     return clone;
  240: }
  241: 
  242: /*
  243:  *  call-seq:
  244:  *     obj.dup -> an_object
  245:  *  
  246:  *  Produces a shallow copy of <i>obj</i>---the instance variables of
  247:  *  <i>obj</i> are copied, but not the objects they reference.
  248:  *  <code>dup</code> copies the tainted state of <i>obj</i>. See also
  249:  *  the discussion under <code>Object#clone</code>. In general,
  250:  *  <code>clone</code> and <code>dup</code> may have different semantics
  251:  *  in descendent classes. While <code>clone</code> is used to duplicate
  252:  *  an object, including its internal state, <code>dup</code> typically
  253:  *  uses the class of the descendent object to create the new instance.
  254:  *
  255:  *  This method may have class-specific behavior.  If so, that
  256:  *  behavior will be documented under the #+initialize_copy+ method of
  257:  *  the class.
  258:  */
  259: 
  260: VALUE
  261: rb_obj_dup(VALUE obj)
  262: {
  263:     VALUE dup;
  264: 
  265:     if (rb_special_const_p(obj)) {
  266:         rb_raise(rb_eTypeError, "can't dup %s", rb_obj_classname(obj));
  267:     }
  268:     dup = rb_obj_alloc(rb_obj_class(obj));
  269:     init_copy(dup, obj);
  270: 
  271:     return dup;
  272: }
  273: 
  274: /* :nodoc: */
  275: VALUE
  276: rb_obj_init_copy(VALUE obj, VALUE orig)
  277: {
  278:     if (obj == orig) return obj;
  279:     rb_check_frozen(obj);
  280:     if (TYPE(obj) != TYPE(orig) || rb_obj_class(obj) != rb_obj_class(orig)) {
  281:         rb_raise(rb_eTypeError, "initialize_copy should take same class object");
  282:     }
  283:     return obj;
  284: }
  285: 
  286: /*
  287:  *  call-seq:
  288:  *     obj.to_s    => string
  289:  *  
  290:  *  Returns a string representing <i>obj</i>. The default
  291:  *  <code>to_s</code> prints the object's class and an encoding of the
  292:  *  object id. As a special case, the top-level object that is the
  293:  *  initial execution context of Ruby programs returns ``main.''
  294:  */
  295: 
  296: VALUE
  297: rb_any_to_s(VALUE obj)
  298: {
  299:     char *cname = rb_obj_classname(obj);
  300:     VALUE str;
  301: 
  302:     str = rb_sprintf("#<%s:%p>", cname, (void*)obj);
  303:     if (OBJ_TAINTED(obj)) OBJ_TAINT(str);
  304: 
  305:     return str;
  306: }
  307: 
  308: VALUE
  309: rb_inspect(VALUE obj)
  310: {
  311:     return rb_obj_as_string(rb_funcall(obj, id_inspect, 0, 0));
  312: }
  313: 
  314: static int
  315: inspect_i(ID id, VALUE value, VALUE str)
  316: {
  317:     VALUE str2;
  318:     const char *ivname;
  319: 
  320:     /* need not to show internal data */
  321:     if (CLASS_OF(value) == 0) return ST_CONTINUE;
  322:     if (!rb_is_instance_id(id)) return ST_CONTINUE;
  323:     if (RSTRING_PTR(str)[0] == '-') { /* first element */
  324:         RSTRING_PTR(str)[0] = '#';
  325:         rb_str_cat2(str, " ");
  326:     }
  327:     else {
  328:         rb_str_cat2(str, ", ");
  329:     }
  330:     ivname = rb_id2name(id);
  331:     rb_str_cat2(str, ivname);
  332:     rb_str_cat2(str, "=");
  333:     str2 = rb_inspect(value);
  334:     rb_str_append(str, str2);
  335:     OBJ_INFECT(str, str2);
  336: 
  337:     return ST_CONTINUE;
  338: }
  339: 
  340: static VALUE
  341: inspect_obj(VALUE obj, VALUE str, int recur)
  342: {
  343:     if (recur) {
  344:         rb_str_cat2(str, " ...");
  345:     }
  346:     else {
  347:         rb_ivar_foreach(obj, inspect_i, str);
  348:     }
  349:     rb_str_cat2(str, ">");
  350:     RSTRING_PTR(str)[0] = '#';
  351:     OBJ_INFECT(str, obj);
  352: 
  353:     return str;
  354: }
  355: 
  356: /*
  357:  *  call-seq:
  358:  *     obj.inspect   => string
  359:  *  
  360:  *  Returns a string containing a human-readable representation of
  361:  *  <i>obj</i>. If not overridden, uses the <code>to_s</code> method to
  362:  *  generate the string.
  363:  *     
  364:  *     [ 1, 2, 3..4, 'five' ].inspect   #=> "[1, 2, 3..4, \"five\"]"
  365:  *     Time.new.inspect                 #=> "Wed Apr 09 08:54:39 CDT 2003"
  366:  */
  367: 
  368: 
  369: static VALUE
  370: rb_obj_inspect(VALUE obj)
  371: {
  372: 
  373:     if (TYPE(obj) == T_OBJECT) {
  374:         int has_ivar = 0;
  375:         VALUE *ptr = ROBJECT_PTR(obj);
  376:         long len = ROBJECT_LEN(obj);
  377:         long i;
  378: 
  379:         for (i = 0; i < len; i++) {
  380:             if (ptr[i] != Qundef) {
  381:                 has_ivar = 1;
  382:                 break;
  383:             }
  384:         }
  385: 
  386:         if (has_ivar) {
  387:             VALUE str;
  388:             char *c;
  389: 
  390:             c = rb_obj_classname(obj);
  391:             str = rb_sprintf("-<%s:%p", c, (void*)obj);
  392:             return rb_exec_recursive(inspect_obj, obj, str);
  393:         }
  394:     }
  395:     return rb_funcall(obj, rb_intern("to_s"), 0, 0);
  396: }
  397: 
  398: 
  399: /*
  400:  *  call-seq:
  401:  *     obj.instance_of?(class)    => true or false
  402:  *  
  403:  *  Returns <code>true</code> if <i>obj</i> is an instance of the given
  404:  *  class. See also <code>Object#kind_of?</code>.
  405:  */
  406: 
  407: VALUE
  408: rb_obj_is_instance_of(VALUE obj, VALUE c)
  409: {
  410:     switch (TYPE(c)) {
  411:       case T_MODULE:
  412:       case T_CLASS:
  413:       case T_ICLASS:
  414:         break;
  415:       default:
  416:         rb_raise(rb_eTypeError, "class or module required");
  417:     }
  418: 
  419:     if (rb_obj_class(obj) == c) return Qtrue;
  420:     return Qfalse;
  421: }
  422: 
  423: 
  424: /*
  425:  *  call-seq:
  426:  *     obj.is_a?(class)       => true or false
  427:  *     obj.kind_of?(class)    => true or false
  428:  *  
  429:  *  Returns <code>true</code> if <i>class</i> is the class of
  430:  *  <i>obj</i>, or if <i>class</i> is one of the superclasses of
  431:  *  <i>obj</i> or modules included in <i>obj</i>.
  432:  *     
  433:  *     module M;    end
  434:  *     class A
  435:  *       include M
  436:  *     end
  437:  *     class B < A; end
  438:  *     class C < B; end
  439:  *     b = B.new
  440:  *     b.instance_of? A   #=> false
  441:  *     b.instance_of? B   #=> true
  442:  *     b.instance_of? C   #=> false
  443:  *     b.instance_of? M   #=> false
  444:  *     b.kind_of? A       #=> true
  445:  *     b.kind_of? B       #=> true
  446:  *     b.kind_of? C       #=> false
  447:  *     b.kind_of? M       #=> true
  448:  */
  449: 
  450: VALUE
  451: rb_obj_is_kind_of(VALUE obj, VALUE c)
  452: {
  453:     VALUE cl = CLASS_OF(obj);
  454: 
  455:     switch (TYPE(c)) {
  456:       case T_MODULE:
  457:       case T_CLASS:
  458:       case T_ICLASS:
  459:         break;
  460: 
  461:       default:
  462:         rb_raise(rb_eTypeError, "class or module required");
  463:     }
  464: 
  465:     while (cl) {
  466:         if (cl == c || RCLASS_M_TBL(cl) == RCLASS_M_TBL(c))
  467:             return Qtrue;
  468:         cl = RCLASS_SUPER(cl);
  469:     }
  470:     return Qfalse;
  471: }
  472: 
  473: 
  474: /*
  475:  *  call-seq:
  476:  *     obj.tap{|x|...}    => obj
  477:  *  
  478:  *  Yields <code>x</code> to the block, and then returns <code>x</code>.
  479:  *  The primary purpose of this method is to "tap into" a method chain,
  480:  *  in order to perform operations on intermediate results within the chain.
  481:  *
  482:  *      (1..10)                .tap {|x| puts "original: #{x.inspect}"}
  483:  *        .to_a                .tap {|x| puts "array: #{x.inspect}"}
  484:  *        .select {|x| x%2==0} .tap {|x| puts "evens: #{x.inspect}"}
  485:  *        .map { |x| x*x }     .tap {|x| puts "squares: #{x.inspect}"}
  486:  *
  487:  */
  488: 
  489: VALUE
  490: rb_obj_tap(VALUE obj)
  491: {
  492:     rb_yield(obj);
  493:     return obj;
  494: }
  495: 
  496: 
  497: /*
  498:  * Document-method: inherited
  499:  *
  500:  * call-seq:
  501:  *    inherited(subclass)
  502:  *
  503:  * Callback invoked whenever a subclass of the current class is created.
  504:  *
  505:  * Example:
  506:  *
  507:  *    class Foo
  508:  *       def self.inherited(subclass)
  509:  *          puts "New subclass: #{subclass}"
  510:  *       end
  511:  *    end
  512:  *
  513:  *    class Bar < Foo
  514:  *    end
  515:  *
  516:  *    class Baz < Bar
  517:  *    end
  518:  *
  519:  * produces:
  520:  *
  521:  *    New subclass: Bar
  522:  *    New subclass: Baz
  523:  */
  524: 
  525: /*
  526:  * Document-method: singleton_method_added
  527:  *
  528:  *  call-seq:
  529:  *     singleton_method_added(symbol)
  530:  *  
  531:  *  Invoked as a callback whenever a singleton method is added to the
  532:  *  receiver.
  533:  *     
  534:  *     module Chatty
  535:  *       def Chatty.singleton_method_added(id)
  536:  *         puts "Adding #{id.id2name}"
  537:  *       end
  538:  *       def self.one()     end
  539:  *       def two()          end
  540:  *       def Chatty.three() end
  541:  *     end
  542:  *     
  543:  *  <em>produces:</em>
  544:  *     
  545:  *     Adding singleton_method_added
  546:  *     Adding one
  547:  *     Adding three
  548:  *     
  549:  */
  550: 
  551: /*
  552:  * Document-method: singleton_method_removed
  553:  *
  554:  *  call-seq:
  555:  *     singleton_method_removed(symbol)
  556:  *  
  557:  *  Invoked as a callback whenever a singleton method is removed from
  558:  *  the receiver.
  559:  *     
  560:  *     module Chatty
  561:  *       def Chatty.singleton_method_removed(id)
  562:  *         puts "Removing #{id.id2name}"
  563:  *       end
  564:  *       def self.one()     end
  565:  *       def two()          end
  566:  *       def Chatty.three() end
  567:  *       class <<self
  568:  *         remove_method :three
  569:  *         remove_method :one
  570:  *       end
  571:  *     end
  572:  *     
  573:  *  <em>produces:</em>
  574:  *     
  575:  *     Removing three
  576:  *     Removing one
  577:  */
  578: 
  579: /*
  580:  * Document-method: singleton_method_undefined
  581:  *
  582:  *  call-seq:
  583:  *     singleton_method_undefined(symbol)
  584:  *  
  585:  *  Invoked as a callback whenever a singleton method is undefined in
  586:  *  the receiver.
  587:  *     
  588:  *     module Chatty
  589:  *       def Chatty.singleton_method_undefined(id)
  590:  *         puts "Undefining #{id.id2name}"
  591:  *       end
  592:  *       def Chatty.one()   end
  593:  *       class << self
  594:  *          undef_method(:one)
  595:  *       end
  596:  *     end
  597:  *     
  598:  *  <em>produces:</em>
  599:  *     
  600:  *     Undefining one
  601:  */
  602: 
  603: 
  604: /*
  605:  * Document-method: included
  606:  *
  607:  * call-seq:
  608:  *    included( othermod )
  609:  *
  610:  * Callback invoked whenever the receiver is included in another
  611:  * module or class. This should be used in preference to
  612:  * <tt>Module.append_features</tt> if your code wants to perform some
  613:  * action when a module is included in another.
  614:  *
  615:  *        module A
  616:  *          def A.included(mod)
  617:  *            puts "#{self} included in #{mod}"
  618:  *          end
  619:  *        end
  620:  *        module Enumerable
  621:  *          include A
  622:  *        end
  623:  */
  624: 
  625: 
  626: /*
  627:  * Not documented
  628:  */
  629: 
  630: static VALUE
  631: rb_obj_dummy(void)
  632: {
  633:     return Qnil;
  634: }
  635: 
  636: /*
  637:  *  call-seq:
  638:  *     obj.tainted?    => true or false
  639:  *  
  640:  *  Returns <code>true</code> if the object is tainted.
  641:  */
  642: 
  643: VALUE
  644: rb_obj_tainted(VALUE obj)
  645: {
  646:     if (OBJ_TAINTED(obj))
  647:         return Qtrue;
  648:     return Qfalse;
  649: }
  650: 
  651: /*
  652:  *  call-seq:
  653:  *     obj.taint -> obj
  654:  *  
  655:  *  Marks <i>obj</i> as tainted---if the <code>$SAFE</code> level is
  656:  *  set appropriately, many method calls which might alter the running
  657:  *  programs environment will refuse to accept tainted strings.
  658:  */
  659: 
  660: VALUE
  661: rb_obj_taint(VALUE obj)
  662: {
  663:     rb_secure(4);
  664:     if (!OBJ_TAINTED(obj)) {
  665:         if (OBJ_FROZEN(obj)) {
  666:             rb_error_frozen("object");
  667:         }
  668:         OBJ_TAINT(obj);
  669:     }
  670:     return obj;
  671: }