1:  package de.luschny.math.primes;
   2:   
   3:  import de.luschny.math.util.PositiveRange;
   4:   
   5:  import java.util.Iterator;
   6:   
   7:  /**
   8:   * An interface for iterating over a prime number sieve or over a subrange of
   9:   * the sieve.
  10:   * <p/>
  11:   * Typical use is: <blockquote>
  12:   * 
  13:   * <pre>
  14:   * IPrimeSieve sieve = new PrimeSieve(sieveLength);
  15:   * IPrimeIteration primes = sieve.getIteration();
  16:   * &lt;p/&gt;
  17:   *   // Java 1.5 Tiger-style
  18:   *   for (int prime : primes)
  19:   *   {
  20:   *      System.out.print(prime + &quot;,&quot;);
  21:   *   }
  22:   * </pre>
  23:   * 
  24:   * </blockquote>
  25:   * <p/>
  26:   * Caveat: IPrimeIteration inherits from java.util.Iterator the method 'remove'.
  27:   * This (optional operation) is usually not supported by an implementation of
  28:   * IPrimeIteration.
  29:   * 
  30:   * @author Peter Luschny
  31:   * @version 2004-09-12
  32:   */
  33:   
  34:  public interface IPrimeIteration extends Iterable<Integer>, Iterator<Integer>
  35:  {
  36:      /**
  37:       * Counts the number of primes in the iteration.
  38:       * 
  39:       * @return The number of primes in the iteration.
  40:       */
  41:   
  42:      int getNumberOfPrimes();
  43:   
  44:      /**
  45:       * Gives the interval [a,b] proceeded by the sieve. We call this interval
  46:       * the SieveRange of the iteration.
  47:       * 
  48:       * @return The range of integers, in which the prime numbers are searched.
  49:       * @see IPrimeIteration#getPrimeRange()
  50:       */
  51:   
  52:      PositiveRange getSieveRange();
  53:   
  54:      /**
  55:       * Gives the range of the indices of the prime numbers in the SieveRange of
  56:       * the iteration. We call this range the PrimeRange of the iteration.
  57:       * <p/>
  58:       * To understand the difference between "SieveRange" and "PrimeRange"
  59:       * better, let us consider the following example:
  60:       * <p/>
  61:       * <blockquote>
  62:       * 
  63:       * <pre>
  64:       * If the SieveRange is 10..20, then the PrimeRange is 5..8,
  65:       * because of the following table
  66:       * &lt;p/&gt;
  67:       *                    &lt;-     SieveRange           -&gt;
  68:       * 1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23
  69:       * x,1,2,x,3,x,4,x,x, x, 5, x, 6, x, x, x, 7, x, 8, x, x, x, 9
  70:       *                    &lt;-     PrimeRange           -&gt;
  71:       * &lt;p/&gt;
  72:       * Thus the smallest prime in the range 10..20 is the 5-th prime
  73:       * and the largest prime in this range is the 8-th prime.
  74:       * </pre>
  75:       * 
  76:       * </blockquote>
  77:       * 
  78:       * @return The range of indices of the primes.
  79:       */
  80:   
  81:      PositiveRange getPrimeRange();
  82:   
  83:      /**
  84:       * Computes the density of primes in the iteration.
  85:       * 
  86:       * @return Ratio of the number of primes relative to the number of all
  87:       *         integers in this iteration.
  88:       */
  89:   
  90:      double getPrimeDensity();
  91:   
  92:      /**
  93:       * Extracts the primes in the SieveRange of the iteration to an array.
  94:       * 
  95:       * @return An array containing the prime numbers in the iteration.
  96:       */
  97:   
  98:      int[] toArray();
  99:   
 100:      /**
 101:       * Three options for formatting the list of primes when printing them to a
 102:       * file.
 103:       */
 104:   
 105:      enum PrintOption
 106:      {
 107:   
 108:          /**
 109:           * A comma-separated list of the prime numbers in the iteration.
 110:           * <blockquote>
 111:           * 
 112:           * <pre>
 113:           *   Example output:
 114:           *   2,3,5,7,...
 115:           * </pre>
 116:           * 
 117:           * </blockquote>
 118:           */
 119:          CommaSeparated,
 120:   
 121:          /**
 122:           * A formated table of the prime numbers in the iteration.
 123:           * <p/>
 124:           * <blockquote>
 125:           * 
 126:           * <pre>
 127:           * Example output:
 128:           * &lt;p/&gt;
 129:           * SieveRange   [100,333] : 234
 130:           * PrimeRange   [ 26, 67] : 42
 131:           * PrimeDensity 0.1794871794871795
 132:           * &lt;p/&gt;
 133:           * &lt;26.&gt; 101 103 107 109 113 127 131 137 139 149 151
 134:           *       157 163 167 173 179 181 191 193 197 199
 135:           * &lt;47.&gt; 211 223 227 229 233 239 241 251 257 263 269
 136:           *       271 277 281 283 293
 137:           * &lt;63.&gt; 307 311 313 317 331
 138:           * </pre>
 139:           * 
 140:           * </blockquote>
 141:           */
 142:          FormattedText,
 143:   
 144:          /**
 145:           * The prime numbers as pairs (ordinal, prime) in Xml-format.
 146:           * <p/>
 147:           * <blockquote>
 148:           * 
 149:           * <pre>
 150:           * Example output:
 151:           * (26,101)
 152:           * (27,103)
 153:           * (28,107)
 154:           * </pre>
 155:           * 
 156:           * </blockquote>
 157:           */
 158:          Xml
 159:      }
 160:   
 161:      /**
 162:       * Saves the prime numbers in the SieveRange of the iteration to a file.
 163:       * 
 164:       * @param fileName
 165:       *            The name of the file the prime numbers are written to.
 166:       * @param format
 167:       *            Sets the type of formatting the output.
 168:       */
 169:   
 170:      void toFile(String fileName, PrintOption format);
 171:   
 172:  }