<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
  "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>

<meta http-equiv="Content-Type" content="text/html;charset=US-ASCII">

<style type="text/css">

body {
  color: #000000;
  background-color: #FFFFFF;
}

del {
  text-decoration: line-through;
  color: #8B0040;
}
ins {
  text-decoration: underline;
  color: #005100;
}

p.example {
  margin: 2em;
}
pre.example {
  margin: 2em;
}
div.example {
  margin: 2em;
}

code.extract {
  background-color: #F5F6A2;
}
pre.extract {
  margin: 2em;
  background-color: #F5F6A2;
  border: 1px solid #E1E28E;
}

p.function {
}

p.attribute {
  text-indent: 3em;
}

blockquote.std {
  color: #000000;
  background-color: #F1F1F1;
  border: 1px solid #D1D1D1;
  padding: 0.5em;
}

blockquote.stddel {
  text-decoration: line-through;
  color: #000000;
  background-color: #FFEBFF;
  border: 1px solid #ECD7EC;
  padding: 0.5em;
}

blockquote.stdins {
  text-decoration: underline;
  color: #000000;
  background-color: #C8FFC8;
  border: 1px solid #B3EBB3;
  padding: 0.5em;
}

table {
  border: 1px solid black;
  border-spacing: 0px;
  border-collapse: collapse;
  margin-left: auto;
  margin-right: auto;
}
th {
  text-align: left;
  vertical-align: top;
  padding: 0.2em;
  border: 1px solid black;
}
td {
  text-align: left;
  vertical-align: top;
  padding: 0.2em;
  border: 1px solid black;
}

</style>


<title>Multi-Word Integer Operations and Types</title>
</head>
<body>
<h1>Multi-Word Integer Operations and Types</h1>

<p>
ISO/IEC JTC1 SC22 WG21 P0104R0 - 2015-09-27
</p>

<p>
Lawrence Crowl, Lawrence@Crowl.org
</p>

<p>
<a href="#Introduction">Introduction</a><br>
<a href="#Problem">Problem</a><br>
<a href="#Solution">Solution</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#DefinitionWord">Definition of Word</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#MultiWordTypes">Multi-Word Types</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SubarrayWord">Subarray by Word Operations</a><br>
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#SubarraySubarray">Subarray by Subarray Operations</a><br>
<a href="#Issues">Open Issues</a><br>
</p>


<h2><a name="Introduction">Introduction</a></h2>

<p>
When the largest integer type is too small for an application domain,
one must use a larger type.
</p>

<p>
Multi-word integer operations
are a necessary component of many higher-level types,
such as those that appear later in the document.
</p>


<h2><a name="Problem">Problem</a></h2>

<p>
The work for multi-word integer operations is tedious.
For division it is also complicated.
It is better to do that work once.
</p>


<h2><a name="Solution">Solution</a></h2>

<p>
We propose a template for multi-word integer types
that behave like built-in types.
While built-in types often have insecure semantics,
they are also efficient and well understood.
Some programmers will prefer to use these types directly,
but we also expect these types to be used as implementation tools
for higher-level types.
</p>

<p>
We also propose a set of multi-word integer operations
based on pointers and counts.
This low-level interface is intended as an implementation tool
for higher level operations and types,
including those mentioned above.
These operations can be built upon the wide operations
presented in
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/p0106.html">P0103r0
Overflow-Detecting and Double-Wide Arithmetic Operations</a>.
</p>

<p>
Within this document, we use <code>S</code> to refer to a signed word
and <code>U</code> to refer to an unsigned word.
</p>


<h3><a name="DefinitionWord">Definition of Word</a></h3>

<p>
A word is the type provided by <code>LARGEST_SINGLE_WIDE_ALL</code>
and defined in
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/p0106.html">P0103r0
Overflow-Detecting and Double-Wide Arithmetic Operations</a>.
</p>


