Files
pj2/doc/edu/rit/util/RandomSubset.html
2016-04-27 01:07:35 -04:00

436 lines
22 KiB
HTML

<!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 (version 1.7.0_51) on Wed Apr 06 13:11:12 EDT 2016 -->
<title>RandomSubset (Parallel Java 2 Library Documentation)</title>
<meta name="date" content="2016-04-06">
<link rel="stylesheet" type="text/css" href="../../../stylesheet.css" title="Style">
</head>
<body>
<script type="text/javascript"><!--
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="RandomSubset (Parallel Java 2 Library Documentation)";
}
//-->
</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="topNav"><a name="navbar_top">
<!-- -->
</a><a href="#skip-navbar_top" title="Skip navigation links"></a><a name="navbar_top_firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="class-use/RandomSubset.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-files/index-1.html">Index</a></li>
<li><a href="../../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../edu/rit/util/Random.html" title="class in edu.rit.util"><span class="strong">Prev Class</span></a></li>
<li><a href="../../../edu/rit/util/Searching.html" title="class in edu.rit.util"><span class="strong">Next Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../index.html?edu/rit/util/RandomSubset.html" target="_top">Frames</a></li>
<li><a href="RandomSubset.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>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Nested&nbsp;|&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li><a href="#constructor_summary">Constr</a>&nbsp;|&nbsp;</li>
<li><a href="#method_summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li><a href="#constructor_detail">Constr</a>&nbsp;|&nbsp;</li>
<li><a href="#method_detail">Method</a></li>
</ul>
</div>
<a name="skip-navbar_top">
<!-- -->
</a></div>
<!-- ========= END OF TOP NAVBAR ========= -->
<!-- ======== START OF CLASS DATA ======== -->
<div class="header">
<div class="subTitle">edu.rit.util</div>
<h2 title="Class RandomSubset" class="title">Class RandomSubset</h2>
</div>
<div class="contentContainer">
<ul class="inheritance">
<li><a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true" title="class or interface in java.lang">java.lang.Object</a></li>
<li>
<ul class="inheritance">
<li>edu.rit.util.RandomSubset</li>
</ul>
</li>
</ul>
<div class="description">
<ul class="blockList">
<li class="blockList">
<dl>
<dt>All Implemented Interfaces:</dt>
<dd><a href="http://docs.oracle.com/javase/7/docs/api/java/util/Iterator.html?is-external=true" title="class or interface in java.util">Iterator</a>&lt;<a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Integer.html?is-external=true" title="class or interface in java.lang">Integer</a>&gt;</dd>
</dl>
<hr>
<br>
<pre>public class <span class="strong">RandomSubset</span>
extends <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true" title="class or interface in java.lang">Object</a>
implements <a href="http://docs.oracle.com/javase/7/docs/api/java/util/Iterator.html?is-external=true" title="class or interface in java.util">Iterator</a>&lt;<a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Integer.html?is-external=true" title="class or interface in java.lang">Integer</a>&gt;</pre>
<div class="block">Class RandomSubset provides an object that generates a random subset of a set
of integers. The original set consists of the integers from 0 to
<I>N</I>&minus;1 inclusive. The subset consists of integers chosen at random
without replacement from the original set; each member of the original set is
equally likely to be chosen. Class RandomSubset is an Iterator that visits
the elements of the original set in a random order; each <TT>next()</TT>
method call returns another element of the subset.
<P>
Calling the <TT>remove(i)</TT> method one or more times removes the given
integers from the original set. Those integers will not be chosen for the
random subset.
<P>
Class RandomSubset is layered on top of a pseudorandom number generator
(PRNG), an instance of class <a href="../../../edu/rit/util/Random.html" title="class in edu.rit.util">Random</a>. Each
time the <TT>next()</TT> method is called, one random number is consumed from
the underlying PRNG.
<P>
Class RandomSubset has two different implementations with different storage
requirements. The implementation is specified with a constructor argument.
<UL>
<P><LI>
The <I>sparse</I> implementation requires less storage when the size of the
random subset (the number of <TT>next()</TT> method calls) is a small
fraction of the size of the original set (<I>N</I>).
<P><LI>
The <I>dense</I> implementation requires less storage when the size of the
random subset is a large fraction of the size of the original set.
</UL></div>
</li>
</ul>
</div>
<div class="summary">
<ul class="blockList">
<li class="blockList">
<!-- ======== CONSTRUCTOR SUMMARY ======== -->
<ul class="blockList">
<li class="blockList"><a name="constructor_summary">
<!-- -->
</a>
<h3>Constructor Summary</h3>
<table class="overviewSummary" border="0" cellpadding="3" cellspacing="0" summary="Constructor Summary table, listing constructors, and an explanation">
<caption><span>Constructors</span><span class="tabEnd">&nbsp;</span></caption>
<tr>
<th class="colOne" scope="col">Constructor and Description</th>
</tr>
<tr class="altColor">
<td class="colOne"><code><strong><a href="../../../edu/rit/util/RandomSubset.html#RandomSubset(edu.rit.util.Random, int)">RandomSubset</a></strong>(<a href="../../../edu/rit/util/Random.html" title="class in edu.rit.util">Random</a>&nbsp;prng,
int&nbsp;N)</code>
<div class="block">Construct a new random subset object for the original set consisting of
the integers from 0 through <I>N</I>&minus;1 inclusive.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colOne"><code><strong><a href="../../../edu/rit/util/RandomSubset.html#RandomSubset(edu.rit.util.Random, int, boolean)">RandomSubset</a></strong>(<a href="../../../edu/rit/util/Random.html" title="class in edu.rit.util">Random</a>&nbsp;prng,
int&nbsp;N,
boolean&nbsp;dense)</code>
<div class="block">Construct a new random subset object for the original set consisting of
the integers from 0 through <I>N</I>&minus;1 inclusive.</div>
</td>
</tr>
</table>
</li>
</ul>
<!-- ========== METHOD SUMMARY =========== -->
<ul class="blockList">
<li class="blockList"><a name="method_summary">
<!-- -->
</a>
<h3>Method Summary</h3>
<table class="overviewSummary" border="0" cellpadding="3" cellspacing="0" summary="Method Summary table, listing methods, and an explanation">
<caption><span>Methods</span><span class="tabEnd">&nbsp;</span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colLast" scope="col">Method and Description</th>
</tr>
<tr class="altColor">
<td class="colFirst"><code>boolean</code></td>
<td class="colLast"><code><strong><a href="../../../edu/rit/util/RandomSubset.html#hasNext()">hasNext</a></strong>()</code>
<div class="block">Determine whether there are more integers in the random subset.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code><a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Integer.html?is-external=true" title="class or interface in java.lang">Integer</a></code></td>
<td class="colLast"><code><strong><a href="../../../edu/rit/util/RandomSubset.html#next()">next</a></strong>()</code>
<div class="block">Returns the next integer in the random subset.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><code>void</code></td>
<td class="colLast"><code><strong><a href="../../../edu/rit/util/RandomSubset.html#remove()">remove</a></strong>()</code>
<div class="block">Unsupported operation.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code><a href="../../../edu/rit/util/RandomSubset.html" title="class in edu.rit.util">RandomSubset</a></code></td>
<td class="colLast"><code><strong><a href="../../../edu/rit/util/RandomSubset.html#remove(int)">remove</a></strong>(int&nbsp;i)</code>
<div class="block">Remove the given integer from the original set.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><code>void</code></td>
<td class="colLast"><code><strong><a href="../../../edu/rit/util/RandomSubset.html#restart()">restart</a></strong>()</code>
<div class="block">Restart this random subset's iteration.</div>
</td>
</tr>
</table>
<ul class="blockList">
<li class="blockList"><a name="methods_inherited_from_class_java.lang.Object">
<!-- -->
</a>
<h3>Methods inherited from class&nbsp;java.lang.<a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true" title="class or interface in java.lang">Object</a></h3>
<code><a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#clone()" title="class or interface in java.lang">clone</a>, <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#equals(java.lang.Object)" title="class or interface in java.lang">equals</a>, <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#finalize()" title="class or interface in java.lang">finalize</a>, <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#getClass()" title="class or interface in java.lang">getClass</a>, <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#hashCode()" title="class or interface in java.lang">hashCode</a>, <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#notify()" title="class or interface in java.lang">notify</a>, <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#notifyAll()" title="class or interface in java.lang">notifyAll</a>, <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#toString()" title="class or interface in java.lang">toString</a>, <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#wait()" title="class or interface in java.lang">wait</a>, <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#wait(long)" title="class or interface in java.lang">wait</a>, <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#wait(long, int)" title="class or interface in java.lang">wait</a></code></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div class="details">
<ul class="blockList">
<li class="blockList">
<!-- ========= CONSTRUCTOR DETAIL ======== -->
<ul class="blockList">
<li class="blockList"><a name="constructor_detail">
<!-- -->
</a>
<h3>Constructor Detail</h3>
<a name="RandomSubset(edu.rit.util.Random, int)">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>RandomSubset</h4>
<pre>public&nbsp;RandomSubset(<a href="../../../edu/rit/util/Random.html" title="class in edu.rit.util">Random</a>&nbsp;prng,
int&nbsp;N)</pre>
<div class="block">Construct a new random subset object for the original set consisting of
the integers from 0 through <I>N</I>&minus;1 inclusive. The sparse
implementation is used.</div>
<dl><dt><span class="strong">Parameters:</span></dt><dd><code>prng</code> - Underlying PRNG.</dd><dd><code>N</code> - Size of original set.</dd>
<dt><span class="strong">Throws:</span></dt>
<dd><code><a href="http://docs.oracle.com/javase/7/docs/api/java/lang/NullPointerException.html?is-external=true" title="class or interface in java.lang">NullPointerException</a></code> - (unchecked exception) Thrown if <TT>prng</TT> is null.</dd>
<dd><code><a href="http://docs.oracle.com/javase/7/docs/api/java/lang/IllegalArgumentException.html?is-external=true" title="class or interface in java.lang">IllegalArgumentException</a></code> - (unchecked exception) Thrown if <I>N</I> &lt; 0.</dd></dl>
</li>
</ul>
<a name="RandomSubset(edu.rit.util.Random, int, boolean)">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>RandomSubset</h4>
<pre>public&nbsp;RandomSubset(<a href="../../../edu/rit/util/Random.html" title="class in edu.rit.util">Random</a>&nbsp;prng,
int&nbsp;N,
boolean&nbsp;dense)</pre>
<div class="block">Construct a new random subset object for the original set consisting of
the integers from 0 through <I>N</I>&minus;1 inclusive. If <TT>dense</TT>
is false, the sparse implementation is used. If <TT>dense</TT> is true,
the dense implementation is used.</div>
<dl><dt><span class="strong">Parameters:</span></dt><dd><code>prng</code> - Underlying PRNG.</dd><dd><code>N</code> - Size of original set.</dd><dd><code>dense</code> - False to use the sparse implementation, true to use the
dense implementation.</dd>
<dt><span class="strong">Throws:</span></dt>
<dd><code><a href="http://docs.oracle.com/javase/7/docs/api/java/lang/NullPointerException.html?is-external=true" title="class or interface in java.lang">NullPointerException</a></code> - (unchecked exception) Thrown if <TT>prng</TT> is null.</dd>
<dd><code><a href="http://docs.oracle.com/javase/7/docs/api/java/lang/IllegalArgumentException.html?is-external=true" title="class or interface in java.lang">IllegalArgumentException</a></code> - (unchecked exception) Thrown if <I>N</I> &lt; 0.</dd></dl>
</li>
</ul>
</li>
</ul>
<!-- ============ METHOD DETAIL ========== -->
<ul class="blockList">
<li class="blockList"><a name="method_detail">
<!-- -->
</a>
<h3>Method Detail</h3>
<a name="hasNext()">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>hasNext</h4>
<pre>public&nbsp;boolean&nbsp;hasNext()</pre>
<div class="block">Determine whether there are more integers in the random subset.</div>
<dl>
<dt><strong>Specified by:</strong></dt>
<dd><code><a href="http://docs.oracle.com/javase/7/docs/api/java/util/Iterator.html?is-external=true#hasNext()" title="class or interface in java.util">hasNext</a></code>&nbsp;in interface&nbsp;<code><a href="http://docs.oracle.com/javase/7/docs/api/java/util/Iterator.html?is-external=true" title="class or interface in java.util">Iterator</a>&lt;<a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Integer.html?is-external=true" title="class or interface in java.lang">Integer</a>&gt;</code></dd>
<dt><span class="strong">Returns:</span></dt><dd>True if there are more integers in the random subset, false if
all the integers in the original set have been used up.</dd></dl>
</li>
</ul>
<a name="next()">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>next</h4>
<pre>public&nbsp;<a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Integer.html?is-external=true" title="class or interface in java.lang">Integer</a>&nbsp;next()</pre>
<div class="block">Returns the next integer in the random subset.</div>
<dl>
<dt><strong>Specified by:</strong></dt>
<dd><code><a href="http://docs.oracle.com/javase/7/docs/api/java/util/Iterator.html?is-external=true#next()" title="class or interface in java.util">next</a></code>&nbsp;in interface&nbsp;<code><a href="http://docs.oracle.com/javase/7/docs/api/java/util/Iterator.html?is-external=true" title="class or interface in java.util">Iterator</a>&lt;<a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Integer.html?is-external=true" title="class or interface in java.lang">Integer</a>&gt;</code></dd>
<dt><span class="strong">Returns:</span></dt><dd>Next integer in the random subset.</dd>
<dt><span class="strong">Throws:</span></dt>
<dd><code><a href="http://docs.oracle.com/javase/7/docs/api/java/util/NoSuchElementException.html?is-external=true" title="class or interface in java.util">NoSuchElementException</a></code> - (unchecked exception) Thrown if all the integers in the original set
have been used up.</dd></dl>
</li>
</ul>
<a name="remove()">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>remove</h4>
<pre>public&nbsp;void&nbsp;remove()</pre>
<div class="block">Unsupported operation.</div>
<dl>
<dt><strong>Specified by:</strong></dt>
<dd><code><a href="http://docs.oracle.com/javase/7/docs/api/java/util/Iterator.html?is-external=true#remove()" title="class or interface in java.util">remove</a></code>&nbsp;in interface&nbsp;<code><a href="http://docs.oracle.com/javase/7/docs/api/java/util/Iterator.html?is-external=true" title="class or interface in java.util">Iterator</a>&lt;<a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Integer.html?is-external=true" title="class or interface in java.lang">Integer</a>&gt;</code></dd>
<dt><span class="strong">Throws:</span></dt>
<dd><code><a href="http://docs.oracle.com/javase/7/docs/api/java/lang/UnsupportedOperationException.html?is-external=true" title="class or interface in java.lang">UnsupportedOperationException</a></code> - (unchecked exception) Thrown always.</dd></dl>
</li>
</ul>
<a name="remove(int)">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>remove</h4>
<pre>public&nbsp;<a href="../../../edu/rit/util/RandomSubset.html" title="class in edu.rit.util">RandomSubset</a>&nbsp;remove(int&nbsp;i)</pre>
<div class="block">Remove the given integer from the original set.
<P>
If <TT>i</TT> has already been removed from the original set, either by a
<TT>remove(i)</TT> method call, or by a <TT>next()</TT> method call that
returned <TT>i</TT>, then this method does nothing.</div>
<dl><dt><span class="strong">Parameters:</span></dt><dd><code>i</code> - Integer to remove.</dd>
<dt><span class="strong">Returns:</span></dt><dd>This random subset object.</dd>
<dt><span class="strong">Throws:</span></dt>
<dd><code><a href="http://docs.oracle.com/javase/7/docs/api/java/lang/IllegalArgumentException.html?is-external=true" title="class or interface in java.lang">IllegalArgumentException</a></code> - (unchecked exception) Thrown if <TT>i</TT> is not in the range 0
through <I>N</I>&minus;1 inclusive.</dd></dl>
</li>
</ul>
<a name="restart()">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>restart</h4>
<pre>public&nbsp;void&nbsp;restart()</pre>
<div class="block">Restart this random subset's iteration. The original set is reset to
contain all the integers from 0 through <I>N</I>&minus;1 inclusive. If
integers had been removed from the original set by calling the
<TT>remove(i)</TT> method, those integers must be removed again by
calling the <TT>remove(i)</TT> method again. The iteration is restarted,
and calling the <TT>next()</TT> method will yield a different random
subset.
<P>
The <TT>restart()</TT> method lets you generate multiple random subsets
from the same original set using the same RandomSubset object. This
avoids the multiple storage allocations that would take place when
creating multiple RandomSubset objects. This in turn can reduce the
running time, especially when <I>N</I> is large.</div>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<!-- ========= END OF CLASS DATA ========= -->
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav"><a name="navbar_bottom">
<!-- -->
</a><a href="#skip-navbar_bottom" title="Skip navigation links"></a><a name="navbar_bottom_firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="class-use/RandomSubset.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-files/index-1.html">Index</a></li>
<li><a href="../../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../edu/rit/util/Random.html" title="class in edu.rit.util"><span class="strong">Prev Class</span></a></li>
<li><a href="../../../edu/rit/util/Searching.html" title="class in edu.rit.util"><span class="strong">Next Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../index.html?edu/rit/util/RandomSubset.html" target="_top">Frames</a></li>
<li><a href="RandomSubset.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>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Nested&nbsp;|&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li><a href="#constructor_summary">Constr</a>&nbsp;|&nbsp;</li>
<li><a href="#method_summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li>Field&nbsp;|&nbsp;</li>
<li><a href="#constructor_detail">Constr</a>&nbsp;|&nbsp;</li>
<li><a href="#method_detail">Method</a></li>
</ul>
</div>
<a name="skip-navbar_bottom">
<!-- -->
</a></div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
<p class="legalCopy"><small><FONT SIZE="-2">Copyright &copy; 2013&ndash;2016 by Alan Kaminsky. All rights reserved. Send comments to ark</FONT><FONT SIZE="1" COLOR="#FFFFFF">&shy;</FONT><FONT SIZE="-2">&#64;</FONT><FONT SIZE="1" COLOR="#FFFFFF">&shy;</FONT><FONT SIZE="-2">cs.rit.edu.</FONT></small></p>
</body>
</html>