Package org.plumelib.util

Class Intern

java.lang.Object
org.plumelib.util.Intern
public final class Intern extends Object
Utilities for interning objects. Interning is also known as canonicalization or hash-consing: it returns a single representative object that Object.equals(java.lang.Object) the object, and the client discards the argument and uses the result instead. Since only one object exists for every set of equal objects, space usage is reduced. Time may also be reduced, since it is possible to use == instead of .equals() for comparisons.

Java builds in interning for Strings, but not for other objects. The methods in this class extend interning to all Java objects.

  • Method Summary

    Modifier and Type
    Method
    Description
    static double
    intern(double d)
    Interns a double A no-op.
    static double @Interned @PolyValue @SameLen("#1") []
    intern(double @PolyValue [] a)
    Intern (canonicalize) a double[].
    static int @Interned @PolyValue @SameLen("#1") []
    intern(int @PolyValue [] a)
    Intern (canonicalize) an int[].
    static long
    intern(long l)
    Interns a long.
    static long @Interned @PolyValue @SameLen("#1") []
    intern(long @PolyValue [] a)
    Intern (canonicalize) a long[].
    static @PolyNull @Interned Object @Interned @PolyValue @SameLen("#1") []
    intern(@PolyNull @Interned @PolyValue Object[] a)
    Intern (canonicalize) an Object[].
    static @PolyNull @Interned String @Interned @PolyValue @SameLen("#1") []
    intern(@PolyNull @Interned String @PolyValue [] a)
    Intern (canonicalize) a String[].
    static @Interned @PolyNull @PolyValue @SameLen("#1") String
    intern(@PolyNull @PolyValue String a)
    Interns a String.
    static @Interned @PolyNull Object
    intern(@PolyNull Object a)
    Convenience method to intern an Object when we don't know its run-time type.
    static @Interned Double
    intern(Double a)
    Intern (canonicalize) a Double.
    static @Interned Integer
    intern(Integer a)
    Intern (canonicalize) an Integer.
    static @Interned Long
    intern(Long a)
    Intern (canonicalize) a Long.
    static @Interned Double
    internedDouble(double d)
    Returns an interned Double with value i.
    static @Interned Double
    internedDouble(String s)
    Returns an interned Double with value parsed from the string.
    static @Interned Integer
    internedInteger(int i)
    Returns an interned Integer with value i.
    static @Interned Integer
    internedInteger(String s)
    Returns an interned Integer with value parsed from the string.
    static @Interned Long
    internedLong(long i)
    Returns an interned Long with value i.
    static @Interned Long
    internedLong(String s)
    Returns an interned Long with value parsed from the string.
    static @Interned String @PolyValue @SameLen("#1") []
    internStrings(String @PolyValue [] a)
    Replace each element of the array by its interned version.
    static double @Interned []
    internSubsequence(double @Interned [] seq, @org.checkerframework.checker.index.qual.IndexFor({"#1"}),@org.checkerframework.checker.index.qual.LessThan({"#3"}) int start, @org.checkerframework.checker.index.qual.NonNegative,@org.checkerframework.checker.index.qual.LTLengthOf(value={"#1"}, offset={"#2 - 1"}) int end)
    Returns a subsequence of seq from start to end that is interned.
    static int @Interned []
    internSubsequence(int @Interned [] seq, @org.checkerframework.checker.index.qual.IndexFor({"#1"}),@org.checkerframework.checker.index.qual.LessThan({"#3"}) int start, @org.checkerframework.checker.index.qual.NonNegative,@org.checkerframework.checker.index.qual.LTLengthOf(value={"#1"}, offset={"#2 - 1"}) int end)
    Returns an interned subsequence of seq from start (inclusive) to end (exclusive).
    static long @Interned []
    internSubsequence(long @Interned [] seq, @org.checkerframework.checker.index.qual.IndexFor({"#1"}),@org.checkerframework.checker.index.qual.LessThan({"#3"}) int start, @org.checkerframework.checker.index.qual.NonNegative,@org.checkerframework.checker.index.qual.LTLengthOf(value={"#1"}, offset={"#2 - 1"}) int end)
    Returns a subsequence of seq from start to end that is interned.
    static @PolyNull @Interned Object @Interned []
    internSubsequence(@PolyNull @Interned Object @Interned [] seq, @org.checkerframework.checker.index.qual.IndexFor({"#1"}),@org.checkerframework.checker.index.qual.LessThan({"#3"}) int start, @org.checkerframework.checker.index.qual.NonNegative,@org.checkerframework.checker.index.qual.LTLengthOf(value={"#1"}, offset={"#2 - 1"}) int end)
    Returns a subsequence of seq from start to end that is interned.
    static @PolyNull @Interned String @Interned []
    internSubsequence(@PolyNull @Interned String @Interned [] seq, @org.checkerframework.checker.index.qual.IndexFor({"#1"}),@org.checkerframework.checker.index.qual.LessThan({"#3"}) int start, @org.checkerframework.checker.index.qual.NonNegative,@org.checkerframework.checker.index.qual.LTLengthOf(value={"#1"}, offset={"#2 - 1"}) int end)
    Returns a subsequence of seq from start to end that is interned.
    static boolean
    isInterned(@Nullable Object value)
    Returns true if the argument is interned (is canonical among all objects equal to itself).

    Methods inherited from class java.lang.Object

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

  • Method Details

    • internStrings

      public static @Interned String @PolyValue @SameLen("#1") [] internStrings(String @PolyValue [] a)
      Replace each element of the array by its interned version. Side-effects the array, but also returns it.
      Parameters:
      a - the array whose elements to intern in place
      Returns:
      an interned version of a
      See Also:

    • isInterned

      @Pure public static boolean isInterned(@Nullable Object value)
      Returns true if the argument is interned (is canonical among all objects equal to itself).
      Parameters:
      value - the value to test for interning
      Returns:
      true iff value is interned

    • intern

      @Pure public static @Interned @PolyNull @PolyValue @SameLen("#1") String intern(@PolyNull @PolyValue String a)
      Interns a String. Delegates to the builtin String.intern() method, but handles null.
      Parameters:
      a - the string to intern; may be null
      Returns:
      an interned version of the argument, or null if the argument was null

    • intern

      @Pure public static long intern(long l)
      Interns a long. A no-op. Provided for completeness.
      Parameters:
      l - the long to intern
      Returns:
      an interned version of the argument

    • intern

      @Pure public static double intern(double d)
      Interns a double A no-op. Provided for completeness.
      Parameters:
      d - the double to intern
      Returns:
      an interned version of the argument

    • intern

      @Pure public static @Interned Integer intern(Integer a)
      Intern (canonicalize) an Integer. Return a canonical representation for the Integer.
      Parameters:
      a - an Integer to canonicalize
      Returns:
      a canonical representation for the Integer

    • internedInteger

      public static @Interned Integer internedInteger(int i)
      Returns an interned Integer with value i.
      Parameters:
      i - the value to intern
      Returns:
      an interned Integer with value i

    • internedInteger

      public static @Interned Integer internedInteger(String s)
      Returns an interned Integer with value parsed from the string.
      Parameters:
      s - the string to parse
      Returns:
      an interned Integer parsed from s

    • intern

      @Pure public static @Interned Long intern(Long a)
      Intern (canonicalize) a Long. Return a canonical representation for the Long.
      Parameters:
      a - the value to intern
      Returns:
      a canonical representation for the Long

    • internedLong

      public static @Interned Long internedLong(long i)
      Returns an interned Long with value i.
      Parameters:
      i - the value to intern
      Returns:
      an interned Integer with value i

    • internedLong

      public static @Interned Long internedLong(String s)
      Returns an interned Long with value parsed from the string.
      Parameters:
      s - the string to parse
      Returns:
      an interned Long parsed from s

    • intern

      @Pure public static int @Interned @PolyValue @SameLen("#1") [] intern(int @PolyValue [] a)
      Intern (canonicalize) an int[]. Return a canonical representation for the int[] array. Arrays are compared according to their elements.
      Parameters:
      a - the array to canonicalize
      Returns:
      a canonical representation for the int[] array

    • intern

      @Pure public static long @Interned @PolyValue @SameLen("#1") [] intern(long @PolyValue [] a)
      Intern (canonicalize) a long[]. Return a canonical representation for the long[] array. Arrays are compared according to their elements.
      Parameters:
      a - the array to canonicalize
      Returns:
      a canonical representation for the long[] array

    • intern

      @Pure public static @Interned Double intern(Double a)
      Intern (canonicalize) a Double. Return a canonical representation for the Double.
      Parameters:
      a - the Double to canonicalize
      Returns:
      a canonical representation for the Double

    • internedDouble

      public static @Interned Double internedDouble(double d)
      Returns an interned Double with value i.
      Parameters:
      d - the value to intern
      Returns:
      an interned Double with value d

    • internedDouble

      public static @Interned Double internedDouble(String s)
      Returns an interned Double with value parsed from the string.
      Parameters:
      s - the string to parse
      Returns:
      an interned Double parsed from s

    • intern

      @Pure public static double @Interned @PolyValue @SameLen("#1") [] intern(double @PolyValue [] a)
      Intern (canonicalize) a double[]. Return a canonical representation for the double[] array. Arrays are compared according to their elements.
      Parameters:
      a - the array to canonicalize
      Returns:
      a canonical representation for the double[] array

    • intern

      @Pure public static @PolyNull @Interned String @Interned @PolyValue @SameLen("#1") [] intern(@PolyNull @Interned String @PolyValue [] a)
      Intern (canonicalize) a String[]. Return a canonical representation for the String[] array. Arrays are compared according to their elements' equals() methods.
      Parameters:
      a - the array to canonicalize. Its elements should already be interned.
      Returns:
      a canonical representation for the String[] array

    • intern

      @Pure public static @PolyNull @Interned Object @Interned @PolyValue @SameLen("#1") [] intern(@PolyNull @Interned @PolyValue Object[] a)
      Intern (canonicalize) an Object[]. Return a canonical representation for the Object[] array. Arrays are compared according to their elements. The elements should themselves already be interned; they are compared using their equals() methods.
      Parameters:
      a - the array to canonicalize
      Returns:
      a canonical representation for the Object[] array

    • intern

      @Pure public static @Interned @PolyNull Object intern(@PolyNull Object a)
      Convenience method to intern an Object when we don't know its run-time type. Its run-time type must be one of the types for which we have an intern() method, else an exception is thrown. If the argument is an array, its elements should themselves be interned.
      Parameters:
      a - an Object to canonicalize
      Returns:
      a canonical version of a

    • internSubsequence

      public static int @Interned [] internSubsequence(int @Interned [] seq, @org.checkerframework.checker.index.qual.IndexFor({"#1"}),@org.checkerframework.checker.index.qual.LessThan({"#3"}) int start, @org.checkerframework.checker.index.qual.NonNegative,@org.checkerframework.checker.index.qual.LTLengthOf(value={"#1"}, offset={"#2 - 1"}) int end)
      Returns an interned subsequence of seq from start (inclusive) to end (exclusive). The argument seq should already be interned.

      The result is the same as computing the subsequence and then interning it, but this method is more efficient: if the subsequence is already interned, it avoids computing the subsequence.

      For example, since derived variables in Daikon compute the subsequence many times, this shortcut saves quite a bit of computation. It saves even more when there may be many derived variables that are non-canonical, since they are guaranteed to be ==.

      Parameters:
      seq - the interned sequence whose subsequence should be computed and interned
      start - the index of the start of the subsequence to compute and intern
      end - the index of the end of the subsequence to compute and intern
      Returns:
      a subsequence of seq from start to end that is interned

    • internSubsequence

      @Pure public static long @Interned [] internSubsequence(long @Interned [] seq, @org.checkerframework.checker.index.qual.IndexFor({"#1"}),@org.checkerframework.checker.index.qual.LessThan({"#3"}) int start, @org.checkerframework.checker.index.qual.NonNegative,@org.checkerframework.checker.index.qual.LTLengthOf(value={"#1"}, offset={"#2 - 1"}) int end)
      Returns a subsequence of seq from start to end that is interned.
      Parameters:
      seq - the interned sequence whose subsequence should be computed and interned
      start - the index of the start of the subsequence to compute and intern
      end - the index of the end of the subsequence to compute and intern
      Returns:
      a subsequence of seq from start to end that is interned
      See Also:

    • internSubsequence

      @Pure public static double @Interned [] internSubsequence(double @Interned [] seq, @org.checkerframework.checker.index.qual.IndexFor({"#1"}),@org.checkerframework.checker.index.qual.LessThan({"#3"}) int start, @org.checkerframework.checker.index.qual.NonNegative,@org.checkerframework.checker.index.qual.LTLengthOf(value={"#1"}, offset={"#2 - 1"}) int end)
      Returns a subsequence of seq from start to end that is interned.
      Parameters:
      seq - the interned sequence whose subsequence should be computed and interned
      start - the index of the start of the subsequence to compute and intern
      end - the index of the end of the subsequence to compute and intern
      Returns:
      a subsequence of seq from start to end that is interned
      See Also:

    • internSubsequence

      @Pure public static @PolyNull @Interned Object @Interned [] internSubsequence(@PolyNull @Interned Object @Interned [] seq, @org.checkerframework.checker.index.qual.IndexFor({"#1"}),@org.checkerframework.checker.index.qual.LessThan({"#3"}) int start, @org.checkerframework.checker.index.qual.NonNegative,@org.checkerframework.checker.index.qual.LTLengthOf(value={"#1"}, offset={"#2 - 1"}) int end)
      Returns a subsequence of seq from start to end that is interned.
      Parameters:
      seq - the interned sequence whose subsequence should be computed and interned
      start - the index of the start of the subsequence to compute and intern
      end - the index of the end of the subsequence to compute and intern
      Returns:
      a subsequence of seq from start to end that is interned
      See Also:

    • internSubsequence

      @Pure public static @PolyNull @Interned String @Interned [] internSubsequence(@PolyNull @Interned String @Interned [] seq, @org.checkerframework.checker.index.qual.IndexFor({"#1"}),@org.checkerframework.checker.index.qual.LessThan({"#3"}) int start, @org.checkerframework.checker.index.qual.NonNegative,@org.checkerframework.checker.index.qual.LTLengthOf(value={"#1"}, offset={"#2 - 1"}) int end)
      Returns a subsequence of seq from start to end that is interned.
      Parameters:
      seq - the interned sequence whose subsequence should be computed and interned
      start - the index of the start of the subsequence to compute and intern
      end - the index of the end of the subsequence to compute and intern
      Returns:
      a subsequence of seq from start to end that is interned
      See Also: