Project

General

Profile

Bug #10526 ยป doc_object_c.patch

stomar (Marcus Stollsteimer), 11/19/2014 09:28 PM

View differences:

object.c (Arbeitskopie)
155 155
 * capacity of a Fixnum will be truncated before being used.
156 156
 *
157 157
 * The hash value for an object may not be identical across invocations or
158
 * implementations of ruby.  If you need a stable identifier across ruby
158
 * implementations of Ruby.  If you need a stable identifier across Ruby
159 159
 * invocations and implementations you will need to generate one with a custom
160 160
 * method.
161 161
 */
......
234 234
 *     obj.singleton_class    -> class
235 235
 *
236 236
 *  Returns the singleton class of <i>obj</i>.  This method creates
237
 *  a new singleton class if <i>obj</i> does not have it.
237
 *  a new singleton class if <i>obj</i> does not have one.
238 238
 *
239 239
 *  If <i>obj</i> is <code>nil</code>, <code>true</code>, or
240 240
 *  <code>false</code>, it returns NilClass, TrueClass, or FalseClass,
......
302 302
 *     obj.clone -> an_object
303 303
 *
304 304
 *  Produces a shallow copy of <i>obj</i>---the instance variables of
305
 *  <i>obj</i> are copied, but not the objects they reference. Copies
306
 *  the frozen and tainted state of <i>obj</i>. See also the discussion
307
 *  under <code>Object#dup</code>.
305
 *  <i>obj</i> are copied, but not the objects they reference.
306
 *  <code>clone</code> copies the frozen and tainted state of <i>obj</i>.
307
 *  See also the discussion under <code>Object#dup</code>.
308 308
 *
309 309
 *     class Klass
310 310
 *        attr_accessor :str
......
352 352
 *     obj.dup -> an_object
353 353
 *
354 354
 *  Produces a shallow copy of <i>obj</i>---the instance variables of
355
 *  <i>obj</i> are copied, but not the objects they reference. <code>dup</code>
356
 *  copies the tainted state of <i>obj</i>.
355
 *  <i>obj</i> are copied, but not the objects they reference.
356
 *  <code>dup</code> copies the tainted state of <i>obj</i>.
357 357
 *
358 358
 *  This method may have class-specific behavior.  If so, that
359 359
 *  behavior will be documented under the #+initialize_copy+ method of
......
367 367
 *  typically uses the class of the descendant object to create the new
368 368
 *  instance.
369 369
 *
370
 *  When using #dup any modules that the object has been extended with will not
370
 *  When using #dup, any modules that the object has been extended with will not
371 371
 *  be copied.
372 372
 *
373 373
 *	class Klass
......
450 450
 *  Returns a string representing <i>obj</i>. The default
451 451
 *  <code>to_s</code> prints the object's class and an encoding of the
452 452
 *  object id. As a special case, the top-level object that is the
453
 *  initial execution context of Ruby programs returns ``main.''
453
 *  initial execution context of Ruby programs returns ``main''.
454 454
 */
455 455

  
456 456
VALUE
......
467 467

  
468 468
/*
469 469
 * If the default external encoding is ASCII compatible, the encoding of
470
 * inspected result must be compatible with it.
470
 * the inspected result must be compatible with it.
471 471
 * If the default external encoding is ASCII incompatible,
472 472
 * the result must be ASCII only.
473 473
 */
......
536 536
 *     obj.inspect   -> string
537 537
 *
538 538
 * Returns a string containing a human-readable representation of <i>obj</i>.
539
 * By default, show the class name and the list of the instance variables and
539
 * The default <code>inspect</code> shows the object's class name,
540
 * an encoding of the object id, and a list of the instance variables and
540 541
 * their values (by calling #inspect on each of them).
541
 * User defined classes should override this method to make better
542
 * User defined classes should override this method to provide a better
542 543
 * representation of <i>obj</i>.  When overriding this method, it should
543 544
 * return a string whose encoding is compatible with the default external
544 545
 * encoding.
......
556 557
 *       end
557 558
 *     end
558 559
 *     Bar.new.inspect                  #=> "#<Bar:0x0300c868 @bar=1>"
559
 *
560
 *     class Baz
561
 *       def to_s
562
 *         "baz"
563
 *       end
564
 *     end
565
 *     Baz.new.inspect                  #=> "#<Baz:0x0300c868>"
566 560
 */
567 561

  
568 562
static VALUE
......
683 677

  
684 678
/*
685 679
 *  call-seq:
686
 *     obj.tap{|x|...}    -> obj
680
 *     obj.tap{|obj| ... }    -> obj
687 681
 *
688
 *  Yields <code>x</code> to the block, and then returns <code>x</code>.
682
 *  Yields self to the block, and then returns self.
689 683
 *  The primary purpose of this method is to "tap into" a method chain,
690 684
 *  in order to perform operations on intermediate results within the chain.
691 685
 *
692
 *	(1..10)                .tap {|x| puts "original: #{x.inspect}"}
693
 *	  .to_a                .tap {|x| puts "array: #{x.inspect}"}
694
 *	  .select {|x| x%2==0} .tap {|x| puts "evens: #{x.inspect}"}
695
 *	  .map { |x| x*x }     .tap {|x| puts "squares: #{x.inspect}"}
686
 *	(1..10)                 .tap {|x| puts "original: #{x.inspect}" }
687
 *	  .to_a                 .tap {|x| puts "array: #{x.inspect}" }
688
 *	  .select {|x| x%2==0 } .tap {|x| puts "evens: #{x.inspect}" }
689
 *	  .map {|x| x*x }       .tap {|x| puts "squares: #{x.inspect}" }
696 690
 *
697 691
 */
698 692

  
......
726 720
 *    class Baz < Bar
727 721
 *    end
728 722
 *
729
 * produces:
723
 * <em>produces:</em>
730 724
 *
731 725
 *    New subclass: Bar
732 726
 *    New subclass: Baz
......
748 742
 *     def some_instance_method() end
749 743
 *   end
750 744
 *
751
 * produces:
745
 * <em>produces:</em>
752 746
 *
753 747
 *   Adding :some_instance_method
754 748
 *
......
774 768
 *     remove_method :some_instance_method
775 769
 *   end
776 770
 *
777
 * produces:
771
 * <em>produces:</em>
778 772
 *
779 773
 *   Removing :some_instance_method
780 774
 *
......
962 956
 *
963 957
 *  Objects that are marked as tainted will be restricted from various built-in
964 958
 *  methods. This is to prevent insecure data, such as command-line arguments
965
 *  or strings read from Kernel#gets, from inadvertently compromising the users
959
 *  or strings read from Kernel#gets, from inadvertently compromising the user's
966 960
 *  system.
967 961
 *
968
 *  To check whether an object is tainted, use #tainted?
962
 *  To check whether an object is tainted, use #tainted?.
969 963
 *
970 964
 *  You should only untaint a tainted object if your code has inspected it and
971
 *  determined that it is safe. To do so use #untaint
965
 *  determined that it is safe. To do so use #untaint.
972 966
 *
973 967
 *  In $SAFE level 3, all newly created objects are tainted and you can't untaint
974 968
 *  objects.
......
1247 1241
 *  call-seq:
1248 1242
 *     true | obj   -> true
1249 1243
 *
1250
 *  Or---Returns <code>true</code>. As <i>anObject</i> is an argument to
1244
 *  Or---Returns <code>true</code>. As <i>obj</i> is an argument to
1251 1245
 *  a method call, it is always evaluated; there is no short-circuit
1252 1246
 *  evaluation in this case.
1253 1247
 *
......
1371 1365

  
1372 1366
/*
1373 1367
 * call-seq:
1374
 *   nil.nil?               -> true
1375
 *   <anything_else>.nil?   -> false
1368
 *   obj.nil?               -> true or false
1376 1369
 *
1377 1370
 * Only the object <i>nil</i> responds <code>true</code> to <code>nil?</code>.
1371
 *
1372
 *    Object.new.nil?   #=> false
1373
 *    nil.nil?          #=> true
1378 1374
 */
1379 1375

  
1380 1376

  
......
1451 1447
 *  Instance methods appear as methods in a class when the module is
1452 1448
 *  included, module methods do not. Conversely, module methods may be
1453 1449
 *  called without creating an encapsulating object, while instance
1454
 *  methods may not. (See <code>Module#module_function</code>)
1450
 *  methods may not. (See <code>Module#module_function</code>.)
1455 1451
 *
1456 1452
 *  In the descriptions that follow, the parameter <i>sym</i> refers
1457 1453
 *  to a symbol, which is either a quoted string or a
......
1474 1470
 * call-seq:
1475 1471
 *   mod.to_s   -> string
1476 1472
 *
1477
 * Return a string representing this module or class. For basic
1473
 * Returns a string representing this module or class. For basic
1478 1474
 * classes and modules, this is the name. For singletons, we
1479 1475
 * show information on the thing we're attached to as well.
1480 1476
 */
......
1534 1530
 *  call-seq:
1535 1531
 *     mod === obj    -> true or false
1536 1532
 *
1537
 *  Case Equality---Returns <code>true</code> if <i>anObject</i> is an
1533
 *  Case Equality---Returns <code>true</code> if <i>obj</i> is an
1538 1534
 *  instance of <i>mod</i> or one of <i>mod</i>'s descendants. Of
1539 1535
 *  limited use for modules, but can be used in <code>case</code>
1540 1536
 *  statements to classify objects by class.
......
1554 1550
 * is the same as <i>other</i>. Returns
1555 1551
 * <code>nil</code> if there's no relationship between the two.
1556 1552
 * (Think of the relationship in terms of the class definition:
1557
 * "class A<B" implies "A<B").
1553
 * "class A<B" implies "A<B".)
1558 1554
 *
1559 1555
 */
1560 1556

  
......
1585 1581
 * Returns true if <i>mod</i> is a subclass of <i>other</i>. Returns
1586 1582
 * <code>nil</code> if there's no relationship between the two.
1587 1583
 * (Think of the relationship in terms of the class definition:
1588
 * "class A<B" implies "A<B").
1584
 * "class A<B" implies "A<B".)
1589 1585
 *
1590 1586
 */
1591 1587

  
......
1605 1601
 * two modules are the same. Returns
1606 1602
 * <code>nil</code> if there's no relationship between the two.
1607 1603
 * (Think of the relationship in terms of the class definition:
1608
 * "class A<B" implies "B>A").
1604
 * "class A<B" implies "B>A".)
