Package edu.gvsu.kurmasz.warszawa.listgen

Class Wildcard

java.lang.Object
edu.gvsu.kurmasz.warszawa.listgen.IntegerListGenerator
edu.gvsu.kurmasz.warszawa.listgen.Wildcard
public class Wildcard
extends IntegerListGenerator
Generate lists of integers based on an integer with "wildcards". For example, the binary value 10** is expanded into the set {1000, 1001, 1010, 1011}.
Author:
Zachary Kurmas

  • Nested Class Summary

    Nested Classes 
    Modifier and Type Class Description
    static class  Wildcard.Pair<T,​U>
    A class to hold a pair of values.

  • Field Summary

    Fields 
    Modifier and Type Field Description
    static int DEFAULT_MAX_RETURN_SIZE
    Limit on the size of the output.

  • Constructor Summary

    Constructors 
    Constructor Description
    Wildcard()  

  • Method Summary

    Modifier and Type Method Description
    long[] generateLongArray​(long base, long wildcards, long notused)
    Generate an array of long integers based on an integer with some of its bits designated as "wildcards".
    long[] generateLongArray​(java.lang.String str)
    Generate an array of long integers based on an integer with some of its bits designated as "wildcards".
    int getMaxReturnSize()
    Returns the maximum size of the array that will be generated.
    long[] getWildcardMasks​(long wildcards)
    Generates the set of masks specified by wildcards.
    static java.lang.String longPairToWildcardString​(long base, long wildcards)
    Generate a String describing the set of integers to be generated by generateLongArray(String) given base and wildcards.
    void setMaxReturnSize​(int new_mrs)
    Sets a new upper bound for size of the array to be generated.
    static Wildcard.Pair<java.lang.Long,​java.lang.Long> wildcardStringToLongPair​(java.lang.String str)
    Convert a String describing a set of integers (e.g., "0101X00XX01") into the pair of longs used by generateLongArray(long, long, long).

    Methods inherited from class edu.gvsu.kurmasz.warszawa.listgen.IntegerListGenerator

    generateIntArray, generateIntList, generateLongList

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • DEFAULT_MAX_RETURN_SIZE

      public static final int DEFAULT_MAX_RETURN_SIZE
      Limit on the size of the output. In the worst case, a wildcard mask of -1 will produce an array containing 232 elements. This is not illegal in Java; but, will almost certainly exhaust the computer's virtual memory. To prevent this, we set a default upper limit.
      See Also:
      Constant Field Values

  • Constructor Details

  • Method Details

    • setMaxReturnSize

      public void setMaxReturnSize​(int new_mrs)
      Sets a new upper bound for size of the array to be generated.
      Parameters:
      new_mrs - new maximum array size returned. Must be >= 1.
      Throws:
      java.lang.IllegalArgumentException - if new_mrs ≤ 0.

    • getMaxReturnSize

      public int getMaxReturnSize()
      Returns the maximum size of the array that will be generated.
      Returns:
      the maximum size of the array that will be generated.

    • longPairToWildcardString

      public static java.lang.String longPairToWildcardString​(long base, long wildcards)
      Generate a String describing the set of integers to be generated by generateLongArray(String) given base and wildcards.
      Parameters:
      base -
      wildcards -
      Returns:
      a String describing the set of integers to be generated by generateLongArray(String)

    • wildcardStringToLongPair

      public static Wildcard.Pair<java.lang.Long,​java.lang.Long> wildcardStringToLongPair​(java.lang.String str)
      Convert a String describing a set of integers (e.g., "0101X00XX01") into the pair of longs used by generateLongArray(long, long, long). Wildcards may be designated as "X", "x", "*", or "?". Leading and trailing whitespace will be ignored. Internal whitespace is an error.
      Parameters:
      str - A String describing a set of integers by marking certain bits as "wildcards" with Xs.
      Returns:
      the pair of longs used by generateLongArray(long, long, long).
      Throws:
      java.lang.IllegalArgumentException - if str contains characters other than "0", "1", or valid wildcard characters.

    • generateLongArray

      public long[] generateLongArray​(long base, long wildcards, long notused)
      Generate an array of long integers based on an integer with some of its bits designated as "wildcards". For example, the binary value 10** is expanded into the set {1000, 1001, 1010, 1011} (which is returned as the array {8, 9, 10, 11}).

      Because the parameters to the generation methods are integers, and not Strings, we must use two parameters: One to specify the value of the "fixed" bits, and the other to specify the locations of the wildcards. In the example above, the first parameter would be 8 (1000 in binary) and the second parameter would be 3 (11 in binary). The second parameter tells us that the last two bits are wildcards. The first parameter tells us the values of those bits that are not wildcards (in this case that the second two bits are 10).

      Here are some example inputs and outputs:

      1. generateLongArray(x, 0) = {x} for all x. (No bits are wildcards.)
      2. generateLongArray(0, 1) = {0, 1}. The least significant bit is the only wildcard.
      3. generateLongArray(1, 1) = {0, 1}. The least significant bit is the only wildcard. Notice that if a bit is specified as a wildcard, it doesn't matter what the corresponding bit in the "fixed" parameter is.
      4. generateLongArray(52, 1) = {52, 53}. The least significant bit is the only wildcard.
      5. generateLongArray(53, 1) = {52, 53}. The least significant bit is the only wildcard.
      6. generateLongArray(0, 3) = {0, 1, 2, 3}.
      7. generateLongArray(4, 3), = {4, 5, 6 , 7}.
      8. generateLongArray(9, 18) = {9, 11, 25, 27}. (9 = 01001b and 18 = 10010b. Together, they define the pattern "*10*1". The pattern produces {01001, 01011, 11001,11011}.)

      If trying to figure out how to use base and wildcards gives you a headache, check out wildcardStringToLongPair(String) and longPairToWildcardString(long, long).

      Specified by:
      generateLongArray in class IntegerListGenerator
      Parameters:
      base - an integer specifying the bits that are considered "fixed".
      wildcards - an integer whose "1" bits identify the location of the "wildcards".
      notused - not used.
      Returns:
      an array of long integers.
      Throws:
      java.lang.IllegalArgumentException - of wildcards defines too many values.

    • generateLongArray

      public long[] generateLongArray​(java.lang.String str)
      Generate an array of long integers based on an integer with some of its bits designated as "wildcards". For example, "10**" is expanded into the set {1000, 1001, 1010, 1011} (which is returned as the array {8, 9, 10, 11}).
      Parameters:
      str - A description of the set of values to return
      Returns:
      an array of long integers.

    • getWildcardMasks

      public long[] getWildcardMasks​(long wildcards)
      Generates the set of masks specified by wildcards. In particular, each bit in wildcards with a value of 1 is a wildcard. Thus if wildcards contains n bits with a value of 1, it specifies a set of 2^n masks. For example the input 5 (binary 101b) specifies 4 masks: 000, 001, 100, and 101.
      Parameters:
      wildcards - a long integer whose bits with value 1 specify the location of wildcards.
      Returns:
      a set of masks that implement the wildcards.
      Throws:
      java.lang.IllegalArgumentException - of wildcards defines too many values.