<h3><a name="MultiWordTypes">Multi-Word Types</a></h3>

<p>
We obtain a multi-word integer type with one of the following templates.
</p>

<pre>
<code>template&lt;int words&gt; multi_int;
template&lt;int words&gt; multi_uint;</code>
</pre>

<p>
The <code>multi_int</code> type uses a two's complement representation.
</p>

<p>
The following multi-word operators take
two multi-word arguments of arbitrary size and sign.
The result type is a promoted type as specified for built-in integers.
</p>

<pre>
<code>~ * / % + - &lt; &gt; &lt;= &gt;= &amp; | ^
= *= /= %= += -= &lt; &gt; &lt;= &gt;= &amp;= |= ^=</code>
</pre>

<p>
The following multi-word operators take
a left-hand multi-word argument (of arbitrary size and sign)
and a right-hand integer argument.
The result type is the type of the left-hand argument.
</p>

<pre>
<code>&lt;&lt; &gt;&gt; &lt;&lt;= &gt;&gt;=</code>
</pre>

<p>
All types implicitly convert to <code>bool</code>
via the normal rules.
</p>

<p>
Functions return by value.
Programmers should consider the composite operation and assignment operators.
</p>


<h3><a name="SubarrayWord">Subarray by Word Operations</a></h3>

<p>
We provide the following operations.
These operations are not intended to provide complete multi-word operations,
but rather to handle subarrays with uniform operations.
Higher-level operations then compose these operations into a complete operation.
</p>

<dl>

<dt><code>U unsigned_subarray_addin_word U* multiplicand, int length, U addend );</code></dt>
<dd><p>
Add the word <code>addend</code>
to the <code>multiplicand</code> of length <code>length</code>,
leaving the result in the <code>multiplicand</code>.
The return value is any carry out from the <code>accumulator</code>.
</p></dd>

<dt><code>U unsigned_subarray_add_word U* summand, const U* augend, int length, U addend );</code></dt>
<dd><p>
Add the <code>addend</code>
to the <code>augend</code> of length <code>length</code>
writing the result to the <code>summand</code>,
which is also of length <code>length</code>.
The return value is any carry out from the <code>summand</code>.
</p></dd>

<dt><code>U unsigned_subarray_mulin_word U* product, int length, U multiplier );</code></dt>
<dd><p>
Multiply the <code>product</code> of length <code>length</code>
by the <code>multiplier</code>,
leaving the result in the <code>product</code>.
The return value is any carry out from the <code>product</code>.
</p></dd>

<dt><code>U unsigned_subarray_mul_word U* product, U* multiplicand, int length, U multiplier );</code></dt>
<dd><p>
Multiply the <code>multiplicand</code> of length <code>length</code>
by the <code>multiplier</code>
writing the result to the <code>product</code>,
which is also of length <code>length</code>.
The return value is any carry out from the <code>product</code>.
</p></dd>

<dt><code>U unsigned_subarray_accmul_word U* accumulator, U* multiplicand, int length, U multiplier );</code></dt>
<dd><p>
Multiply the <code>multiplicand</code> of length <code>length</code>
by the <code>multiplier</code>
adding the result to the <code>accumulator</code>,
which is also of length <code>length</code>.
The return value is any carry out from the <code>accumulator</code>.
</p></dd>

</dl>

<p>
For each of the two add operations above,
there is a corresponding subtract operation.
</p>

<p>
For each of the seven operations above (add+sub+mul),
there is a corresponding signed operation.
The primary difference between the two is sign extension.
</p>

<h3><a name="SubarraySubarray">Subarray by Subarray Operations</a></h3>

<p>
For each of the fourteen operations in the section above,
there is a corresponding operation where the 'right-hand' argument
is a pointer to a subarray,
which is also of length <code>length</code>.
</p>


<h2><a name="Issues">Open Issues</a></h2>

<p>
There are as yet no definitions for subarray division.
</p>


</body>
</html>
