documentation/arbitrary-precision.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2
   3 <!-- **************************************************************************
   4      *                                                                        *
   5      *    (C) Copyright Paul Mensonides 2003-2005.                            *
   6      *                                                                        *
   7      *    Distributed under the Boost Software License, Version 1.0.          *
   8      *    (See accompanying file LICENSE).                                    *
   9      *                                                                        *
  10      *    See http://chaos-pp.sourceforge.net for the most recent version.    *
  11      *                                                                        *
  12      ************************************************************************** -->
  13
  14 <document id="Arbitrary-Precision Arithmetic" author="Paul Mensonides" date="2003-2005">
  15         <section>
  16                 <para>
  17                         The <link id="arbitrary-precision arithmetic"/> component supports arithmetic, relational, and equality operations on signed integers of any precision.
  18                 </para>
  19         </section>
  20         <section id="Representation">
  21                 <para>
  22                         Positive <link id="arbitrary-precision values"/> are represented as a <link id="sequence"/> of base-10 digits.
  23                         For example, the value +123 is represented as <code>(1)(2)(3)</code>.
  24                         Negative values are represented as a parenthesized <link id="sequence"/> of base-10 digits.
  25                         For example, the value -123 is represented as <code>((1)(2)(3))</code>.
  26                 </para>
  27         </section>
  28         <section id="Conversion">
  29                 <para>
  30                         The library supplies primitives that convert between various formats.
  31                         The first of these is <ARBITRARY_PROMOTE/> which converts a simple integer range from <code>0</code> to <LIMIT_MAG/> to an <link id="arbitrary-precision value"/> (e.g. <code><ARBITRARY_PROMOTE/>(123)</code>).
  32                         Negative values can be specified by prefixing the number with a parenthesized negation operator (e.g. <code><ARBITRARY_PROMOTE/>((-)123)</code>).
  33                 </para>
  34                 <para>
  35                         The second conversion primitive is <ARBITRARY_LITERAL/> which converts a <link id="string"/> of digits to a <link id="arbitrary-precision value"/> (e.g. <code><ARBITRARY_LITERAL/>(1 2 3)</code>).
  36                         Negative values can be specified by again prefixing the digits with a parenthesized negation operator (e.g. <code><ARBITRARY_LITERAL/>((-)1 2 3)</code>).
  37                 </para>
  38                 <para>
  39                         The third conversion primitive is <ARBITRARY_BOOL/> which converts a <link id="arbitrary-precision value"/> to a Boolean value (i.e. either <code>0</code> or <code>1</code>).
  40                 </para>
  41                 <para>
  42                         The last conversion primitive is <ARBITRARY_DEMOTE/> which converts an <link id="arbitrary-precision value"/> to a simple integer (e.g. <code><ARBITRARY_DEMOTE/>((1)(2)(3))</code>).
  43                         If the <link id="arbitrary-precision value"/> is negative, the result is prefixed with a negation operator (e.g. <code><ARBITRARY_DEMOTE/>(((1)(2)(3)))</code> expands to <code>-123</code>).
  44                 </para>
  45         </section>
  46         <section id="Arithmetic Operators">
  47                 <para>
  48                         The basic arithmetic operations are all available on <link id="arbitrary-precision values"/>.
  49                         The following table summarizes these operations and their equivalents in C or C++:
  50                         <table>
  51                                 <row>
  52                                         <column><code><ARBITRARY_ADD/>(x, y)</code></column>
  53                                         <column type="expression"><code>x + y</code></column>
  54                                 </row>
  55                                 <row>
  56                                         <column><code><ARBITRARY_DEC/>(x)</code></column>
  57                                         <column type="expression"><code>x - 1</code></column>
  58                                 </row>
  59                                 <row>
  60                                         <column><code><ARBITRARY_DIV/>(x, y)</code></column>
  61                                         <column type="expression"><code>x / y</code></column>
  62                                 </row>
  63                                 <row>
  64                                         <column><code><ARBITRARY_INC/>(x)</code></column>
  65                                         <column type="expression"><code>x + 1</code></column>
  66                                 </row>
  67                                 <row>
  68                                         <column><code><ARBITRARY_MUL/>(x, y)</code></column>
  69                                         <column type="expression"><code>x * y</code></column>
  70                                 </row>
  71                                 <row>
  72                                         <column><code><ARBITRARY_MOD/>(x, y)</code></column>
  73                                         <column type="expression"><code>x % y</code></column>
  74                                 </row>
  75                                 <row>
  76                                         <column><code><ARBITRARY_NEG/>(x)</code></column>
  77                                         <column type="expression"><code>-x</code></column>
  78                                 </row>
  79                                 <row>
  80                                         <column><code><ARBITRARY_SUB/>(x, y)</code></column>
  81                                         <column type="expression"><code>x - y</code></column>
  82                                 </row>
  83                         </table>
  84                 </para>
  85         </section>
  86         <section id="Equality &amp; Relational Operators">
  87                 <para>
  88                         The basic equality and relation operators are provided as well.
  89                         The following table summarizes these operations and their equivalents in C or C++.
  90                         <table>
  91                                 <row>
  92                                         <column><code><ARBITRARY_EQUAL/>(x, y)</code></column>
  93                                         <column type="expression"><code>x == y</code></column>
  94                                 </row>
  95                                 <row>
  96                                         <column><code><ARBITRARY_GREATER/>(x, y)</code></column>
  97                                         <column type="expression"><code>x &gt; y</code></column>
  98                                 </row>
  99                                 <row>
 100                                         <column><code><ARBITRARY_GREATER_EQUAL/>(x, y)</code></column>
 101                                         <column type="expression"><code>x &gt;= y</code></column>
 102                                 </row>
 103                                 <row>
 104                                         <column><code><ARBITRARY_LESS/>(x, y)</code></column>
 105                                         <column type="expression"><code>x &lt; y</code></column>
 106                                 </row>
 107                                 <row>
 108                                         <column><code><ARBITRARY_LESS_EQUAL/>(x, y)</code></column>
 109                                         <column type="expression"><code>x &lt;= y</code></column>
 110                                 </row>
 111                                 <row>
 112                                         <column><code><ARBITRARY_NOT_EQUAL/>(x, y)</code></column>
 113                                         <column type="expression"><code>x != y</code></column>
 114                                 </row>
 115                         </table>
 116                 </para>
 117         </section>
 118 </document>