<ppdoc>
<copyright>
    Copyright (c) 2001 by Addison Wesley Longman.  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/).
</copyright>

<class name="Bignum" super="Integer" type="class">
    <tt>Bignum</tt> objects hold integers outside the range of
  <tt>Fixnum</tt>. <tt>Bignum</tt> objects are created automatically when
  integer calculations would otherwise overflow a <tt>Fixnum</tt>. When a
  calculation involving <tt>Bignum</tt> objects returns a result that will 
  fit in a <tt>Fixnum</tt>, the result is automatically converted.
<p/>
  For the purposes of the bitwise operations and <tt>[]</tt>, a
  <tt>Bignum</tt> is treated as if it were an infinite-length bitstring
  with 2's complement representation.
<p/>
  While <tt>Fixnum</tt> values are immediate, <tt>Bignum</tt> objects are
  not---assignment and parameter passing work with references to
  objects, not the objects themselves.
<p/>
  <methods type="instance">
<p/>
        <method name="Arithmetic operations" ref="Arithmeticoperations">
      <callseq>
<p/>
      </callseq>
      <desc>
<p/>
      Performs various arithmetic operations on <obj>big</obj>.
<p/>
      <table>
<tr>
  <td><obj>big</obj></td>
  <td>+</td>
  <td><obj>aNumeric</obj></td>
  <td>Addition</td>
</tr>
<tr>
  <td><obj>big</obj></td>
  <td>--</td>
  <td><obj>aNumeric</obj></td>
  <td>Subtraction</td>
</tr>
<tr>
  <td><obj>big</obj></td>
  <td>*</td>
  <td><obj>aNumeric</obj></td>
  <td>Multiplication</td>
</tr>
<tr>
  <td><obj>big</obj></td>
  <td>/</td>
  <td><obj>aNumeric</obj></td>
  <td>Division</td>
</tr>
<tr>
  <td><obj>big</obj></td>
  <td>%</td>
  <td><obj>aNumeric</obj></td>
  <td>Modulo</td>
</tr>
<tr>
  <td><obj>big</obj></td>
  <td>**</td>
  <td><obj>aNumeric</obj></td>
  <td>Exponentiation</td>
</tr>
</table>
<p/>
      </desc>
    </method>
<p/>
        <method name="Bit operations" ref="Bitoperations">
      <callseq>
<p/>
      </callseq>
      <desc>
<p/>
      Performs various operations on the binary
      representations of the <tt>Bignum</tt>.<nbsp/>
<p/>
      <table>
<tr>
<td colspan="3">~ <obj>big</obj></td>
  <td>Invert bits</td>
</tr>
<tr>
  <td><obj>big</obj></td>
  <td>|</td>
  <td><obj>aNumeric</obj></td>
  <td>Bitwise <smallfont>OR</smallfont></td>
</tr>
<tr>
  <td><obj>big</obj></td>
  <td>&amp;</td>
  <td><obj>aNumeric</obj></td>
  <td>Bitwise <smallfont>AND</smallfont></td>
</tr>
<tr>
  <td><obj>big</obj></td>
  <td>^</td>
  <td><obj>aNumeric</obj></td>
  <td>Bitwise <smallfont>EXCLUSIVE</smallfont> <smallfont>OR</smallfont></td>
</tr>
<tr>
  <td><obj>big</obj></td>
  <td>&lt;&lt;</td>
  <td><obj>aNumeric</obj></td>
  <td>Left-shift <em>aNumeric</em> bits</td>
</tr>
<tr>
  <td><obj>big</obj></td>
  <td>&gt;&gt;</td>
  <td><obj>aNumeric</obj></td>
  <td>Right-shift <em>aNumeric</em> bits
                                        (with sign extension)</td>
</tr>
</table>
<p/>
      </desc>
    </method>
<p/>
        <method name="&lt;=&gt;" ref="_lt_eq_lt">
      <callseq>
        <obj>big</obj> &lt;=&gt; <obj>aNumeric</obj> <returns>-1, 0, +1</returns>
      </callseq>
      <desc>
<p/>
      Comparison---Returns -1, 0, or +1 depending on
      whether <obj>big</obj> is less
      than, equal to, or greater than <obj>aNumeric</obj>. This is the
      basis for the tests in <tt>Comparable</tt>.
<p/>
      </desc>
    </method>
<p/>
        <method name="[ ]" ref="_ob_cb">
      <callseq>
        <obj>big</obj>[ <obj>n</obj> ] <returns>0, 1</returns>
      </callseq>
      <desc>
<p/>
      Bit Reference---Returns the <em>n</em>th bit in
      the (assumed) binary representation of <obj>big</obj>,
      where <obj>big</obj>[0] is the least significant bit.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        a = 9**15
        50.downto(0) do |n|
          print a[n]
        end
!-        print "\n"
]]></fullcode>
a<nbsp/>=<nbsp/>9**15
50.downto(0)<nbsp/>do<nbsp/>|n|
<nbsp/><nbsp/>print<nbsp/>a[n]
end
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
000101110110100000111000011110010100111100010111001
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="size" ref="size">
      <callseq>
        <obj>big</obj>.size <returns><obj>anInteger</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the number of bytes in the machine representation
      of <obj>big</obj>. 
<p/>
<codefragment>
<fullcode><![CDATA[        (256**10 - 1).size
        (256**20 - 1).size
        (256**40 - 1).size
]]></fullcode><rubycode>
<tr>
  <td><tt>(256**10<nbsp/>-<nbsp/>1).size</tt></td>
  <td>&#187;</td>
  <td><tt>12</tt></td>
</tr>
<tr>
  <td><tt>(256**20<nbsp/>-<nbsp/>1).size</tt></td>
  <td>&#187;</td>
  <td><tt>20</tt></td>
</tr>
<tr>
  <td><tt>(256**40<nbsp/>-<nbsp/>1).size</tt></td>
  <td>&#187;</td>
  <td><tt>40</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="to_f" ref="to_f">
      <callseq>
        <obj>big</obj>.to_f <returns><obj>aFloat</obj></returns>
      </callseq>
      <desc>
<p/>
      Converts <obj>big</obj> to a <tt>Float</tt>.  If <obj>big</obj> doesn't fit in a
      <tt>Float</tt>, the result is infinity.
<p/>
      </desc>
    </method>
<p/>
        <method name="to_i" ref="to_i">
      <callseq>
        <obj>big</obj>.to_i <returns><obj><obj>big</obj></obj></returns>
      </callseq>
      <desc>
<p/>
      Returns <obj>big</obj>.
<p/>
      </desc>
    </method>
<p/>
        <method name="to_s" ref="to_s">
      <callseq>
        <obj>big</obj>.to_s <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns a string containing the decimal representation of <obj>big</obj>.
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
</class>
</ppdoc>