1609 1605
 *
1610 1606
 */
1611 1607

  
......
1626 1622
 * Returns true if <i>mod</i> is an ancestor of <i>other</i>. Returns
1627 1623
 * <code>nil</code> if there's no relationship between the two.
1628 1624
 * (Think of the relationship in terms of the class definition:
1629
 * "class A<B" implies "B>A").
1625
 * "class A<B" implies "B>A".)
1630 1626
 *
1631 1627
 */
1632 1628

  
......
1884 1880
 *     class Bar < Foo; end
1885 1881
 *     Bar.superclass           #=> Foo
1886 1882
 *
1887
 *  returns nil when the given class hasn't a parent class:
1883
 *  Returns nil when the given class does not have a parent class:
1888 1884
 *
1889 1885
 *     BasicObject.superclass   #=> nil
1890 1886
 *
......
2059 2055
 *     mod.const_get(sym, inherit=true)    -> obj
2060 2056
 *     mod.const_get(str, inherit=true)    -> obj
2061 2057
 *
2062
 *  Checks for a constant with the given name in <i>mod</i>
2058
 *  Checks for a constant with the given name in <i>mod</i>.
2063 2059
 *  If +inherit+ is set, the lookup will also search
2064
 *  the ancestors (and +Object+ if <i>mod</i> is a +Module+.)
2060
 *  the ancestors (and +Object+ if <i>mod</i> is a +Module+).
2065 2061
 *
2066 2062
 *  The value of the constant is returned if a definition is found,
2067 2063
 *  otherwise a +NameError+ is raised.
......
2087 2083
 *     Object.const_get 'Foo::Baz::VAL'         # => 10
2088 2084
 *     Object.const_get 'Foo::Baz::VAL', false  # => NameError
2089 2085
 *
2090
 *  If neither +sym+ nor +str+ is not a valid constant name a NameError will be
2086
 *  If the argument is not a valid constant name a +NameError+ will be
2091 2087
 *  raised with a warning "wrong constant name".
2092 2088
 *
