rwaldhoff 2003/11/16 15:20:21
Modified: primitives/xdocs index.xml
Added: primitives/xdocs faq.xml
Log:
add basic FAQ
Revision Changes Path
1.7 +2 -1 jakarta-commons/primitives/xdocs/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-commons/primitives/xdocs/index.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- index.xml 6 Nov 2003 00:55:23 -0000 1.6
+++ index.xml 16 Nov 2003 23:20:21 -0000 1.7
@@ -13,7 +13,7 @@
<p>
Apache Jakarta Commons Primitives provides a collection of types and utilities
optimized
for working with Java primitives (boolean, byte, char, double, float, int, long,
short).
-Generally, the Commons-Primitives classes are faster, smaller and easier to work
with than
+Generally, the Commons-Primitives classes are smaller, faster and easier to work
with than
their purely Object based alternatives.
</p>
</section>
@@ -75,6 +75,7 @@
<p>
For more information on Commons Primitives, you might like to visit the
+<a href="faq.html">FAQ</a>,
<a href="./apidocs/index.html">JavaDocs</a>, <a href="./project-info.html">project
information</a>
or <a href="./maven-reports.html">project reports</a>.
</p>
1.1 jakarta-commons/primitives/xdocs/faq.xml
Index: faq.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Commons Primitives: FAQ</title>
<author email="[EMAIL PROTECTED]">Commons Documentation Team</author>
</properties>
<body>
<section name="The Primitives Component">
<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? Well, consider this table:
</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>
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 isn't this overkill? 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: Won't this functionality be 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 will be 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>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
