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]