objects.html

<article>  
  <h1 id=objects>Objects</h1>

    <!-- Summary
      * Objects are instances of classes 
      * An object's behaviour is defined by its methods 
      * An object's state is stored in its instance variables 
    -->
    <!-- Discuss immediate values: objects can be constructed via message
    sending (constructors), which may be instance or singleton methods, or via
    literals -->

    <!-- TODO: ObjectSpace.count_objects -->
    <!-- TODO: Delegator: Here or Methods? -->
    <!-- cite source of object definition --> <p>An <dfn>object</dfn> is a
    compilation of data (attributes) and behaviour (methods) which
    encapsulate a specific <i>instance</i> of a <a
      href=/classes>class</a>. The <code>String</code>
    <code>"hello"</code> and the <code>Integer</code> <code>3</code> are
    both examples of objects, and instances of the <code>String</code> and
    <code>Integer</code> classes, respectively. They constitute data
    (<em>hello</em> and <em>3</em>, respectively) and behaviour relevant
    to that data.</p>

    <section>
      <h1 id=instantiation>Instantiation</h1>
      
      <!-- More preamble here -->
      <p>There are five main ways to <dfn>instantiate</dfn>, or
      <em>create</em>, an object: 
      
      <ul>
        <li>Using a <a href=#literals>literal</a>.
        <li>Sending a <a href=#constructors>constructor</a> message to an
        existing object (usually a class).
        <li><a href=#cloning>Cloning</a> or <a
          href=#duplication>duplicating</a> an existing object.
        <li>Loading a serialized, or <a href=#marshaling>Marshaled</a>, object.
      </ul>
      
      <p>In addition, certain core objects always exist without being
      instantiated: they are created by the Ruby interpreter. </p>


      <section>
        <h1 id=constructors>Constructors</h1>

        <section>
          <h1 id=dot-new><code>.new</code></h1>

          <p>Sending the <code>:new</code> message to a class
          instantiates that class. For example, <code>Array.new</code>
          creates an <code>Array</code> object. A method that
          instantiates a class is a <dfn
            title="constructor">constructor</dfn>: it allocates an
          object then initializes its state.
        </section>

        <section>
          <h1 id=allocation>Allocation</h1>

          <p><code>Class#allocate</code> allocates memory for a new
          object and returns a reference to it. It cannot be overridden.
          If invoked manually, it returns an uninitialized instance of
          the class. <!-- some classes forbid this; maybe this is an
          idiom: privatise #allocate so as to prevent uninitialized
          objects? -->
        </section>

        <section>
          <h1 id=initialization>Initialization</h1>
      
          <p>The newly allocated object is sent an
          <code>:initialize</code> message along with the arguments
          passed to <code>.new</code>. The <code>#initialize</code>
          method typically validates the constructor’s arguments then
          assigns them to instance variables. It is a private method so
          cannot be called from outside the class.

          <p>The <code>.new</code> constructor ignores the return value
          of <code>#initialize</code>, so as to return the initialized
          object instead.

          <p>It is good practice for a class—particularly one with a
          superclass other than <code>Object</code>—that defines an
          <code>#initialize</code> method to call its parent’s
          <code>#initialize</code> with <a
            href=/methods#super><code>super</code></a>. This allows the
          superclass and any included modules to perform their own
          initialization routines.
        </section>
      </section>
        <!-- Pickaxe pp. 427: Hook for object creation -->
    </section>

    <!--<section>
      <h1>Vocabulary</h1>

      Do we want to use this term? 
      <ol>
        <li>Ask an object what it understands by sending it :methods /
        :instance_methods
      </ol>
    </section>-->

    <section>
      <h1 id=identity>Identity</h1>      
      
      <p>Every object has a numeric identifier that is unique among other
      objects and constant for the object’s lifetime. It is returned as a
      <code>Fixnum</code> by <code>Object#object_id</code>.

      <p><code>ObjectSpace._id2ref</code> returns a reference to an object given
      its ID. For example, <code>ObjectSpace._id2ref([1, 2].object_id) = [1,
        2]</code>. <!--
      http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/348859 -->

      <!-- Note http://www.engineyard.com/blog/2010/memoization-and-id2ref/ -->
      <p>An object’s ID should not be confused with its hash code as returned by
      <code>Object#hash</code>. Logically identical objects should have the same
      hash code, yet will have different object IDs if they are pointed to by
      different references. For example, <code>[].object_id !=
        [].object_id</code> yet <code>[].hash == [].hash</code>.

      <!-- Hash#compare_by_identity -->
    </section>

    <section>
      <h1 id=class>Class</h1> <!-- Is the class a component of identity? -->

      <p>The class of an object is returned by
      <code>Object#class</code>. To test whether an object is an
      instance of a given class, use the
      <code>Object#is_a?(<var>class</var>)</code> predicate, where
      <var>class</var> is a <code>Class</code> object. <!-- === -->
    </section>

    <section>
      <h1 id=relations>Relations</h1>
      <!-- Explain that as relational operators are method calls the LHS gets to
      evaluate the relation -->
      <!-- Look at wikipedia Relations article for this -->

      <section>
        <h1 id=order>Order</h1>
          
        <p>If instances of a class suggest an ordering relationship such that
        one instance is either less than, greater than, or equal to, another,
        they are said to be <dfn title="comparable class">comparable</dfn>. The
        class can define a method named <code>&lt;=&gt;</code> (the <dfn
          title="spaceship operator">spaceship operator</dfn>) expecting a
        single argument and
        following the <code>qsort(3)</code> convention <!-- reference this --> of
        returning <code>-1</code> if <code>self</code> is less than the
        argument, <code>0</code> if they are equal, or <code>1</code> if
        <code>self</code> is greater. <!-- Describe returning nil for
        incomparable argument; http://redmine.ruby-lang.org/issues/show/2276 -->

        <p>The class then mixes in the <code>Comparable</code> module, which
        provides <code>#&lt;</code>, <code>#==</code>, and <code>#&gt;</code>
        methods implemented in terms of <code>#&lt;=&gt;</code>. 
        
        <!-- http://redmine.ruby-lang.org/repositories/diff/ruby-19/object.c?rev=25453
        -->
      </section>

      <section>
        <h1 id=equivalence>Equivalence</h1>

        <!-- Link with Comparison section: <=> defines == --> 
        <!-- Diagram showing equality on a strict..loose line, e.g. 
        equal?    eql?  ==
        Strictest <-> Loosest
        --> 
        <p>The means by which objects are compared for equality depend on the type
        of equality desired.
        
        <p><code>Object#equal?</code> considers the receiver equal to the argument
        if the two objects are identical, i.e. their object IDs are equal. For
        example, <code>[].equal?([]) == false</code>. Classes are discouraged from
        overriding this method, so its semantics should not change.
        
        <p><code>Object#==</code> is an alias of <code>Object#equal?</code>, but
        <i>is</i> normally overridden in subclasses to denote <i>logical</i>
        equivalence. For example, <code>Array#==</code> regards two
        <code>Array</code> objects equal if they contain the same number of
        elements and each element is <code>==</code> to its corresponding element.
        So, <code>[O.new] == [O.new]</code> is <code>true</code> if <code>O.new ==
          O.new</code>.
        
        <p><code>Object#!=</code> returns the inverse of <code>Object#==</code>,
        so it does not normally need to be defined explicitly. It can be, however.
        
        <p><code>Object#eql?</code> is also an alias of
        <code>Object#equal?</code> that subclasses often override. It differs
        from <code>Object#==</code> in that it denotes <i>strict</i> logical
        comparison without performing type conversion. For example, consider 1
        and 1.0. The two are logically equivalent if converted to the same
        class, so <code>1 == 1.0</code>.  However, <code>1.eql?(1.0) ==
          false</code> because <code>Object#eql?</code> does not perform type
        conversion.
        
        <p><a class=ref href=/references#refFLAN08>Flanagan &amp; Matsumoto</a>
        (pp. 77–78) state that <q>If two objects are <code>eql?</code>, their
          <code>hash</code> methods must also return the same value.</q>, going
        on to recommend that classes implement <code>#eql?</code> in terms of
        <code>#hash</code>.</p>
        
        <!-- Cover === and =~ ? -->
      </section>
    </section>

    <section>
      <h1 id=state>State</h1>

      <section>
        <h1 id=instance-variables>Instance Variables</h1>

        <p>The state of an object is encapsulated in its <a
          href=/variables#instance>instance variables</a>, whose
        values are local to that particular object, hidden <!-- better word? -->
        from others. An object will not respond to a message selecting one if its
        instance variables unless a corresponding method has been defined, either
        explicitly, or implicitly with <code>attr</code> <!-- link to section;
        clarify the attr _familly_? -->.

        <p>An instance variable is typically defined in an instance method. If
        defined in the context of a class it is a <a
          href=/classes#class-instance-variables>class instance variable</a>.
      </section>

      <section>
        <h1 id=attributes>Attributes</h1>
        
        <p>An attribute, <var>a</var>, is a pair (<a class=ref
          href=/references#refFLAN08>Flanagan &amp; Matsumoto</a>, pp.
        94–95) of public methods—an accessor (<var>a</var>) and a writer
        (<var>a=</var>)—exposing a property of an object’s state to
        other objects. They can be created automatically by supplying
        their names to <code>Module#attr_accessor</code> or
        <code>Module#attr_writer</code> inside a class definition. This
        assumes, as is typical, that an attribute corresponds to an
        instance variable of the same name, i.e.  <var>a</var> returns
        <var>@a</var>; <var>a=</var> sets <var>@a</var>. If the
        attribute value is not backed by an instance variable, it should
        be exposed in the same way (<a href=/references#refMEYER00
          class=ref>Meyer</a>, pp. 55–57) by defining the methods
        manually.

        <p>The writer method <a href=/variables#lvalue-attribute>behaves
          specially</a> when used as an <a
          href=/variables#lvalues>lvalue</a> in an
        <a href=/variables#assignment>assignment expression</a>.

        <!-- In the Ruby cookbook these are called "virtual attributes"
        --> 
        
        <!-- http://github.com/rails/rails/blob/master/activesupport/lib/active_support/core_ext/class/attribute_accessors.rb
        -->
        <!-- Module#attr ? -->
      </section>
  
      <section>
        <h1 id=mutability>Mutability</h1>
      
        <!-- Define _mutability_ -->
        <p><code>Object#freeze</code> makes the receiver immutable: attempts to
        change its state elicit a <code>RuntimeError</code>. The
        <code>Object#frozen?</code> predicate returns <code>true</code> if the
        receiver is frozen. There is not a <code>#thaw</code> method, so this
        operation is not reversible. However, duplicating an object <!-- link #dup
        --> removes its frozen state.</p>
        
        <aside class=note>
          Freezing works on objects not variables, so it is permissible to assign
          a new value to a “frozen variable”. <!-- explain why we're saying this?
          -->
        </aside> 
        <!-- TODO: Example
        class ImmutableString < String
          def initialize(s)
            super(s).freeze
          end
        end -->
        <!-- Note that immediates can be frozen...; link to my bug report -->
      </section>
    </section>
    
    <section>
      <h1 id=references>References &amp; Garbage Collection</h1> <!-- Lifespan / Lifetime ? -->

      <p>Variables store references to objects. Assignment is,
      therefore, the copying of the reference on the right-hand side to
      the variable named on the left, leaving both sides referring to
      the same object. However, a reference may not be dereferenced; it
      is not a pointer.

      <p>An object is deemed <dfn title="unreachable
        object">unreachable</dfn> when there are no references to it, or
      the sources of the remaining references are themselves
      unreachable. Such objects are subject to garbage collection:
      automatic destruction by Ruby. The lifetime of an object is
      determined by its longest living reference. If an object is
      intended to be temporal, its references must be likewise.

      <!-- GC.start, GC.disable -->
    </section>

    <section>
      <h1 id=basicobject>BasicObject</h1>

      <p><code>BasicObject</code> is the root of the class hierarchy: from this
      all other classes ultimately inherit. Its superclass is <code>nil</code>.
      It defines the bare minimum of methods so as to be a “blank slate”:
      <q>…useful as the superclass of delegating wrapper classes…</q> (<a
        class=ref href=/references#refFLAN08>Flanagan &amp; Matsumoto</a>, p
      235). (A thorough explanation of “blank slate” classes in Ruby is found in
      <a href=/references#refBROWN09 class=ref>Brown</a>, pp. 57–62). <!--
      Footnote this remark? -->

      <!-- Clarify that by default classes inherit from Object? -->
      <!-- Note implications of having so few methods? In irb? -->
    </section>

    <section>
      <h1 id=duplication>Duplication</h1>

      <p><code>Object#dup</code> creates a shallow copy of the receiver. A new
      instance of the receiver’s class is allocated, tainted if the original
      object was, then populated with shallow copies of the receiver’s
      instance variables. Neither singleton methods nor frozen state are
      duplicated<a href=#fn-dup-clone>†</a>. Corresponding instance variables
      will refer to the same object because they are copied by reference; not
      referent.</p>

      <p>If the duplicated object responds to <code>:initialize_dup</code>, it
      will be sent this message with the receiver as an argument. Its return
      value is ignored. A common use is to perform a deep copyَ<a
        href=#fn-deep-copy>†</a> of instance variables by explicitly
      duplicating them. If an object may only
      be duplicated under certain circumstances, <code>#initialize_dup</code>
      may choose to raise an exception.</p>

      <p>If an object doesn’t respond to <code>:initialize_dup</code>, but
      does respond to <code>:initialize_copy</code>, it is sent the latter
      instead, with the same semantics as <code>:initialize_dup</code>.</p>

      <p>Objects that shouldn’t be duplicated can privatise their
      <code>#dup</code> method or define it to raise an informative exception
      (<a class=ref href=/references#refFLAN08>Flanagan &amp; Matsumoto</a>, pp.
      243–245).
      <!-- TODO: Note that NilClass, TrueClass, FalseClass, Integer, Float,
      and Symbol can't be dup'd -->
    </section>

    <section>
      <h1 id=cloning>Cloning</h1>
    
      <p><code>Kernel#clone</code>, behaves like <a
        href=#duplication><code>Kernel#dup</code></a> except it also copies
      singleton methods and frozen state. Further, instead of sending
      <code>:initialize_dup</code> to its receiver it sends
      <code>:initialize_clone</code>, falling back to
      <code>:initialize_copy</code>, if the former isn’t defined.
      </ul>

      <!-- TODO: The obvious example is prototypical programming, but we also
      discuss that in Methods... -->
    </section>

    <section>
      <h1 id=marshaling>Marshaling</h1> <!-- Serialization? Make part of Instantiation? -->
      
      <p>An object may be serialized as a binary <code>String</code> by
      supplying it to <code>Marshal.dump</code>. If an <code>IO</code> object is
      supplied as the second argument, the marshaled object is written to it.
      <code>Marshal.load</code> reverses this process by recreating the object
      from its marshaled form, which may be a string <!-- Explain somewhere that
      _string_ (or _string-y_) is an object that String.try_convert(obj) != nil
      --> or <code>IO</code> object.

      <p>The Marshal data format is versioned with a major and minor number,
      which are stored in the first two bytes of marshaled data.
      <code>Marshal.load</code> raises a <code>TypeError</code> unless the data
      has the current major version and a minor version ≤ the current
      minor version.

      <!-- Investigate interaction between #_dump and #marshal_dump -->

      <p>Objects may control how they’re dumped by responding to
      <code>:marshal_dump</code> with another object to be serialized in their
      place. If so, they must also respond to <code>:marshal_load</code>, which
      is sent to an allocated, uninitialized instance of their class with the
      recreated object as an argument. It is expected to initialize the state of
      the receiver from that of its argument. The return value is ignored.
    </section>

    <section>
      <h1 id=taint>Taint</h1>

      <!-- Clarify that every object is either tainted or not -->
      <p>Taint checking is a security mechanism that blacklists objects
      influenced by external input, propagating this trait to derivative
      objects. Data read from <code>IO</code> streams and user input is
      automatically tainted. An object can be explicitly tainted by
      sending it <code>:taint</code>. The <code>#tainted?</code>
      predicate returns <code>true</code> if the receiver, or an object
      from which it derived, is tainted. Taintedness persists over
      duplication and cloning. It can be removed with
      <code>Object#untaint</code>.

      <p>If <code>$SAFE &gt; 0</code> certain methods raise
      <code>SecurityError</code>s when given tainted objects. <!-- How
      do we handle this? Separate section for $SAFE? List a sampling of
      methods? -->
    </section>

    <section>
      <h1 id=trust>Trust</h1>
    
      <p>Objects and running code are either trusted or untrusted. They
      are trusted by default unless <code>$SAFE</code> ≥ 3, in which
      case they are untrusted. Untrusted code is prohibited from
      modifying trusted objects.

      <p>An object may be explicitly trusted by sending it
      <code>:trust</code> when <code>$SAFE &lt; 3</code>; a message of
      <code>:untrust</code> does the converse when <code>$SAFE &lt;
        4</code>. The <code>Object#untrusted?</code> predicate returns
      <code>true</code> when the receiver is not trusted;
      <code>false</code> otherwise.
    </section>

    <!--
  <h2>Defining Methods On</h2>  Behaviour 

  <h2>Listing Methods</h2>  Interrogating? / Under Behaviour?

  <h2>Extending</h2> In Modules? 

  <h2>ObjectSpace</h2>
  [ruby-core:19600] 
  ObjectSpace.each_object(o) do
   if o.is_a?(IO)
     o.close rescue nil
   end
  end
  -->

  <section>
    <h1 id=context>Context</h1>
    
    <p><code>BasicObject#instance_eval</code> takes a string or block
    which it evaluates in the receiver’s context, setting
    <code>self</code> to the receiver. The evaluated code can access the
    object’s instance variables, invoke its private and protected
    methods, and define methods on its singleton class. <!-- Needs
    examples of all three -->

    <p><code>BasicObject#instance_exec</code> is similar, but accepts
    any number of arguments which it passes to the required block.
  </section>

  <section>
    <h1 id=conversion>Conversion</h1>

    <!-- Look at Ruby Cookbook, pp 287–291 --> <p>Selectors whose
    names begin with <i>to_</i> are expected to return the receiver
    converted to an object of the indicated class. A conversion is
    either <i>implicit</i> or <i>explicit</i>, as explained below:</p>
   
    <section>
      <h1 id=implicit-conversion>Implicit Conversion</h1>
      
      <p>A method may expect an argument of a particular class. If it
      receives an object of another class it wishes to automatically
      convert that object into one of the desired class. 
      
      <p>For example, <code>Array.new</code> may be called with an Array as
      an argument, which is copied to produce a new Array. If the argument
      is not of class <code>Array</code>, <code>Array.new</code> sends
      <code>:to_ary</code> to the argument, implicitly converting it to an
      <code>Array</code>.

      <p><code>Array.new</code> sent <code>:to_ary</code> because it is part
      of the implicit conversion protocol. By responding to this message
      with an <code>Array</code>  objects are declaring that they may be
      used in place of an <code>Array</code>. 
       
      <p>If the argument responds to <code>:to_a</code> it can also be
      automatically converted to an <code>Array</code>. However,
      <code>Array.new</code> does not send this message for it is part of
      the <i>explicit</i> conversion protocol; the sender of the message
      must send the argument <code>:to_a</code> himself if he requires the
      conversion.

      <p><a class=ref href=/references#refFLAN08>Flanagan &amp; Matsumoto</a>
      (p. 80) suggest that objects should implement an implicit conversion
      protocol if they have <q>strong characteristics</q> of the target
      class.</p>

      <section>
        <h1 id=try-convert><code>try_convert</code></h1>
      
        <!-- Describe idioms that this implies, e.g
        Array.try_convert(arg) or raise ArgumentError -->
        <p><code>Array</code>, <code>Hash</code>, <code>IO</code>,
        <code>Regexp</code>, and <code>String</code> define a class
        method named <code>try_convert</code> which uses the appropriate
        implicit conversion protocol to convert the argument to the
        receiver’s class. If the argument does not respond to the
        appropriate implicit conversion message,
        <code>.try_convert</code> returns <code>nil</code>.

        <p>For example,
        <code>String.try_convert(<var>object</var>)</code> returns
        <code><var>object</var>.to_str</code> if <var>object</var>
        responds to <code>:to_str</code>; <code>nil</code> otherwise.
      </section>

      <p>From the discussion above we can derive the following rules:

      <ol>
        <li>A method may send implicit conversion messages to its
        arguments. 
        <li>Objects responding to such messages are declaring that they may
        be used in this way.
        <li>A method must not send explicit conversion messages to its
        arguments.
      </ol>
    </section>

    <section>
      <h1 id=explicit-conversion>Explicit Conversion</h1>
      
      <p>An object which can be represented as an object of another class
      may implement the relevant explicit conversion protocol. It is
      explicit because the user must explicitly send the conversion message
      to the object to effect the conversion; the message should never be
      sent automatically by another method.

      <p>If an object implements an implicit conversion protocol that
      corresponds with an explicit conversion protocol, it should implement
      the explicit protocol, too. The implicit protocol is a superset of the
      explicit protocol, so there will not exist a scenario where an object
      would need to implement the former without the latter. This can be easily
      achieved by aliasing the implicit method to the explicit method. For
      example, if an object responds to <code>:to_ary</code> but not to
      <code>:to_a</code> it should alias <code>:to_a</code> to
      <code>:to_ary</code>.

      <p>From the discussion above we can derive the following rules:

      <ol>
        <li>A method should not send explicit conversion messages to its
        arguments. 
        <li>Objects responding to implicit conversion messages that have
        explicit counterparts should respond to the latter, too. 
      </ol>
    </section>

    <p>The conversion protocol is summarised in the table below. The
    <i>Target Class</i> column indicates the class of the object the
    conversion method should return. The <i>Implicit</i> column specifies
    the message, if any, that is part of the implicit conversion protocol
    for the target class. Likewise, the <i>Explicit</i> column specifies
    the message, if any, that is part of the explicit conversion protocol
    for the target class. If a protocol is not defined for a class, it has a
    value of <i>N/A</i> is given. 
    
    <p>Note that the absence of an implicit protocol for a class implies
    that it should not be converted implicitly. Methods expecting arguments
    of a non-convertible class should raise a <code>TypeError</code> if they
    receive arguments of an unsuitable type.</p>

    <!-- Use spanning cell when an implicit message is given without an explicit
    counterpart? -->
    <table class=border style=width:60%>
      <thead>
        <tr>
          <th>Target Class 
          <th>Implicit 
          <th>Explicit
          <th>Note
      <tbody class=zebra>
        <tr>
          <td><code>Array</code></td> 
          <td><code>:to_ary</code></td>
          <td><code>:to_a</code></td>
          <td>&nbsp;
        <tr>
          <td><code>Complex</code></td> 
          <td><code>:to_c</code></td>
          <td>N/A</td>
          <td>&nbsp;</td>
        <tr>
          <td><code>Enumerator</code></td> 
          <td>N/A</td>
          <td><code>:to_enum</code></td>
          <td>&nbsp;</td>
        <tr>
          <td><code>Float</code></td> 
          <td><code>:to_f</code></td>
          <td>N/A</td>
          <td>&nbsp;</td>
        <tr>
          <td><code>Hash</code></td> 
          <td><code>:to_hash</code></td>
          <td>N/A</td>
          <td>&nbsp;</td>
        <tr>
          <td><code>Integer</code></td> 
          <td><code>:to_int</code></td>
          <td><code>:to_i</code></td>
          <td>&nbsp;</td>
        <tr>
          <td><code>IO</code></td> 
          <td><code>:to_io</code></td>
          <td>N/A</td>
          <td>Sent by <code>IO.try_convert</code>
        <tr>
          <td><code>IO</code></td> 
          <td><code>:to_open</code></td>
          <td>N/A</td>
          <td>Sent by <code>Kernel#open</code> to its first argument</td>
        <tr>
          <td><code>Proc</code></td> 
          <td><code>:to_proc</code></td>
          <td>N/A</td>
          <td>&nbsp;</td>
        <tr>
          <td><code>Rational</code></td> 
          <td><code>:to_r</code></td>
          <td>N/A</td>
          <td>&nbsp;</td>
        <tr>
          <td><code>Regexp</code></td> 
          <td><code>:to_regexp</code></td>
          <td>N/A</td>
          <td>Sent by <code>Regexp.try_convert</code></td>
        <tr>
          <td><code>String</code></td> 
          <td><code>:to_str</code></td>
          <td><code>:to_s</code></td>
          <td>&nbsp;</td>
        <tr>
          <td><code>String</code></td> 
          <td><code>:to_path</code></td>
          <td>N/A</td>
          <td>Sent by methods expecting a file path as an argument, such as
            the class methods of <code>File</code></td>
        <tr>
          <td><code>Symbol</code></td> 
          <td><code>:to_sym</code></td>
          <td>N/A</td>
          <td>&nbsp;</td>
    </table> 

    <section>
      <h1 id=converting-to-boolean>Converting to “Boolean”</h1>

      <p>It is rarely necessary to convert an object to a “Boolean” because Ruby
      automatically treats <code>false</code> and <code>nil</code> as false, and
      any other value as true. However, if a method wishes to return either
      <code>true</code> or <code>false</code> it may use the
      <code>!!<var>object</var></code> idiom. This returns <code>false</code> if
      <var>object</var> is <code>false</code> or <code>nil</code>;
      <code>true</code> otherwise.
    </section>
    <!-- Explain numeric coercion -->
  </section>

  <footer>
    <h1>Footnotes</h1>
    
    <ol>
      <li id=fn-dup-clone>To copy these items use <a
        href=#cloning><code>Object#clone</code></a> instead.
      <li id=fn-deep-copy>Another way to perform a deep copy of an object is:
      <code>Marshal.load(Marshal.dump(<var>object</var>))</code>.
    </ol>
  </footer>
</article>