<?xml version="1.0"?>
<!--
   Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->

<document>

 <properties>
  <title>FAQ</title>
  <author email="dev@commons.apache.org">Commons Documentation Team</author>
 </properties>

 <body>

<section name="FAQ">
<dl>
<dt>Q: Why would I use the primitive collections?</dt>
<dd>
<p>
The main advantage of the primitive collections is that they are signficantly smaller than their java.util equivalents.
How much smaller?
</p>
<table border="1" cellspacing="0">
 <tr>
  <th>Object-based Collection</th>
  <th>Bytes per Element</th>
  <th>Primitive Collection</th>
  <th>Bytes per Element</th>
  <th>Space Savings</th>
 </tr>
 <tr>
  <td>ArrayList of Bytes</td>
  <td align="right">16</td>
  <td>ArrayByteList</td>
  <td align="right">1</td>
  <td align="right">93.4%</td>
 </tr>
 <tr>
  <td>ArrayList of Shorts</td>
  <td align="right">16</td>
  <td>ArrayShortList</td>
  <td align="right">2</td>
  <td align="right">87.5%</td>
 </tr>
 <tr>
  <td>ArrayList of Characters</td>
  <td align="right">16</td>
  <td>ArrayCharList</td>
  <td align="right">4</td>
  <td align="right">75.0%</td>
 </tr>
 <tr>
  <td>ArrayList of Floats</td>
  <td align="right">16</td>
  <td>ArrayFloatList</td>
  <td align="right">4</td>
  <td align="right">75.0%</td>
 </tr>
 <tr>
  <td>ArrayList of Integers</td>
  <td align="right">16</td>
  <td>ArrayIntist</td>
  <td align="right">4</td>
  <td align="right">75.0%</td>
 </tr>
 <tr>
  <td>ArrayList of Doubles</td>
  <td align="right">16</td>
  <td>ArrayDoubleList</td>
  <td align="right">8</td>
  <td align="right">50.0%</td>
 </tr>
 <tr>
  <td>ArrayList of Longs</td>
  <td align="right">16</td>
  <td>ArrayLongList</td>
  <td align="right">8</td>
  <td align="right">50.0%</td>
 </tr>
</table>
<p>
Depending upon your circumstances, you may also find the primitive collections to be faster, 
both because of the reduction in time spent boxing and un-boxing the primitives and their
Object wrappers, and because there are fewer bytes to move around when copying or moving 
data.
</p>
<p>
Finally, in the pre-autoboxing (JDK 1.5) world, you may also find the primitive collections easier 
to work with, since you'll waste fewer keystrokes manually boxing and un-boxing the 
primitives and their Object wrappers.  For instance, to sum an ArrayList of Integers, you 
might write something like:
</p>
<pre>
int sum = 0;
for(Iterator iter = list.iterator(); iter.hasNext(); ) {
  sum += ((Integer)(iter.next())).intValue();
}
</pre>
<p>
The IntList equivalent would be:
</p>
<pre>
int sum = 0;
for(IntIterator iter = list.iterator(); iter.hasNext(); ) {
  sum += iter.next();
}
</pre>
</dd>

<dt>Q: But aren't the time and space efficiencies insignificant for 
the size and number of collections used by most applications?</dt>
<dd>
<p>
Yes.
</p><p>
The primitive collections are most useful for applications that create very many or very large
collections of primitive types, or that process them very frequently.
</p>
</dd>

<dt>Q: Isn't this functionality available in JDK 1.5 using auto-boxing and generics?</dt>
<dd>
<p>
No.
</p><p>
Using generics, one can create collections that are specific to a particular Object from a templated
implementation, for instance, a List of Integers or a List of Strings from the same prototype 
implemenation.  Since the distinction between Java primitives and Java Objects is not going away, it will
not be possible to, for example, instantiate a List of ints from that same prototype.
</p><p>
Using autoboxing, it is possible to emulate the syntax of using the primitive collections.
For example, <code>list.add(19)</code> will work equally well whether <code>list</code> is a List or IntList,
since the compiler will automatically convert <code>list.add(19)</code> into <code>list.add(new Integer(19))</code>.
</p><p>
While this sugar-coating of the primitive-to-Object-wrapper syntax is a welcome improvement, it does not change the 
underlying representation of the List.  That is, ArrayList will still use 16 bytes per element, even if that element
could be represented by a single byte.
</p>
</dd>

</dl>
</section>

</body>
</document>






