org.plumelib.util

Class Intern

java.lang.Object

org.plumelib.util.Intern

public final class Intern
extends java.lang.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 and Description
static double	intern(double d) Interns a double A no-op.
static @Interned java.lang.Double	intern(java.lang.Double a) Intern (canonicalize) a Double.
static double[]	intern(double[] a) Intern (canonicalize) a double[].
static int[]	intern(int[] a) Intern (canonicalize) an int[].
static @Interned java.lang.Integer	intern(java.lang.Integer a) Intern (canonicalize) an Integer.
static long	intern(long l) Interns a long.
static @Interned java.lang.Long	intern(java.lang.Long a) Intern (canonicalize) a Long.
static long[]	intern(long[] a) Intern (canonicalize) a long[].
static @Interned @PolyNull java.lang.Object	intern(@PolyNull java.lang.Object a) Convenience method to intern an Object when we don't know its run-time type.
static @PolyNull @Interned java.lang.Object[]	intern(@PolyNull @Interned @PolyValue java.lang.Object[] a) Intern (canonicalize) an Object[].
static @Interned @PolyNull @PolyValue @SameLen(value="#1") java.lang.String	intern(@PolyNull @PolyValue java.lang.String a) Interns a String.
static @PolyNull @Interned java.lang.String[]	intern(@PolyNull @Interned java.lang.String[] a) Intern (canonicalize) a String[].
static @Interned java.lang.Double	internedDouble(double d) Returns an interned Double with value i.
static @Interned java.lang.Double	internedDouble(java.lang.String s) Returns an interned Double with value parsed from the string.
static @Interned java.lang.Integer	internedInteger(int i) Returns an interned Integer with value i.
static @Interned java.lang.Integer	internedInteger(java.lang.String s) Returns an interned Integer with value parsed from the string.
static @Interned java.lang.Long	internedLong(long i) Returns an interned Long with value i.
static @Interned java.lang.Long	internedLong(java.lang.String s) Returns an interned Long with value parsed from the string.
static @Interned java.lang.String[]	internStrings(java.lang.String[] a) Replace each element of the array by its interned version.
static double[]	internSubsequence(double[] seq, @IndexFor(value="#1") @LessThan(value="#3") int start, @NonNegative @LTLengthOf(value="#1",offset="#2 - 1") int end) Returns a subsequence of seq from start to end that is interned.
static int[]	internSubsequence(int[] seq, @IndexFor(value="#1") @LessThan(value="#3") int start, @NonNegative @LTLengthOf(value="#1",offset="#2 - 1") int end) Return an interned subsequence of seq from start (inclusive) to end (exclusive).
static long[]	internSubsequence(long[] seq, @IndexFor(value="#1") @LessThan(value="#3") int start, @NonNegative @LTLengthOf(value="#1",offset="#2 - 1") int end) Returns a subsequence of seq from start to end that is interned.
static @PolyNull @Interned java.lang.Object[]	internSubsequence(@PolyNull @Interned java.lang.Object[] seq, @IndexFor(value="#1") @LessThan(value="#3") int start, @NonNegative @LTLengthOf(value="#1",offset="#2 - 1") int end) Returns a subsequence of seq from start to end that is interned.
static @PolyNull @Interned java.lang.String[]	internSubsequence(@PolyNull @Interned java.lang.String[] seq, @IndexFor(value="#1") @LessThan(value="#3") int start, @NonNegative @LTLengthOf(value="#1",offset="#2 - 1") int end) Returns a subsequence of seq from start to end that is interned.
static boolean	isInterned(@Nullable java.lang.Object value) Return 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 Detail

internStrings

public static @Interned java.lang.String[] internStrings(java.lang.String[] 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:

String.intern()

isInterned

@Pure
public static boolean isInterned(@Nullable java.lang.Object value)

Return 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(value="#1") java.lang.String intern(@PolyNull @PolyValue java.lang.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 java.lang.Integer intern(java.lang.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 java.lang.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 java.lang.Integer internedInteger(java.lang.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 java.lang.Long intern(java.lang.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 java.lang.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 java.lang.Long internedLong(java.lang.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[] intern(int[] 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[] intern(long[] 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 java.lang.Double intern(java.lang.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 java.lang.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 java.lang.Double internedDouble(java.lang.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[] intern(double[] 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 java.lang.String[] intern(@PolyNull @Interned java.lang.String[] 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 java.lang.Object[] intern(@PolyNull @Interned @PolyValue java.lang.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 java.lang.Object intern(@PolyNull java.lang.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[] internSubsequence(int[] seq,
                                      @IndexFor(value="#1") @LessThan(value="#3") int start,
                                      @NonNegative @LTLengthOf(value="#1",offset="#2 - 1") int end)

Return 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[] internSubsequence(long[] seq,
                                             @IndexFor(value="#1") @LessThan(value="#3") int start,
                                             @NonNegative @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(int[], int, int)

internSubsequence

@Pure
public static double[] internSubsequence(double[] seq,
                                               @IndexFor(value="#1") @LessThan(value="#3") int start,
                                               @NonNegative @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(int[], int, int)

internSubsequence

@Pure
public static @PolyNull @Interned java.lang.Object[] internSubsequence(@PolyNull @Interned java.lang.Object[] seq,
                                                                             @IndexFor(value="#1") @LessThan(value="#3") int start,
                                                                             @NonNegative @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(int[], int, int)

internSubsequence

@Pure
public static @PolyNull @Interned java.lang.String[] internSubsequence(@PolyNull @Interned java.lang.String[] seq,
                                                                             @IndexFor(value="#1") @LessThan(value="#3") int start,
                                                                             @NonNegative @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(int[], int, int)