2093 2089
 *	Object.const_get 'foobar' #=> NameError: wrong constant name foobar
......
2199 2195
 *     Math.const_set("HIGH_SCHOOL_PI", 22.0/7.0)   #=> 3.14285714285714
2200 2196
 *     Math::HIGH_SCHOOL_PI - Math::PI              #=> 0.00126448926734968
2201 2197
 *
2202
 *  If neither +sym+ nor +str+ is not a valid constant name a NameError will be
2198
 *  If +sym+ or +str+ is not a valid constant name a +NameError+ will be
2203 2199
 *  raised with a warning "wrong constant name".
2204 2200
 *
2205 2201
 *	Object.const_set('foobar', 42) #=> NameError: wrong constant name foobar
......
2248 2244
 *
2249 2245
 *  In this case, the same logic for autoloading applies.
2250 2246
 *
2251
 *  If the argument is not a valid constant name +NameError+ is raised with the
2247
 *  If the argument is not a valid constant name a +NameError+ is raised with the
2252 2248
 *  message "wrong constant name _name_":
2253 2249
 *
2254 2250
 *    Hash.const_defined? 'foobar'   #=> NameError: wrong constant name foobar
......
2401 2397
 *     obj.instance_variable_set(symbol, obj)    -> obj
2402 2398
 *     obj.instance_variable_set(string, obj)    -> obj
2403 2399
 *
2404
 *  Sets the instance variable names by <i>symbol</i> to
2405
 *  <i>object</i>, thereby frustrating the efforts of the class's
2400
 *  Sets the instance variable named by <i>symbol</i> to the given
2401
 *  object, thereby frustrating the efforts of the class's
2406 2402
 *  author to attempt to provide proper encapsulation. The variable
2407
 *  did not have to exist prior to this call.
2403
 *  does not have to exist prior to this call.
2408 2404
 *  If the instance variable name is passed as a string, that string
2409 2405
 *  is converted to a symbol.
2410 2406
 *
......
2474 2470
 *
2475 2471
 *  Returns the value of the given class variable (or throws a
2476 2472
 *  <code>NameError</code> exception). The <code>@@</code> part of the
2477
 *  variable name should be included for regular class variables
2473
 *  variable name should be included for regular class variables.
2478 2474
 *  String arguments are converted to symbols.
2479 2475
 *
2480 2476
 *     class Fred
......
2510 2506
 *     obj.class_variable_set(symbol, obj)    -> obj
2511 2507
 *     obj.class_variable_set(string, obj)    -> obj
2512 2508
 *
2513
 *  Sets the class variable names by <i>symbol</i> to
2514
 *  <i>object</i>.
2509
 *  Sets the class variable named by <i>symbol</i> to the given
2510
 *  object.
2515 2511
 *  If the class variable name is passed as a string, that string
2516 2512
 *  is converted to a symbol.
2517 2513
 *
