diff --git a/src/main/java/forge/quest/gui/QuestWinLoseHandler.java b/src/main/java/forge/quest/gui/QuestWinLoseHandler.java index 557ba9db811..74f651f00ee 100644 --- a/src/main/java/forge/quest/gui/QuestWinLoseHandler.java +++ b/src/main/java/forge/quest/gui/QuestWinLoseHandler.java @@ -34,7 +34,6 @@ import forge.quest.gui.main.QuestChallenge; import forge.quest.gui.main.QuestEvent; import forge.view.swing.WinLoseModeHandler; -// TODO: Auto-generated Javadoc /** *

* QuestWinLoseHandler. diff --git a/src/main/java/forge/view/swing/WinLoseModeHandler.java b/src/main/java/forge/view/swing/WinLoseModeHandler.java index e590fc5a73a..1e87b0693aa 100644 --- a/src/main/java/forge/view/swing/WinLoseModeHandler.java +++ b/src/main/java/forge/view/swing/WinLoseModeHandler.java @@ -37,7 +37,7 @@ public class WinLoseModeHandler { * Action performed when "quit" button is pressed in default win/lose UI. * */ - public final void actionOnQuit() { + public void actionOnQuit() { if (System.getenv("NG2") != null) { if (System.getenv("NG2").equalsIgnoreCase("true")) { String[] argz = {}; @@ -69,7 +69,7 @@ public class WinLoseModeHandler { * with other game modes. * */ - public final void startNextRound() { + public void startNextRound() { AllZone.getGameAction().newGame(Constant.Runtime.HumanDeck[0], Constant.Runtime.ComputerDeck[0]); } @@ -82,7 +82,7 @@ public class WinLoseModeHandler { * * @return true, if successful */ - public final boolean populateCustomPanel() { + public boolean populateCustomPanel() { return false; } diff --git a/src/main/java/net/slightlymagic/braids/util/ClumsyRunnable.java b/src/main/java/net/slightlymagic/braids/util/ClumsyRunnable.java index cbd4e55e154..3525c937ab3 100644 --- a/src/main/java/net/slightlymagic/braids/util/ClumsyRunnable.java +++ b/src/main/java/net/slightlymagic/braids/util/ClumsyRunnable.java @@ -4,5 +4,12 @@ package net.slightlymagic.braids.util; * Like Runnable, but it can throw any Exception. */ public interface ClumsyRunnable { - public void run() throws Exception; + + /** + * Run. + * + * @throws Exception + * the exception + */ + void run() throws Exception; } diff --git a/src/main/java/net/slightlymagic/braids/util/ImmutableIterableFrom.java b/src/main/java/net/slightlymagic/braids/util/ImmutableIterableFrom.java index 329b065fcbf..396dde98ddd 100644 --- a/src/main/java/net/slightlymagic/braids/util/ImmutableIterableFrom.java +++ b/src/main/java/net/slightlymagic/braids/util/ImmutableIterableFrom.java @@ -5,56 +5,66 @@ import java.util.Iterator; /** * Acts as both immutable Iterator and Iterable; remove method always throws * exception. + * + * @param + * the generic type */ public class ImmutableIterableFrom implements Iterable, Iterator { - private Iterator iterator; + private Iterator iterator; - /** - * Wrap an iterable so that it cannot be changed via - * the remove method. - * - * @param iterable the iterable to wrap - */ - public ImmutableIterableFrom(Iterable iterable) { - this.iterator = iterable.iterator(); - } + /** + * Wrap an iterable so that it cannot be changed via the remove method. + * + * @param iterable + * the iterable to wrap + */ + public ImmutableIterableFrom(final Iterable iterable) { + this.iterator = iterable.iterator(); + } - /** - * Wrap an iterator so that its container cannot be changed via - * the remove method. - * - * @param iterator the iterator to wrap - */ - public ImmutableIterableFrom(Iterator iterator) { - this.iterator = iterator; - } + /** + * Wrap an iterator so that its container cannot be changed via the remove + * method. + * + * @param iterator + * the iterator to wrap + */ + public ImmutableIterableFrom(final Iterator iterator) { + this.iterator = iterator; + } - /** - * This class acts as both an Iterable and an Iterator. - */ - public Iterator iterator() { - return this; - } + /** + * This class acts as both an Iterable and an Iterator. + * + * @return the iterator + */ + public final Iterator iterator() { + return this; + } - /** - * Returns hasNext from the wrapped [object's] iterator. - */ - public boolean hasNext() { - return iterator.hasNext(); - } + /** + * Returns hasNext from the wrapped [object's] iterator. + * + * @return true, if successful + */ + public final boolean hasNext() { + return iterator.hasNext(); + } - /** - * Returns next from the wrapped [object's] iterator. - */ - public T next() { - return iterator.next(); - } + /** + * Returns next from the wrapped [object's] iterator. + * + * @return the t + */ + public final T next() { + return iterator.next(); + } - /** - * Never succeeeds. - * @throws UnsupportedOperationException always. - */ - public void remove() { - throw new UnsupportedOperationException(); - } + /** + * Never succeeeds. + * + */ + public final void remove() { + throw new UnsupportedOperationException(); + } } diff --git a/src/main/java/net/slightlymagic/braids/util/NotImplementedError.java b/src/main/java/net/slightlymagic/braids/util/NotImplementedError.java index 1b426417bad..7b3d2564d67 100644 --- a/src/main/java/net/slightlymagic/braids/util/NotImplementedError.java +++ b/src/main/java/net/slightlymagic/braids/util/NotImplementedError.java @@ -4,7 +4,7 @@ package net.slightlymagic.braids.util; * This exception indicates the particular method (or part of a method) being * called has not been implemented; getting this exception is generally * considered a programming error. - * + * * Throwing this exception does not necessarily mean the method will be * implemented at any point in the future. */ @@ -22,10 +22,11 @@ public class NotImplementedError extends RuntimeException { /** * Indicates what has not been implemented. - * - * @param message indicates what exactly has not been implemented. - * May include information about future plans to implement the described - * section of code. + * + * @param message + * indicates what exactly has not been implemented. May include + * information about future plans to implement the described + * section of code. */ public NotImplementedError(final String message) { super(message); @@ -33,9 +34,10 @@ public class NotImplementedError extends RuntimeException { /** * Like the no-arg constructor, but with a cause parameter. - * - * @param cause the exception that caused this one to be thrown - * + * + * @param cause + * the exception that caused this one to be thrown + * * @see #NotImplementedError() */ public NotImplementedError(final Throwable cause) { @@ -44,13 +46,15 @@ public class NotImplementedError extends RuntimeException { /** * Like the String constructor, but with a cause parameter. - * - * @param message indicates what exactly has not been implemented. - * May include information about future plans to implement the described - * section of code. - * - * @param cause the exception that caused this one to be thrown - * + * + * @param message + * indicates what exactly has not been implemented. May include + * information about future plans to implement the described + * section of code. + * + * @param cause + * the exception that caused this one to be thrown + * * @see #NotImplementedError(String) */ public NotImplementedError(final String message, final Throwable cause) { diff --git a/src/main/java/net/slightlymagic/braids/util/UtilFunctions.java b/src/main/java/net/slightlymagic/braids/util/UtilFunctions.java index 6784db0ea22..1874c1976a1 100644 --- a/src/main/java/net/slightlymagic/braids/util/UtilFunctions.java +++ b/src/main/java/net/slightlymagic/braids/util/UtilFunctions.java @@ -19,12 +19,13 @@ public final class UtilFunctions { // empty } - /** * Throws a NullPointerException if param is null. - * - * @param paramName the name of the parameter; may be null - * @param param the parameter to test + * + * @param paramName + * the name of the parameter; may be null + * @param param + * the parameter to test */ public static void checkNotNull(final String paramName, final Object param) { if (param != null) { @@ -34,10 +35,16 @@ public final class UtilFunctions { NullPointerException exn = null; if (paramName == null) { - exn = new NullPointerException(); // NOPMD by Braids on 8/18/11 11:19 PM - } - else { - exn = new NullPointerException(paramName + " must not be null"); // NOPMD by Braids on 8/18/11 11:19 PM + exn = new NullPointerException(); // NOPMD by Braids on 8/18/11 + // 11:19 PM + } else { + exn = new NullPointerException(paramName + " must not be null"); // NOPMD + // by + // Braids + // on + // 8/18/11 + // 11:19 + // PM } // Doctor the exception to appear to come from the caller. @@ -48,43 +55,52 @@ public final class UtilFunctions { } /** - * Invoke the given Runnable in an Event Dispatch Thread and wait for it - * to finish; but try to use SwingUtilities.invokeLater instead whenever + * Invoke the given Runnable in an Event Dispatch Thread and wait for it to + * finish; but try to use SwingUtilities.invokeLater instead whenever * feasible. - * + * * Exceptions generated by SwingUtilities.invokeAndWait (if used), are * rethrown as RuntimeExceptions. - * + * + * @param proc + * the Runnable to run * @see javax.swing.SwingUtilities#invokeLater(Runnable) - * - * @param proc the Runnable to run */ - public static void invokeInEventDispatchThreadAndWait(final Runnable proc) { // NOPMD by Braids on 8/18/11 11:19 PM + public static void invokeInEventDispatchThreadAndWait(final Runnable proc) { // NOPMD + // by + // Braids + // on + // 8/18/11 + // 11:19 + // PM if (SwingUtilities.isEventDispatchThread()) { // Just run in the current thread. proc.run(); - } - else { + } else { try { SwingUtilities.invokeAndWait(proc); } catch (InterruptedException exn) { - throw new RuntimeException(exn); // NOPMD by Braids on 8/18/11 11:19 PM + throw new RuntimeException(exn); // NOPMD by Braids on 8/18/11 + // 11:19 PM } catch (InvocationTargetException exn) { - throw new RuntimeException(exn); // NOPMD by Braids on 8/18/11 11:19 PM + throw new RuntimeException(exn); // NOPMD by Braids on 8/18/11 + // 11:19 PM } } } /** - * Create an array from the (rest of) an iterator's output; - * this function is horribly inefficient. - * + * Create an array from the (rest of) an iterator's output; this function is + * horribly inefficient. + * * Please, only use it on small iterators. - * - * @param (inferred automatically) - * - * @param iter the iterator to traverse - * + * + * @param + * (inferred automatically) + * + * @param iter + * the iterator to traverse + * * @return an array of (the rest of) the iterator's values */ public static T[] iteratorToArray(final Iterator iter) { @@ -101,27 +117,28 @@ public final class UtilFunctions { return result; } - /** * Returns the rightmost portion of an array, Python-style. - * - * @param (inferred automatically) - * - * @param dstArray the array in which to place new items - * - * @param srcArray the array to copy (shallowly) - * - * @param startIndexIn if positive, the index (from the left) at which to - * start copying; if negative, we treat this as the index from the right. - * For example, calling this with startIndex = -2 returns the last two - * items in the array, if it has that many. - * + * + * @param + * (inferred automatically) + * + * @param dstArray + * the array in which to place new items + * + * @param srcArray + * the array to copy (shallowly) + * + * @param startIndexIn + * if positive, the index (from the left) at which to start + * copying; if negative, we treat this as the index from the + * right. For example, calling this with startIndex = -2 returns + * the last two items in the array, if it has that many. + * * @return a shallow copy of array starting at startIndex; this may return * an empty array if the startIndex is out of bounds. */ - public static T[] slice(final T[] dstArray, final T[] srcArray, - final int startIndexIn) - { + public static T[] slice(final T[] dstArray, final T[] srcArray, final int startIndexIn) { int startIndex = startIndexIn; if (startIndex < 0) { startIndex = srcArray.length + startIndex; @@ -131,55 +148,51 @@ public final class UtilFunctions { } if (dstArray == null) { - throw new NullPointerException(); // NOPMD by Braids on 8/18/11 11:19 PM + throw new NullPointerException(); // NOPMD by Braids on 8/18/11 + // 11:19 PM } if (srcArray == null) { - throw new NullPointerException(); // NOPMD by Braids on 8/18/11 11:19 PM + throw new NullPointerException(); // NOPMD by Braids on 8/18/11 + // 11:19 PM } final int resultLength = getSliceLength(srcArray, startIndex); if (dstArray.length != resultLength) { - throw new ArrayIndexOutOfBoundsException( - "First parameter must have length " + resultLength + throw new ArrayIndexOutOfBoundsException("First parameter must have length " + resultLength + ", but length is " + dstArray.length + "."); } int srcIx = startIndex; - for (int dstIx = 0; - dstIx < resultLength && srcIx < srcArray.length; - dstIx++, srcIx++) - { + for (int dstIx = 0; dstIx < resultLength && srcIx < srcArray.length; dstIx++, srcIx++) { dstArray[dstIx] = srcArray[srcIx]; } return dstArray; } - /** * Get a slice's length in preparation for taking a slice. - * - * I do not like the fact that I have to use this function, but - * Java left me with little choice. - * - * @see #slice(Object[], Object[], int) - * - * @param (inferred automatically) - * - * @param srcArray the array that would be copied (shallowly) - * - * @param startIndexIn if positive, the index (from the left) at which - * copying would start; if negative, we treat this as the index from the - * right. For example, calling this with startIndex = -2 computes the - * length if slice would return the last two items in the array, if it has - * that many. - * + * + * I do not like the fact that I have to use this function, but Java left me + * with little choice. + * + * @param + * (inferred automatically) + * @param srcArray + * the array that would be copied (shallowly) + * @param startIndexIn + * if positive, the index (from the left) at which copying would + * start; if negative, we treat this as the index from the right. + * For example, calling this with startIndex = -2 computes the + * length if slice would return the last two items in the array, + * if it has that many. * @return the length of the array that would result from calling - * slice(Object[], Object[], int) with the given srcArray and - * startIndex. + * slice(Object[], Object[], int) with the given srcArray and + * startIndex. + * @see #slice(Object[], Object[], int) */ public static int getSliceLength(final T[] srcArray, final int startIndexIn) { int startIndex = startIndexIn; @@ -195,34 +208,43 @@ public final class UtilFunctions { return resultLength; } - /** * Handles the boilerplate null and isinstance check for an equals method. - * + * * Example: + * * 

      * public boolean equals(Object obj) {
      *     MyClassName that = checkNullOrNotInstance(this, obj);
      *     if (that == null) {
      *         return false;
      *     }
-     *     //...
+     *     // ...
      * }
      *
- * - * @param (inferred automatically) - * - * @param goodInstance a non-null instance of type T; looks neater than - * passing in goodInstance.getClass() - * - * @param obj the object to test - * - * @return null if obj is null or not an instance of goodInstance's class; - * otherwise, we return obj cast to goodInstance's type + * + * @param + * (inferred automatically) + * + * @param goodInstance + * a non-null instance of type T; looks neater than passing in + * goodInstance.getClass() + * + * @param obj + * the object to test + * + * @return null if obj is null or not an instance of goodInstance's class; + * otherwise, we return obj cast to goodInstance's type */ public static T checkNullOrNotInstance(final T goodInstance, final Object obj) { if (goodInstance == null) { - throw new NullPointerException("first parameter must not be null"); // NOPMD by Braids on 8/18/11 11:19 PM + throw new NullPointerException("first parameter must not be null"); // NOPMD + // by + // Braids + // on + // 8/18/11 + // 11:19 + // PM } @SuppressWarnings("unchecked") @@ -246,13 +268,12 @@ public final class UtilFunctions { return result; } - - /** * Safely converts an object to a String. - * - * @param obj to convert; may be null - * + * + * @param obj + * to convert; may be null + * * @return "null" if obj is null, obj.toString() otherwise */ public static String safeToString(final Object obj) { @@ -260,8 +281,7 @@ public final class UtilFunctions { if (obj == null) { result = "null"; - } - else { + } else { result = obj.toString(); } @@ -270,33 +290,33 @@ public final class UtilFunctions { /** * Remove nulls and duplicate items from the list. - * + * * This may change the list's ordering. It uses the items' equals methods to * determine equality. - * + * * Advantages over HashSet: This consumes no unnecessary heap-memory, nor - * does it require objects to implement hashCode. It is OK if - * (o1.equals(o2) does not imply o1.hashCode() == o2.hashCode()). - * + * does it require objects to implement hashCode. It is OK if (o1.equals(o2) + * does not imply o1.hashCode() == o2.hashCode()). + * * Advantages over TreeSet: This does not require a comparator. - * - * Disadvantages over HashSet and TreeSet: This runs in O(n*n) time. - * - * @param (inferred automatically) - * - * @param list the list to modify; this is fastest with ArrayList. + * + * Disadvantages over HashSet and TreeSet: This runs in O(n*n) time. + * + * @param + * (inferred automatically) + * + * @param list + * the list to modify; this is fastest with ArrayList. */ public static void smartRemoveDuplicatesAndNulls(final List list) { // Get rid of pesky leading nulls. smartRemoveDuplicatesAndNullsHelper(list, 0, null); for (int earlierIx = 0; earlierIx < list.size(); earlierIx++) { - for (int laterIx = earlierIx + 1; laterIx < list.size(); laterIx++) - { + for (int laterIx = earlierIx + 1; laterIx < list.size(); laterIx++) { final T itemAtEarlierIx = list.get(earlierIx); - smartRemoveDuplicatesAndNullsHelper(list, laterIx, - itemAtEarlierIx); + smartRemoveDuplicatesAndNullsHelper(list, laterIx, itemAtEarlierIx); } } @@ -304,28 +324,25 @@ public final class UtilFunctions { /** * Helper method for smartRemoveDuplicatesAndNulls that is subject to - * change; if you call this directly, you do so at your own risk! - * - * @param (inferred automatically) - * - * @param list the list to modify; if all items from startIx to the end - * are either null or equal to objSeenPreviously, then we truncate the - * list just before startIx. - * - * @param startIx the index to examine; we only move items within the range - * of [startIx, list.size()-1]. - * - * @param objSeenPreviously the object with which to compare list[startIx]; - * may be null. + * change; if you call this directly, you do so at your own risk!. + * + * @param + * (inferred automatically) + * @param list + * the list to modify; if all items from startIx to the end are + * either null or equal to objSeenPreviously, then we truncate + * the list just before startIx. + * @param startIx + * the index to examine; we only move items within the range of + * [startIx, list.size()-1]. + * @param objSeenPreviously + * the object with which to compare list[startIx]; may be null. */ - public static void smartRemoveDuplicatesAndNullsHelper( - final List list, final int startIx, final T objSeenPreviously) - { + public static void smartRemoveDuplicatesAndNullsHelper(final List list, final int startIx, + final T objSeenPreviously) { while (startIx < list.size() - && (list.get(startIx) == null - || list.get(startIx) == objSeenPreviously - || list.get(startIx).equals(objSeenPreviously))) - { + && (list.get(startIx) == null || list.get(startIx) == objSeenPreviously || list.get(startIx).equals( + objSeenPreviously))) { final int lastItemIx = list.size() - 1; // Overwrite the item at laterIx with the one at the end, diff --git a/src/main/java/net/slightlymagic/braids/util/generator/FindNonDirectoriesSkipDotDirectoriesGenerator.java b/src/main/java/net/slightlymagic/braids/util/generator/FindNonDirectoriesSkipDotDirectoriesGenerator.java index 4b228891708..d32672eb3bf 100644 --- a/src/main/java/net/slightlymagic/braids/util/generator/FindNonDirectoriesSkipDotDirectoriesGenerator.java +++ b/src/main/java/net/slightlymagic/braids/util/generator/FindNonDirectoriesSkipDotDirectoriesGenerator.java @@ -1,61 +1,69 @@ /** Licensed under both the GPL and the Apache 2.0 License. */ package net.slightlymagic.braids.util.generator; +import java.io.File; + import com.google.code.jyield.Generator; import com.google.code.jyield.Yieldable; -import java.io.File; - /** * This is a generator over all of the non-directories residing in a given - * starting directory and all subdirectories of it that do NOT start with a - * dot; this prevents the code from descending into .svn directories. + * starting directory and all subdirectories of it that do NOT start with a dot; + * this prevents the code from descending into .svn directories. * * For documentation on Java-Yield and its generators, see * {@link com.google.code.jyield.Generator} */ public class FindNonDirectoriesSkipDotDirectoriesGenerator implements Generator { - private File startDir; + private File startDir; - /** - * Create a generator at a given starting directory. - * - * One can invoke this generator more than once by calling its generate - * method. - * - * @param startDir the directory to start in; we ignore this directory's - * name, so if it starts with a dot, we treat it as if it didn't. - */ - public FindNonDirectoriesSkipDotDirectoriesGenerator(File startDir) { - this.startDir = startDir; - } + /** + * Create a generator at a given starting directory. + * + * One can invoke this generator more than once by calling its generate + * method. + * + * @param startDir + * the directory to start in; we ignore this directory's name, so + * if it starts with a dot, we treat it as if it didn't. + */ + public FindNonDirectoriesSkipDotDirectoriesGenerator(final File startDir) { + this.startDir = startDir; + } - /** - * Standard generate method. - * - *

Yields results to the given Yieldable. Convert Generator instances to - * Iterables with YieldUtils.toIterable.

- * - * See {@link com.google.code.jyield.YieldUtils#toIterable(com.google.code.jyield.Generator)} - */ - public void generate(Yieldable yy) { - String[] list = startDir.list(); - - for (String filename : list) { - File entry = new File(startDir, filename); - - if (entry.isDirectory()) { - if (!filename.startsWith(".")) { - FindNonDirectoriesSkipDotDirectoriesGenerator child = new FindNonDirectoriesSkipDotDirectoriesGenerator(entry); - child.generate(yy); - child = null; - } - // else do nothing, because it's a dot directory - } - else { - // Use this instead of a return statement. - yy.yield(entry); - } - } - } + /** + * Standard generate method. + * + *

+ * Yields results to the given Yieldable. Convert Generator instances to + * Iterables with YieldUtils.toIterable. + *

+ * + * See + * {@link com.google.code.jyield.YieldUtils#toIterable(com.google.code.jyield.Generator)} + * + * @param yy + * the yy + */ + public final void generate(final Yieldable yy) { + String[] list = startDir.list(); + + for (String filename : list) { + File entry = new File(startDir, filename); + + if (entry.isDirectory()) { + if (!filename.startsWith(".")) { + FindNonDirectoriesSkipDotDirectoriesGenerator child = + new FindNonDirectoriesSkipDotDirectoriesGenerator( + entry); + child.generate(yy); + child = null; + } + // else do nothing, because it's a dot directory + } else { + // Use this instead of a return statement. + yy.yield(entry); + } + } + } } diff --git a/src/main/java/net/slightlymagic/braids/util/generator/GeneratorFromArray.java b/src/main/java/net/slightlymagic/braids/util/generator/GeneratorFromArray.java index 6b082f56429..72ed7a72f1c 100644 --- a/src/main/java/net/slightlymagic/braids/util/generator/GeneratorFromArray.java +++ b/src/main/java/net/slightlymagic/braids/util/generator/GeneratorFromArray.java @@ -4,33 +4,43 @@ import com.google.code.jyield.Generator; import com.google.code.jyield.Yieldable; /** - * Creates a Generator from an array; generators are a handy - * substitute for passing around and creating temporary - * lists, collections, and arrays. + * Creates a Generator from an array; generators are a handy substitute for + * passing around and creating temporary lists, collections, and arrays. * - * {@link com.google.code.jyield.Generator} + * @param + * the generic type {@link com.google.code.jyield.Generator} */ public class GeneratorFromArray implements Generator { - private T[] array; + private T[] array; - /** - * Create a Generator from an array - * - * @param array from which to generate items - */ - public GeneratorFromArray(T[] array) { - this.array = array; - } + /** + * Create a Generator from an array. + * + * @param array + * from which to generate items + */ + public GeneratorFromArray(final T[] array) { + this.array = array; + } - @Override - /** - * Submits all of the array's elements to the yieldable. - * - * @param yy the yieldable which receives the elements - */ - public void generate(Yieldable yy) { - for (T item : array) { - yy.yield(item); - } - } + /* + * (non-Javadoc) + * + * @see + * com.google.code.jyield.Generator#generate(com.google.code.jyield.Yieldable + * ) + */ + + /** + * Submits all of the array's elements to the yieldable. + * + * @param yy + * the yieldable which receives the elements + */ + @Override + public final void generate(final Yieldable yy) { + for (T item : array) { + yy.yield(item); + } + } } diff --git a/src/main/java/net/slightlymagic/braids/util/generator/GeneratorFunctions.java b/src/main/java/net/slightlymagic/braids/util/generator/GeneratorFunctions.java index 6d0a47e8ed7..fca78c5c37c 100644 --- a/src/main/java/net/slightlymagic/braids/util/generator/GeneratorFunctions.java +++ b/src/main/java/net/slightlymagic/braids/util/generator/GeneratorFunctions.java @@ -1,204 +1,215 @@ /** Licensed under both the GPL and the Apache 2.0 License. */ package net.slightlymagic.braids.util.generator; -import com.google.code.jyield.Generator; -import com.google.code.jyield.YieldUtils; -import com.google.code.jyield.Yieldable; -import net.slightlymagic.braids.util.lambda.Lambda1; - import java.util.ArrayList; import java.util.NoSuchElementException; +import net.slightlymagic.braids.util.lambda.Lambda1; + +import com.google.code.jyield.Generator; +import com.google.code.jyield.YieldUtils; +import com.google.code.jyield.Yieldable; + /** - * For documentation on Java-Yield and its generators, see + * For documentation on Java-Yield and its generators, see. + * * {@link com.google.code.jyield.Generator}. */ public final class GeneratorFunctions { - /** - * Do not instantiate. - */ - private GeneratorFunctions() { - ; - } + /** + * Do not instantiate. + */ + private GeneratorFunctions() { + } - /** - * Estimate the number of items in this generator by traversing all of its - * elements. - * - * Note this only works on a generator that can be reinstantiated once it - * has been traversed. This is only an estimate, because a generator's size - * may vary been traversals. This is especially true if the generator - * relies on external resources, such as a file system. - * - * If you call this on an infinite generator, this method will never - * return. - * - * @return the estimated number of items provided by this generator - */ - public static long estimateSize(Generator gen) { - long result = 0; - for (@SuppressWarnings("unused") T ignored : YieldUtils.toIterable(gen)) - { - result++; - } - - return result; - } + /** + * Estimate the number of items in this generator by traversing all of its + * elements. + * + * Note this only works on a generator that can be reinstantiated once it + * has been traversed. This is only an estimate, because a generator's size + * may vary been traversals. This is especially true if the generator relies + * on external resources, such as a file system. + * + * If you call this on an infinite generator, this method will never return. + * + * @param + * the generic type + * @param gen + * the gen + * @return the estimated number of items provided by this generator + */ + public static long estimateSize(final Generator gen) { + long result = 0; + for (@SuppressWarnings("unused") + T ignored : YieldUtils.toIterable(gen)) + { + result++; + } - /** - * Highly efficient means of filtering a long or infinite sequence. - * - * @param any type - * - * @param predicate a Lambda (function) whose apply method takes an object - * of type and returns a Boolean. If it returns false or null, the - * item from the inputGenerator is not yielded by this Generator; - * if predicate.apply returns true, then this Generator does - * yield the value. - * - * @param inputGenerator the sequence upon which we operate - * - * @return a generator which produces a subset <= the inputGenerator - */ - public static Generator filterGenerator( - final Lambda1 predicate, final Generator inputGenerator) - { - Generator result = new Generator() { + return result; + } - @Override - public void generate(final Yieldable outputYield) { + /** + * Highly efficient means of filtering a long or infinite sequence. + * + * @param + * any type + * + * @param predicate + * a Lambda (function) whose apply method takes an object of type + * and returns a Boolean. If it returns false or null, the + * item from the inputGenerator is not yielded by this Generator; + * if predicate.apply returns true, then this Generator + * does yield the value. + * + * @param inputGenerator + * the sequence upon which we operate + * + * @return a generator which produces a subset <= the inputGenerator + */ + public static Generator filterGenerator(final Lambda1 predicate, + final Generator inputGenerator) + { + Generator result = new Generator() { - Yieldable inputYield = new Yieldable() { - Boolean pResult; - - @Override - public void yield(T input) { - pResult = predicate.apply(input); - if (pResult != null && pResult) { - outputYield.yield(input); - } - } - }; - - inputGenerator.generate(inputYield); - } - - }; - - return result; - } + @Override + public void generate(final Yieldable outputYield) { - /** - * Highly efficient means of applying a transform to a long or infinite - * sequence. - * - * @param any type - * - * @param transform a Lambda (function) whose apply method takes an object - * of type and returns an object of the same type. This transforms - * the values from the inputGenerator into this Generator. - * - * @param inputGenerator the sequence upon which we operate - * - * @return a generator that yields transform.apply's return value for - * each item in the inputGenerator - */ - public static Generator transformGenerator( - final Lambda1 transform, final Generator inputGenerator) - { - Generator result = new Generator() { + Yieldable inputYield = new Yieldable() { + Boolean pResult; - @Override - public void generate(final Yieldable outputYield) { + @Override + public void yield(final T input) { + pResult = predicate.apply(input); + if (pResult != null && pResult) { + outputYield.yield(input); + } + } + }; - Yieldable inputYield = new Yieldable() { - @Override - public void yield(T input) { - outputYield.yield(transform.apply(input)); - } - }; - - inputGenerator.generate(inputYield); - } - - }; - - return result; - } + inputGenerator.generate(inputYield); + } - /** - * Forces a generator to be completely evaluated into a temporary data - * structure, then returns the generator over that same structure. - * - * This effectively returns the same Generator, but it is a faster one. - * This trades away heap space for reduced CPU intensity. This is - * particuarly helpful if you know that a Generator is going to be - * totally evaluated more than once in the near future. - * - * @param inferred automatically - * - * @param unevaluated a Generator of T instances - * - * @return the equivalent Generator, except that the result's generate - * method can be invoked multiple times for fast results. - */ - public static Generator solidify(Generator unevaluated) { + }; + + return result; + } + + /** + * Highly efficient means of applying a transform to a long or infinite + * sequence. + * + * @param + * any type + * + * @param transform + * a Lambda (function) whose apply method takes an object of type + * and returns an object of the same type. This transforms + * the values from the inputGenerator into this Generator. + * + * @param inputGenerator + * the sequence upon which we operate + * + * @return a generator that yields transform.apply's return value for each + * item in the inputGenerator + */ + public static Generator transformGenerator(final Lambda1 transform, final Generator inputGenerator) + { + Generator result = new Generator() { + + @Override + public void generate(final Yieldable outputYield) { + + Yieldable inputYield = new Yieldable() { + @Override + public void yield(final T input) { + outputYield.yield(transform.apply(input)); + } + }; + + inputGenerator.generate(inputYield); + } + + }; + + return result; + } + + /** + * Forces a generator to be completely evaluated into a temporary data + * structure, then returns the generator over that same structure. + * + * This effectively returns the same Generator, but it is a faster one. This + * trades away heap space for reduced CPU intensity. This is particuarly + * helpful if you know that a Generator is going to be totally evaluated + * more than once in the near future. + * + * @param + * inferred automatically + * + * @param unevaluated + * a Generator of T instances + * + * @return the equivalent Generator, except that the result's generate + * method can be invoked multiple times for fast results. + */ + public static Generator solidify(final Generator unevaluated) { ArrayList solidTmp = YieldUtils.toArrayList(unevaluated); solidTmp.trimToSize(); return YieldUtils.toGenerator(solidTmp); - } + } - /** - * Select an item at random from a Generator; this causes the entire - * Generator to be evaluated once, but only once. - * - * @param generator - * the generator from which to select a random item - * - * @return an item chosen at random from the generator; this may be null, if - * the generator contains null items. - * - * @throws NoSuchElementException - * if the generator has no contents - */ - public static T selectRandom(Generator generator) - throws NoSuchElementException - { - /* - * This algorithm requires some explanation. Each time we encounter a - * new item from the generator, we determine via random chance if the - * item is the one we select. At the end of each iteration, we have a - * candidate, and we have a count of the number of items encountered so - * far. Each iteration has a 1/n chance of replacing the candidate with - * the current item, where n is the number of items encountered so far. - * This allows us to randomly select an item from the generated contents - * with an equal distribution; and we don't have to count the number of - * items first! - */ + /** + * Select an item at random from a Generator; this causes the entire + * Generator to be evaluated once, but only once. + * + * @param + * the generic type + * @param generator + * the generator from which to select a random item + * @return an item chosen at random from the generator; this may be null, if + * the generator contains null items. + * @throws NoSuchElementException + * if the generator has no contents + */ + public static T selectRandom(final Generator generator) throws NoSuchElementException + { + /* + * This algorithm requires some explanation. Each time we encounter a + * new item from the generator, we determine via random chance if the + * item is the one we select. At the end of each iteration, we have a + * candidate, and we have a count of the number of items encountered so + * far. Each iteration has a 1/n chance of replacing the candidate with + * the current item, where n is the number of items encountered so far. + * This allows us to randomly select an item from the generated contents + * with an equal distribution; and we don't have to count the number of + * items first! + */ - int n = 0; - T candidate = null; - - for (T item : YieldUtils.toIterable(generator)) { - n++; - int rand = (int) (Math.random() * n); - // At this point, 0 <= rand < n. - rand++; // Now, 1 <= rand <= n. - - if (rand == 1) { - // We rolled a 1 on an n-sided die. We have a new candidate! - // Note that on the first iteration, this always happens, - // because n = 1. - candidate = item; - } - } + int n = 0; + T candidate = null; - if (n == 0) { - // There were no items in the generator! - throw new NoSuchElementException("generator is empty"); - } + for (T item : YieldUtils.toIterable(generator)) { + n++; + int rand = (int) (Math.random() * n); + // At this point, 0 <= rand < n. + rand++; // Now, 1 <= rand <= n. - return candidate; - } + if (rand == 1) { + // We rolled a 1 on an n-sided die. We have a new candidate! + // Note that on the first iteration, this always happens, + // because n = 1. + candidate = item; + } + } + + if (n == 0) { + // There were no items in the generator! + throw new NoSuchElementException("generator is empty"); + } + + return candidate; + } }