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: * <p/>
17: * // Java 1.5 Tiger-style
18: * for (int prime : primes)
19: * {
20: * System.out.print(prime + ",");
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: * <p/>
67: * <- SieveRange ->
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: * <- PrimeRange ->
71: * <p/>
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: * <p/>
129: * SieveRange [100,333] : 234
130: * PrimeRange [ 26, 67] : 42
131: * PrimeDensity 0.1794871794871795
132: * <p/>
133: * <26.> 101 103 107 109 113 127 131 137 139 149 151
134: * 157 163 167 173 179 181 191 193 197 199
135: * <47.> 211 223 227 229 233 239 241 251 257 263 269
136: * 271 277 281 283 293
137: * <63.> 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: }