......
2777 2773

  
2778 2774
/*
2779 2775
 *  call-seq:
2780
 *     Integer(arg,base=0)    -> integer
2776
 *     Integer(arg, base=0)    -> integer
2781 2777
 *
2782 2778
 *  Converts <i>arg</i> to a <code>Fixnum</code> or <code>Bignum</code>.
2783 2779
 *  Numeric types are converted directly (with floating point numbers
2784
 *  being truncated).    <i>base</i> (0, or between 2 and 36) is a base for
2780
 *  being truncated).  <i>base</i> (0, or between 2 and 36) is a base for
2785 2781
 *  integer string representation.  If <i>arg</i> is a <code>String</code>,
2786
 *  when <i>base</i> is omitted or equals to zero, radix indicators
2782
 *  when <i>base</i> is omitted or equals zero, radix indicators
2787 2783
 *  (<code>0</code>, <code>0b</code>, and <code>0x</code>) are honored.
2788 2784
 *  In any case, strings should be strictly conformed to numeric
2789 2785
 *  representation. This behavior is different from that of
2790
 *  <code>String#to_i</code>.  Non string values will be converted using
2791
 *  <code>to_int</code>, and <code>to_i</code>. Passing <code>nil</code>
2786
 *  <code>String#to_i</code>.  Non string values will be converted by first
2787
 *  trying <code>to_int</code>, then <code>to_i</code>. Passing <code>nil</code>
2792 2788
 *  raises a TypeError.
2793 2789
 *
2794 2790
 *     Integer(123.999)    #=> 123
......
2962 2958
 *     Float(arg)    -> float
2963 2959
 *
2964 2960
 *  Returns <i>arg</i> converted to a float. Numeric types are converted
2965
 *  directly, the rest are converted using <i>arg</i>.to_f. As of Ruby
2966
 *  1.8, converting <code>nil</code> generates a <code>TypeError</code>.
2961
 *  directly, the rest are converted using <i>arg</i>.to_f.
2962
 *  Converting <code>nil</code> generates a <code>TypeError</code>.
2967 2963
 *
2968 2964
 *     Float(1)           #=> 1.0
2969 2965
 *     Float("123.456")   #=> 123.456
......
3035 3031
 *  call-seq:
3036 3032
 *     String(arg)   -> string
3037 3033
 *
3038
 *  Returns <i>arg</i> as an <code>String</code>.
3034
 *  Returns <i>arg</i> as a <code>String</code>.
3039 3035
 *
3040 3036
 *  First tries to call its <code>to_str</code> method, then its <code>to_s</code> method.
3041 3037
 *
......
3070 3066
 *
3071 3067
 *  Returns +arg+ as an Array.
3072 3068
 *
3073
 *  First tries to call Array#to_ary on +arg+, then Array#to_a.
3069
 *  First tries to call <code>to_ary</code> on +arg+, then <code>to_a</code>.
3074 3070
 *
3075 3071
 *     Array(1..5)   #=> [1, 2, 3, 4, 5]
3076 3072
 */
......
3125 3121
 *  Typically, you create a new class by using:
3126 3122
 *
3127 3123
 *    class Name
3128
 *     # some class describing the class behavior
3124
 *     # some code describing the class behavior
3129 3125
 *    end
3130 3126
 *
3131 3127
 *  When a new class is created, an object of type Class is initialized and
......
3137 3133
 *  <code>Class</code>:
3138 3134
 *
3139 3135
 *     class Class
3140
 *        alias oldNew  new
3141
 *        def new(*args)
3142
 *          print "Creating a new ", self.name, "\n"
3143
 *          oldNew(*args)
3144
 *        end
3145
 *      end
3136
 *       alias old_new new
3137
 *       def new(*args)
3138
 *         print "Creating a new ", self.name, "\n"
3139
 *         old_new(*args)
3140
 *       end
3141
 *     end
3146 3142
 *
3143
 *     class Name
3144
 *     end
3147 3145
 *
3148
 *      class Name
3149
 *      end
3146
 *     n = Name.new
3150 3147
 *
3151
 *
3152
 *      n = Name.new
3153
 *
3154 3148
 *  <em>produces:</em>
3155 3149
 *
3156 3150
 *     Creating a new Name
3157 3151
 *
3158 3152
 *  Classes, modules, and objects are interrelated. In the diagram
3159 3153
 *  that follows, the vertical arrows represent inheritance, and the
3160
 *  parentheses meta-classes. All metaclasses are instances
3154
 *  parentheses metaclasses. All metaclasses are instances
3161 3155
 *  of the class `Class'.
3162 3156
 *                             +---------+             +-...
3163 3157
 *                             |         |             |
......
3218 3212
 *
3219 3213
 *  BasicObject does not include Kernel (for methods like +puts+) and
3220 3214
 *  BasicObject is outside of the namespace of the standard library so common
3221
 *  classes will not be found without a using a full class path.
3215
 *  classes will not be found without using a full class path.
3222 3216
 *
3223 3217
 *  A variety of strategies can be used to provide useful portions of the
3224 3218
 *  standard library to subclasses of BasicObject.  A subclass could
......
3256 3250
 *
3257 3251
 *  Object is the default root of all Ruby objects.  Object inherits from
3258 3252
 *  BasicObject which allows creating alternate object hierarchies.  Methods
3259
 *  on object are available to all classes unless explicitly overridden.
3253
 *  on Object are available to all classes unless explicitly overridden.
3260 3254
 *
3261 3255
 *  Object mixes in the Kernel module, making the built-in kernel functions
3262 3256
 *  globally accessible.  Although the instance methods of Object are defined