| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <!-- NewPage --> |
| <html lang="en"> |
| <head> |
| <!-- Generated by javadoc (1.8.0_121) on Fri Apr 14 22:10:59 PDT 2017 --> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <title>org.apache.mahout.math.list (Mahout Math 0.13.0 API)</title> |
| <meta name="date" content="2017-04-14"> |
| <link rel="stylesheet" type="text/css" href="../../../../../stylesheet.css" title="Style"> |
| <script type="text/javascript" src="../../../../../script.js"></script> |
| </head> |
| <body> |
| <script type="text/javascript"><!-- |
| try { |
| if (location.href.indexOf('is-external=true') == -1) { |
| parent.document.title="org.apache.mahout.math.list (Mahout Math 0.13.0 API)"; |
| } |
| } |
| catch(err) { |
| } |
| //--> |
| </script> |
| <noscript> |
| <div>JavaScript is disabled on your browser.</div> |
| </noscript> |
| <!-- ========= START OF TOP NAVBAR ======= --> |
| <div class="topNav"><a name="navbar.top"> |
| <!-- --> |
| </a> |
| <div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div> |
| <a name="navbar.top.firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li><a href="../../../../../overview-summary.html">Overview</a></li> |
| <li class="navBarCell1Rev">Package</li> |
| <li>Class</li> |
| <li><a href="package-use.html">Use</a></li> |
| <li><a href="package-tree.html">Tree</a></li> |
| <li><a href="../../../../../deprecated-list.html">Deprecated</a></li> |
| <li><a href="../../../../../index-all.html">Index</a></li> |
| <li><a href="../../../../../help-doc.html">Help</a></li> |
| </ul> |
| </div> |
| <div class="subNav"> |
| <ul class="navList"> |
| <li><a href="../../../../../org/apache/mahout/math/jet/stat/package-summary.html">Prev Package</a></li> |
| <li><a href="../../../../../org/apache/mahout/math/map/package-summary.html">Next Package</a></li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="../../../../../index.html?org/apache/mahout/math/list/package-summary.html" target="_top">Frames</a></li> |
| <li><a href="package-summary.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_top"> |
| <li><a href="../../../../../allclasses-noframe.html">All Classes</a></li> |
| </ul> |
| <div> |
| <script type="text/javascript"><!-- |
| allClassesLink = document.getElementById("allclasses_navbar_top"); |
| if(window==top) { |
| allClassesLink.style.display = "block"; |
| } |
| else { |
| allClassesLink.style.display = "none"; |
| } |
| //--> |
| </script> |
| </div> |
| <a name="skip.navbar.top"> |
| <!-- --> |
| </a></div> |
| <!-- ========= END OF TOP NAVBAR ========= --> |
| <div class="header"> |
| <h1 title="Package" class="title">Package org.apache.mahout.math.list</h1> |
| <div class="docSummary"> |
| <div class="block"><HTML> |
| <BODY> |
| Resizable lists holding objects or primitive data types such as <tt>int</tt>, |
| <tt>double</tt>, etc.</div> |
| </div> |
| <p>See: <a href="#package.description">Description</a></p> |
| </div> |
| <div class="contentContainer"> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Class Summary table, listing classes, and an explanation"> |
| <caption><span>Class Summary</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Class</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/mahout/math/list/AbstractByteList.html" title="class in org.apache.mahout.math.list">AbstractByteList</a></td> |
| <td class="colLast"> |
| <div class="block">Abstract base class for resizable lists holding <code>byte</code> elements; abstract.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/mahout/math/list/AbstractCharList.html" title="class in org.apache.mahout.math.list">AbstractCharList</a></td> |
| <td class="colLast"> |
| <div class="block">Abstract base class for resizable lists holding <code>char</code> elements; abstract.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/mahout/math/list/AbstractDoubleList.html" title="class in org.apache.mahout.math.list">AbstractDoubleList</a></td> |
| <td class="colLast"> |
| <div class="block">Abstract base class for resizable lists holding <code>double</code> elements; abstract.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/mahout/math/list/AbstractFloatList.html" title="class in org.apache.mahout.math.list">AbstractFloatList</a></td> |
| <td class="colLast"> |
| <div class="block">Abstract base class for resizable lists holding <code>float</code> elements; abstract.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/mahout/math/list/AbstractIntList.html" title="class in org.apache.mahout.math.list">AbstractIntList</a></td> |
| <td class="colLast"> |
| <div class="block">Abstract base class for resizable lists holding <code>int</code> elements; abstract.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/mahout/math/list/AbstractList.html" title="class in org.apache.mahout.math.list">AbstractList</a></td> |
| <td class="colLast"> |
| <div class="block">Abstract base class for resizable lists holding objects or primitive data types such as |
| <code>int</code>, <code>float</code>, etc.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/mahout/math/list/AbstractLongList.html" title="class in org.apache.mahout.math.list">AbstractLongList</a></td> |
| <td class="colLast"> |
| <div class="block">Abstract base class for resizable lists holding <code>long</code> elements; abstract.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/mahout/math/list/AbstractObjectList.html" title="class in org.apache.mahout.math.list">AbstractObjectList</a><T></td> |
| <td class="colLast"> |
| <div class="block">Abstract base class for resizable lists holding objects or primitive data types such as <code>int</code>, |
| <code>float</code>, etc.First see the <a href="package-summary.html">package summary</a> and |
| javadoc <a href="package-tree.html">tree view</a> to get the broad picture.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/mahout/math/list/AbstractShortList.html" title="class in org.apache.mahout.math.list">AbstractShortList</a></td> |
| <td class="colLast"> |
| <div class="block">Abstract base class for resizable lists holding <code>short</code> elements; abstract.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/mahout/math/list/ByteArrayList.html" title="class in org.apache.mahout.math.list">ByteArrayList</a></td> |
| <td class="colLast"> |
| <div class="block">Resizable list holding <code>byte</code> elements; implemented with arrays.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/mahout/math/list/CharArrayList.html" title="class in org.apache.mahout.math.list">CharArrayList</a></td> |
| <td class="colLast"> |
| <div class="block">Resizable list holding <code>char</code> elements; implemented with arrays.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/mahout/math/list/DoubleArrayList.html" title="class in org.apache.mahout.math.list">DoubleArrayList</a></td> |
| <td class="colLast"> |
| <div class="block">Resizable list holding <code>double</code> elements; implemented with arrays.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/mahout/math/list/FloatArrayList.html" title="class in org.apache.mahout.math.list">FloatArrayList</a></td> |
| <td class="colLast"> |
| <div class="block">Resizable list holding <code>float</code> elements; implemented with arrays.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/mahout/math/list/IntArrayList.html" title="class in org.apache.mahout.math.list">IntArrayList</a></td> |
| <td class="colLast"> |
| <div class="block">Resizable list holding <code>int</code> elements; implemented with arrays.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/mahout/math/list/LongArrayList.html" title="class in org.apache.mahout.math.list">LongArrayList</a></td> |
| <td class="colLast"> |
| <div class="block">Resizable list holding <code>long</code> elements; implemented with arrays.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/mahout/math/list/ObjectArrayList.html" title="class in org.apache.mahout.math.list">ObjectArrayList</a><T></td> |
| <td class="colLast"> |
| <div class="block">Resizable list holding <code>${valueType}</code> elements; implemented with arrays.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/mahout/math/list/ShortArrayList.html" title="class in org.apache.mahout.math.list">ShortArrayList</a></td> |
| <td class="colLast"> |
| <div class="block">Resizable list holding <code>short</code> elements; implemented with arrays.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/mahout/math/list/SimpleLongArrayList.html" title="class in org.apache.mahout.math.list">SimpleLongArrayList</a></td> |
| <td class="colLast"> |
| <div class="block">Resizable list holding <code>long</code> elements; implemented with arrays; not efficient; just to |
| demonstrate which methods you must override to implement a fully functional list.</div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </li> |
| </ul> |
| <a name="package.description"> |
| <!-- --> |
| </a> |
| <h2 title="Package org.apache.mahout.math.list Description">Package org.apache.mahout.math.list Description</h2> |
| <div class="block"><HTML> |
| <BODY> |
| Resizable lists holding objects or primitive data types such as <tt>int</tt>, |
| <tt>double</tt>, etc. For non-resizable lists (1-dimensional matrices) see |
| package <code>org.apache.mahout.math.matrix</code>.<p></p> |
| <h1><a name="Overview"></a>Getting Started</h1> |
| <h2>1. Overview</h2> |
| <p>The list package offers flexible object oriented abstractions modelling dynamically |
| resizing lists holding objects or primitive data types such as <tt>int</tt>, |
| <tt>double</tt>, etc. It is designed to be scalable in terms of performance |
| and memory requirements.</p> |
| <p>Features include: </p> |
| <p></p> |
| <ul> |
| <li>Lists operating on objects as well as all primitive data types such as <tt>int</tt>, |
| <tt>double</tt>, etc. |
| </li> |
| <li>Compact representations</li> |
| <li>A number of general purpose list operations including: adding, inserting, |
| removing, iterating, searching, sorting, extracting ranges and copying. All |
| operations are designed to perform well on mass data. |
| </li> |
| <li>Support for quick access to list elements. This is achieved by bounds-checking |
| and non-bounds-checking accessor methods as well as zero-copy transformations |
| to primitive arrays such as <tt>int[]</tt>, <tt>double[]</tt>, etc. |
| </li> |
| <li>Allows to use high level algorithms on primitive data types without any |
| space and time overhead. Operations on primitive arrays, Colt lists and JAL |
| algorithms can freely be mixed at zero copy overhead. |
| </li> |
| </ul> |
| <p>File-based I/O can be achieved through the standard Java built-in serialization |
| mechanism. All classes implement the <a href="http://docs.oracle.com/javase/7/docs/api/java/io/Serializable.html?is-external=true" title="class or interface in java.io"><code>Serializable</code></a> interface. |
| However, the toolkit is entirely decoupled from advanced I/O. It provides data |
| structures and algorithms only. |
| <p> This toolkit borrows concepts and terminology from the Javasoft <a |
| href="http://www.javasoft.com/products/jdk/1.2/docs/guide/collections/index.html"> |
| Collections framework</a> written by Josh Bloch and introduced in JDK 1.2. |
| <h2>2. Introduction</h2> |
| <p>Lists are fundamental to virtually any application. Large scale resizable lists |
| are, for example, used in scientific computations, simulations database management |
| systems, to name just a few.</p> |
| <h2></h2> |
| <p>A list is a container holding elements that can be accessed via zero-based |
| indexes. Lists may be implemented in different ways (most commonly with arrays). |
| A resizable list automatically grows as elements are added. The lists of this |
| package do not automatically shrink. Shrinking needs to be triggered by explicitly |
| calling <tt>trimToSize()</tt> methods.</p> |
| <p><i>Growing policy</i>: A list implemented with arrays initially has a certain |
| <tt>initialCapacity</tt> - per default 10 elements, but customizable upon instance |
| construction. As elements are added, this capacity may nomore be sufficient. |
| When a list is automatically grown, its capacity is expanded to <tt>1.5*currentCapacity</tt>. |
| Thus, excessive resizing (involving copying) is avoided.</p> |
| <h4>Copying</h4> |
| <p> |
| <p>Any list can be copied. A copy is <i>equal</i> to the original but entirely |
| independent of the original. So changes in the copy are not reflected in the |
| original, and vice-versa. |
| <h2>3. Organization of this package</h2> |
| <p>Class naming follows the schema <tt><ElementType><ImplementationTechnique>List</tt>. |
| For example, we have a <a href="../../../../../org/apache/mahout/math/list/DoubleArrayList.html" title="class in org.apache.mahout.math.list"><code>DoubleArrayList</code></a>, which is a list |
| holding <tt>double</tt> elements implemented with <tt>double</tt>[] arrays. |
| </p> |
| <p>The classes for lists of a given value type are derived from a common abstract |
| base class tagged <tt>Abstract<ElementType></tt><tt>List</tt>. For example, |
| all lists operating on <tt>double</tt> elements are derived from |
| <a href="../../../../../org/apache/mahout/math/list/AbstractDoubleList.html" title="class in org.apache.mahout.math.list"><code>AbstractDoubleList</code></a>, |
| which in turn is derived from an abstract base class tying together all lists |
| regardless of value type, <a href="../../../../../org/apache/mahout/math/list/AbstractList.html" title="class in org.apache.mahout.math.list"><code>AbstractList</code></a>. The abstract |
| base classes provide skeleton implementations for all but few methods. Experimental |
| data layouts (such as compressed, sparse, linked, etc.) can easily be implemented |
| and inherit a rich set of functionality. Have a look at the javadoc <a href="package-tree.html">tree |
| view</a> to get the broad picture.</p> |
| <h2>4. Example usage</h2> |
| <p>The following snippet fills a list, randomizes it, extracts the first half |
| of the elements, sums them up and prints the result. It is implemented entirely |
| with accessor methods.</p> |
| <table> |
| <td class="PRE"> |
| <pre> |
| int s = 1000000;<br>AbstractDoubleList list = new DoubleArrayList(); |
| for (int i=0; i<s; i++) { list.add((double)i); } |
| list.shuffle(); |
| AbstractDoubleList part = list.partFromTo(0,list.size()/2 - 1); |
| double sum = 0.0; |
| for (int i=0; i<part.size(); i++) { sum += part.get(i); } |
| log.info(sum); |
| </pre> |
| </td> |
| </table> |
| <p> For efficiency, all classes provide back doors to enable getting/setting the |
| backing array directly. In this way, the high level operations of these classes |
| can be used where appropriate, and one can switch to <tt>[]</tt>-array index |
| notations where necessary. The key methods for this are <tt>public <ElementType>[] |
| elements()</tt> and <tt>public void elements(<ElementType>[])</tt>. The |
| former trustingly returns the array it internally keeps to store the elements. |
| Holding this array in hand, we can use the <tt>[]</tt>-array operator to |
| perform iteration over large lists without needing to copy the array or paying |
| the performance penalty introduced by accessor methods. Alternatively any JAL |
| algorithm (or other algorithm) can operate on the returned primitive array. |
| The latter method forces a list to internally hold a user provided array. Using |
| this approach one can avoid needing to copy the elements into the list. |
| <p>As a consequence, operations on primitive arrays, Colt lists and JAL algorithms |
| can freely be mixed at zero-copy overhead. |
| <p> Note that such special treatment certainly breaks encapsulation. This functionality |
| is provided for performance reasons only and should only be used when absolutely |
| necessary. Here is the above example in mixed notation: |
| <table> |
| <td class="PRE"> |
| <pre> |
| int s = 1000000;<br>DoubleArrayList list = new DoubleArrayList(s); // list.size()==0, capacity==s |
| list.setSize(s); // list.size()==s<br>double[] values = list.elements(); |
| // zero copy, values.length==s<br>for (int i=0; i<s; i++) { values[i]=(double)i; } |
| list.shuffle(); |
| double sum = 0.0; |
| int limit = values.length/2; |
| for (int i=0; i<limit; i++) { sum += values[i]; } |
| log.info(sum); |
| </pre> |
| </td> |
| </table> |
| <p> Or even more compact using lists as algorithm objects: |
| <table> |
| <td class="PRE"> |
| <pre> |
| int s = 1000000;<br>double[] values = new double[s]; |
| for (int i=0; i<s; i++) { values[i]=(double)i; } |
| new DoubleArrayList(values).shuffle(); // zero-copy, shuffle via back door |
| double sum = 0.0; |
| int limit = values.length/2; |
| for (int i=0; i<limit; i++) { sum += values[i]; } |
| log.info(sum); |
| </pre> |
| </td> |
| </table> |
| <p> |
| <h2>5. Notes </h2> |
| <p>The quicksorts and mergesorts are the JDK 1.2 V1.26 algorithms, modified as |
| necessary to operate on the given data types. |
| </BODY> |
| </HTML></div> |
| </div> |
| <!-- ======= START OF BOTTOM NAVBAR ====== --> |
| <div class="bottomNav"><a name="navbar.bottom"> |
| <!-- --> |
| </a> |
| <div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div> |
| <a name="navbar.bottom.firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li><a href="../../../../../overview-summary.html">Overview</a></li> |
| <li class="navBarCell1Rev">Package</li> |
| <li>Class</li> |
| <li><a href="package-use.html">Use</a></li> |
| <li><a href="package-tree.html">Tree</a></li> |
| <li><a href="../../../../../deprecated-list.html">Deprecated</a></li> |
| <li><a href="../../../../../index-all.html">Index</a></li> |
| <li><a href="../../../../../help-doc.html">Help</a></li> |
| </ul> |
| </div> |
| <div class="subNav"> |
| <ul class="navList"> |
| <li><a href="../../../../../org/apache/mahout/math/jet/stat/package-summary.html">Prev Package</a></li> |
| <li><a href="../../../../../org/apache/mahout/math/map/package-summary.html">Next Package</a></li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="../../../../../index.html?org/apache/mahout/math/list/package-summary.html" target="_top">Frames</a></li> |
| <li><a href="package-summary.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_bottom"> |
| <li><a href="../../../../../allclasses-noframe.html">All Classes</a></li> |
| </ul> |
| <div> |
| <script type="text/javascript"><!-- |
| allClassesLink = document.getElementById("allclasses_navbar_bottom"); |
| if(window==top) { |
| allClassesLink.style.display = "block"; |
| } |
| else { |
| allClassesLink.style.display = "none"; |
| } |
| //--> |
| </script> |
| </div> |
| <a name="skip.navbar.bottom"> |
| <!-- --> |
| </a></div> |
| <!-- ======== END OF BOTTOM NAVBAR ======= --> |
| <p class="legalCopy"><small>Copyright © 2008–2017 <a href="http://www.apache.org/">The Apache Software Foundation</a>. All rights reserved.</small></p> |
| </body> |
| </html> |
