Package org.apache.calcite.util

Class Util

java.lang.Object

org.apache.calcite.util.Util

public class Util
extends Object

Miscellaneous utility functions.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Util.FoundOne	Exception used to interrupt a tree walk of any kind.
static class	Util.OverFinder	Visitor which looks for an OVER clause inside a tree of SqlNode objects.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	FILE_SEPARATOR	System-dependent file separator, for example, "/" or "\."
static final String	FILE_TIMESTAMP_FORMAT	Datetime format string for generating a timestamp string to be used as part of a filename.
static final String	LINE_SEPARATOR	System-dependent newline character.

Method Summary

Modifier and Type	Method	Description
static <X> UnaryOperator<X>	andThen(UnaryOperator<X> op1, UnaryOperator<X> op2)	Returns an operator that applies op1 and then op2.
static <K, V> Map<K,V>	asIndexMap(Collection<V> values, com.google.common.base.Function<V,K> function)	Deprecated.
static <K, V> Map<K,V>	asIndexMapJ(Collection<V> values, Function<V,K> function)	Returns a map that is a view onto a collection of values, using the provided function to convert a value to a key.
static void	asStringBuilder(Appendable appendable, Consumer<StringBuilder> consumer)	Given an Appendable, performs an action that requires a StringBuilder.
static <K, V> Map<K,V>	blackholeMap()	Returns a map which ignores any write operation.
static Calendar	calendar()	Creates a Calendar in the UTC time zone and root locale.
static Calendar	calendar(long millis)	Creates a Calendar in the UTC time zone and root locale with a given time.
static <E> Iterable<E>	cast(Iterable<? super E> iterable, Class<E> clazz)	Converts an Iterable whose members are automatically down-cast to a given type.
static <E extends @PolyNull Object> Iterator<E>	cast(Iterator<? extends @PolyNull Object> iter, Class<E> clazz)	Converts a iterator whose members are automatically down-cast to a given type.
static <E> List<E>	cast(List<? super E> list, Class<E> clazz)	Converts a list whose members are automatically down-cast to a given type.
static Throwable	causeOrSelf(Throwable throwable)	Returns cause of the given throwable if it is non-null or the throwable itself.
static <E> com.google.common.collect.ImmutableList.Builder<E>	combine(com.google.common.collect.ImmutableList.Builder<E> b0, com.google.common.collect.ImmutableList.Builder<E> b1)	Combines a second immutable list builder into a first.
static <E> ArrayList<E>	combine(ArrayList<E> list0, ArrayList<E> list1)	Combines a second array list into a first.
static <T> String	commaList(List<T> list)	Converts a list of a string, with commas between elements.
static boolean	contains(String[] a, int length, String s)	Returns whether an array of strings contains a given string among the first length entries.
static void	debugCode(PrintStream out, String code)	Prints the given code with line numbering.
static <T> T	deprecated(T argument, boolean fail)	Deprecated. If a piece of code calls this method, it indicates that the code needs to be cleaned up.
static void	discard(boolean b)	Does nothing with its argument.
static void	discard(double d)	Does nothing with its argument.
static void	discard(int i)	Does nothing with its argument.
static void	discard(@Nullable Object o)	Does nothing with its argument.
static <E> List<E>	distinctList(Iterable<E> keys)	Converts an iterable into a list with unique elements.
static <E> List<E>	distinctList(List<E> list)	Converts a list into a list with unique elements.
static <T extends Enum<T>> Map<String,T>	enumConstants(Class<T> clazz)	Creates a map of the values of an enumeration by name.
static <T extends Enum<T>> @Nullable T	enumVal(Class<T> clazz, String name)	Returns the value of an enumeration with a particular name.
static <T extends Enum<T>> T	enumVal(T default_, @Nullable String name)	Returns the value of an enumeration with a particular or default value if not found.
static <T> boolean	equalShallow(List<? extends T> list0, List<? extends T> list1)	Returns whether two lists are equal to each other using shallow comparisons.
static <E> Iterable<E>	filter(Iterable<?> iterable, Class<E> includeFilter)	Makes a collection of untyped elements appear as a list of strictly typed elements, by filtering out those which are not of the correct type.
static <E> Iterable<E>	filter(Iterable<? extends E> iterable, Predicate<? super E> predicate)	Filters an iterable.
static <E> Collection<E>	filter(Collection<?> collection, Class<E> includeFilter)
static <E> Iterator<E>	filter(Iterator<? extends E> iterator, Predicate<? super E> predicate)	Filters an iterator.
static <E> List<E>	filter(List<?> list, Class<E> includeFilter)	Returns a subset of a list containing only elements of a given type.
static int	findMatch(List<String> strings, String seek, boolean caseSensitive)	Looks for a string within a list of strings, using a given case-sensitivity policy, and returns the position at which the first match is found, or -1 if there are no matches.
static <T> @PolyNull T	first(@Nullable T v0, @PolyNull T v1)	Returns the first value if it is not null, otherwise the second value.
static boolean	first(@Nullable Boolean v0, boolean v1)	Unboxes a Boolean value, using a given default value if it is null.
static byte	first(@Nullable Byte v0, byte v1)	Unboxes a Byte value, using a given default value if it is null.
static char	first(@Nullable Character v0, char v1)	Unboxes a Character value, using a given default value if it is null.
static double	first(@Nullable Double v0, double v1)	Unboxes a Double value, using a given default value if it is null.
static float	first(@Nullable Float v0, float v1)	Unboxes a Float value, using a given default value if it is null.
static int	first(@Nullable Integer v0, int v1)	Unboxes a Integer value, using a given default value if it is null.
static long	first(@Nullable Long v0, long v1)	Unboxes a Long value, using a given default value if it is null.
static short	first(@Nullable Short v0, short v1)	Unboxes a Short value, using a given default value if it is null.
<E> E	first(List<E> list)	Returns the first element of a list.
static <E> List<E>	first(List<E> list, int n)	Returns the first n elements of a list.
static <E> int	firstDuplicate(List<E> list)	Returns the ordinal of the first element in the list which is equal to a previous element in the list.
static Charset	getDefaultCharset()	Returns the Charset object representing the value of CalciteSystemProperty.DEFAULT_CHARSET.
static String	getFileTimestamp()	Deprecated.
static String	getMessages(Throwable t)	Deprecated.
static String	getStackTrace(Throwable t)	Deprecated. Use Throwables.getStackTraceAsString(Throwable)
static int	hash(int i, int j)	Deprecated. Use Objects.hash(Object...)
static int	hash(int h, @Nullable Object o)	Deprecated. Use Objects.hash(Object...)
static int	hashArray(int h, Object[] a)	Deprecated. Use Objects.hash(Object...)
static int	hashCode(double v)	Deprecated. Use Utilities.hashCode(double)
static String	human(double d)	Converts a number into human-readable form, with 3 digits and a "K", "M" or "G" multiplier for thousands, millions or billions.
static <E> List<List<E>>	immutableCopy(Iterable<? extends Iterable<E>> lists)	Returns a copy of a list of lists, making the component lists immutable if they are not already.
static <E> boolean	intersects(Collection<E> c0, Collection<E> c1)	Returns whether two collections have any elements in common.
static <E> boolean	isDefinitelyDistinctAndNonNull(List<? extends @Nullable E> list)	Returns whether the elements of list are definitely distinct and not null, working quickly and sometimes giving false negatives for large lists.
static <E> boolean	isDistinct(List<E> list)	Returns whether the elements of list are distinct.
static boolean	isNullOrEmpty(@Nullable String s)	Returns whether s == null or if s.length() == 0.
static boolean	isSingleValue(SqlCall call)	Does nothing with its argument.
static boolean	isValidJavaIdentifier(String s)	Returns true when input string is a valid Java identifier.
static <E> E	last(List<E> list)	Returns the last element of a list.
static <E> List<E>	last(List<E> list, int n)	Returns the last n elements of a list.
static String	lines(Iterable<String> strings)	Converts a list of strings to a string separated by newlines.
static String	listToString(List<String> list)	Converts ["ab", "c"] to "ab"."c".
static <K, V> Map<K,V>	mapOf(K key, V value, Object... keyValues)	Returns a hashmap with given contents.
static boolean	matches(boolean caseSensitive, String s0, String s1)	Returns whether a name matches another according to a given case-sensitivity policy.
static <T> Set<T>	minus(Set<T> set1, Set<T> set2)	Returns a set of the elements which are in set1 but not in set2, without modifying either.
static <E> List<E>	moveToHead(List<? extends E> terms, Predicate<? super E> predicate)	Returns a list with any elements for which the predicate is true moved to the head of the list.
static RuntimeException	needToImplement(@Nullable Object o)	Returns a RuntimeException indicating that a particular feature has not been implemented, but should be.
static Error	newInternal()	Deprecated. Throw new AssertionError
static Error	newInternal(String s)	Deprecated. Throw new AssertionError
static Error	newInternal(Throwable e)	Deprecated. Throw new RuntimeException if checked; throw raw exception if unchecked or Error
static Error	newInternal(Throwable e, String s)	Deprecated. Throw new AssertionError if applicable; or RuntimeException if e is checked; or raw exception if e is unchecked or Error.
static double	nLogM(double n, double m)	Computes nlog(m) using the natural logarithm (or n if m < Math.E, so the result is never negative.
static double	nLogN(double d)	Computes nlogn(n) using the natural logarithm (or n if n < Math.E, so the result is never negative.
static <T> Iterable<T>	orEmpty(@Nullable Iterable<T> v0)
static <E> List<Pair<E,E>>	pairs(List<E> list)	Given a list with N elements [e0, e1, ..., eN-1] (where N is even), returns a list of the N / 2 elements [ (e0, e1), (e2, e3), ...
static Locale	parseLocale(String localeString)	Parses a locale string.
static void	permAssert(boolean b, String description)	Deprecated. Use Preconditions.checkArgument(boolean)
static void	post(boolean b, String description)	Deprecated. Use Preconditions.checkArgument(boolean) or Objects.requireNonNull(Object)
static void	pre(boolean b, String description)	Deprecated. Use Preconditions.checkArgument(boolean) or Objects.requireNonNull(Object)
static void	print(PrintWriter pw, @Nullable Object o, int indent)
static void	print(PrintWriter pw, Object o)	Prints an object using reflection.
static <E> StringBuilder	printIterable(StringBuilder sb, Iterable<E> iterable)	Prints a collection of elements to a StringBuilder, in the same format as AbstractCollection.toString().
static void	printJavaString(Appendable appendable, @Nullable String s, boolean nullMeansNull)	Prints a string, enclosing in double quotes (") and escaping if necessary.
static StringBuilder	printList(StringBuilder sb, int elementCount, ObjIntConsumer<StringBuilder> consumer)	Prints a set of elements to a StringBuilder, in the same format same as AbstractCollection.toString().
static void	println(PrintWriter pw, Object o)
static PrintWriter	printWriter(File file)	Creates a PrintWriter to a given file using UTF-8 character set.
static PrintWriter	printWriter(OutputStream out)	Creates a PrintWriter to a given output stream using UTF-8 character set.
static <E> List<E>	quotientList(List<E> list, int n, int k)	Creates a list that returns every nth element of a list, starting at element k.
static List<Integer>	range(int end)
static List<Integer>	range(int start, int end)
static String	readAllAsString(Reader reader)	Deprecated.
static BufferedReader	reader(File file)	Creates a BufferedReader to read a given file using UTF-8 character set.
static BufferedReader	reader(InputStream in)	Creates a BufferedReader to a given input stream using UTF-8 character set.
static String	replace(String s, String find, String replace)	Replaces every occurrence of find in s with replace.
static String	rpad(String s, int len)	Deprecated. Use Spaces.padRight(String, int)
static String	rtrim(String s)	Deprecated.
static <E> List<E>	select(List<E> list, List<Integer> ordinals)	Returns a view of a list, picking the elements of a list with the given set of ordinals.
static <T> String	sepList(List<T> list, String sep)	Converts a list of a string, with a given separator between elements.
static <E> List<E>	skip(List<E> list)	Returns all but the first element of a list.
static <E> List<E>	skip(List<E> list, int fromIndex)	Returns all but the first n elements of a list.
static <E> List<E>	skipLast(List<E> list)	Returns every element of a list but its last element.
static <E> List<E>	skipLast(List<E> list, int n)	Returns every element of a list but its last n elements.
static void	squelchConnection(@Nullable Connection connection)	Deprecated.
static void	squelchJar(@Nullable JarFile jar)	Deprecated.
static void	squelchReader(@Nullable Reader reader)	Deprecated.
static void	squelchStmt(@Nullable Statement stmt)	Deprecated.
static void	squelchStream(@Nullable InputStream stream)	Deprecated.
static void	squelchStream(@Nullable OutputStream stream)	Deprecated.
static void	squelchWriter(@Nullable Writer writer)	Deprecated.
static <E> boolean	startsWith(List<E> list0, List<E> list1)	Returns whether one list is a prefix of another.
static List<String>	stringToList(String s)
static String	stripDoubleQuotes(String value)	Converts double-quoted Java strings to their contents.
static void	swallow(Throwable e, @Nullable org.slf4j.Logger logger)	Records that an exception has been caught but will not be re-thrown.
static RuntimeException	throwAsRuntime(String message, Throwable throwable)	This method rethrows input throwable as is (if its unchecked) with an extra message or wraps it with RuntimeException and throws.
static RuntimeException	throwAsRuntime(Throwable throwable)	This method rethrows input throwable as is (if its unchecked) or wraps it with RuntimeException and throws.
static void	throwIfUnchecked(Throwable throwable)	Deprecated.
static <T> Collector<T,?,com.google.common.collect.ImmutableList<T>>	toImmutableList()	Deprecated. Use ImmutableList.toImmutableList()
static String	toJavaId(String s, int ordinal)	Converts an arbitrary string into a string suitable for use as a Java identifier.
static Iterable<String>	tokenize(String s, String delim)	Converts a string into tokens.
static String	toLinux(String s)
static <T> List<T>	toList(Iterator<T> iter)	Deprecated.
static Map<String,String>	toMap(Properties properties)	Converts a Properties object to a Map<String, String>.
static String	toPosix(TimeZone tz, boolean verbose)	Converts a Java timezone to POSIX format, so that the boost C++ library can instantiate timezone objects.
static String	toScientificNotation(BigDecimal bd)	Formats a BigDecimal value to a string in scientific notation For example A value of 0.00001234 would be formated as 1.234E-5 A value of 100000.00 would be formated as 1.00E5 A value of 100 (scale zero) would be formated as 1E2
static <T> String	toString(Iterable<T> iterable, String start, String sep, String end)	Converts an iterable to a string.
static RuntimeException	toUnchecked(Exception e)	Wraps an exception with RuntimeException and return it.
static URL	toURL(File file)	Deprecated.
static <F, T> Iterable<T>	transform(Iterable<? extends F> iterable, Function<? super F,? extends T> function)	Transforms an iterable, applying a function to each element.
static <F, T> Iterator<T>	transform(Iterator<? extends F> iterator, Function<? super F,? extends T> function)	Transforms an iterator.
static <F, T> List<T>	transform(List<? extends F> list, Function<? super F,? extends T> function)	Transforms a list, applying a function to each element.
static <F, T> List<T>	transformIndexed(List<? extends F> list, BiFunction<? super F,Integer,? extends T> function)	Transforms a list, applying a function to each element, also passing in the element's index in the list.
static <E extends Enum<E>> Error	unexpected(E value)	Returns an exception indicating that we didn't expect to find this enumeration here.

Methods inherited from class java.lang.Object

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

Field Details

LINE_SEPARATOR

public static final String LINE_SEPARATOR

System-dependent newline character.

In general, you should not use this in expected results of tests. Expected results should be the expected result on Linux (or Mac OS) using '\n'. Apply toLinux(String) to Windows actual results, if necessary, to make them look like Linux actual.

FILE_SEPARATOR

public static final String FILE_SEPARATOR

System-dependent file separator, for example, "/" or "\."

FILE_TIMESTAMP_FORMAT

public static final String FILE_TIMESTAMP_FORMAT

Datetime format string for generating a timestamp string to be used as part of a filename. Conforms to SimpleDateFormat conventions.

See Also:

• Constant Field Values

Method Details

isSingleValue

public static boolean isSingleValue(SqlCall call)

Does nothing with its argument. Returns whether it is ensured that the call produces a single value

Parameters:

call - the expression to evaluate

Returns:

Whether it is ensured that the call produces a single value

discard

public static void discard(@Nullable Object o)

Does nothing with its argument. Call this method when you have a value you are not interested in, but you don't want the compiler to warn that you are not using it.

discard

public static void discard(int i)

Does nothing with its argument. Call this method when you have a value you are not interested in, but you don't want the compiler to warn that you are not using it.

discard

public static void discard(boolean b)

Does nothing with its argument. Call this method when you have a value you are not interested in, but you don't want the compiler to warn that you are not using it.

discard

public static void discard(double d)

Does nothing with its argument. Call this method when you have a value you are not interested in, but you don't want the compiler to warn that you are not using it.

swallow

public static void swallow(Throwable e,
 @Nullable org.slf4j.Logger logger)

Records that an exception has been caught but will not be re-thrown. If the tracer is not null, logs the exception to the tracer.

Parameters:

e - Exception

logger - If not null, logs exception to this logger

equalShallow

public static <T> boolean equalShallow(List<? extends T> list0,
 List<? extends T> list1)

Returns whether two lists are equal to each other using shallow comparisons.

Parameters:

list0 - First list

list1 - Second list

Returns:

Whether lists are same length and all of their elements are equal using == (may be null).

hash

@Deprecated
public static int hash(int i,
 int j)

Deprecated.

Use Objects.hash(Object...)

Combines two integers into a hash code.

hash

@Deprecated
public static int hash(int h,
 @Nullable Object o)

Deprecated.

Use Objects.hash(Object...)

Computes a hash code from an existing hash code and an object (which may be null).

hashArray

@Deprecated
public static int hashArray(int h,
 Object[] a)

Deprecated.

Use Objects.hash(Object...)

Computes a hash code from an existing hash code and an array of objects (which may be null).

hashCode

@Deprecated
public static int hashCode(double v)

Deprecated.

Use Utilities.hashCode(double)

Computes the hash code of a double value. Equivalent to Double.hashCode(double), but that method was only introduced in JDK 1.8.

Parameters:

v - Value

Returns:

Hash code

minus

public static <T> Set<T> minus(Set<T> set1,
 Set<T> set2)

Returns a set of the elements which are in set1 but not in set2, without modifying either.

nLogN

public static double nLogN(double d)

Computes nlogn(n) using the natural logarithm (or n if n < Math.E, so the result is never negative.

nLogM

public static double nLogM(double n,
 double m)

Computes nlog(m) using the natural logarithm (or n if m < Math.E, so the result is never negative.

print

public static void print(PrintWriter pw,
 Object o)

Prints an object using reflection. We can handle null; arrays of objects and primitive values; for regular objects, we print all public fields.

print

public static void print(PrintWriter pw,
 @Nullable Object o,
 int indent)

printJavaString

public static void printJavaString(Appendable appendable,
 @Nullable String s,
 boolean nullMeansNull)

Prints a string, enclosing in double quotes (") and escaping if necessary. For example, printDoubleQuoted(w,"x\"y",false) prints "x\"y".

The appendable where the value is printed must not incur I/O operations. This method is not meant to be used for writing the values to permanent storage.

Throws:

IllegalStateException - if the print to the specified appendable fails due to I/O

println

public static void println(PrintWriter pw,
 Object o)

toScientificNotation

public static String toScientificNotation(BigDecimal bd)

Formats a BigDecimal value to a string in scientific notation For example

• A value of 0.00001234 would be formated as 1.234E-5
• A value of 100000.00 would be formated as 1.00E5
• A value of 100 (scale zero) would be formated as 1E2

If bd has a precision higher than 20, this method will truncate the output string to have a precision of 20 (no rounding will be done, just a truncate).

replace

public static String replace(String s,
 String find,
 String replace)

Replaces every occurrence of find in s with replace.

toURL

@Deprecated
public static URL toURL(File file)
                 throws MalformedURLException

Deprecated.

Creates a file-protocol URL for the given file.

Throws:

MalformedURLException

getFileTimestamp

@Deprecated
public static String getFileTimestamp()

Deprecated.

Gets a timestamp string for use in file names. The generated timestamp string reflects the current time.

stripDoubleQuotes

public static String stripDoubleQuotes(String value)

Converts double-quoted Java strings to their contents. For example, "foo\"bar" becomes foo"bar.

toJavaId

public static String toJavaId(String s,
 int ordinal)

Converts an arbitrary string into a string suitable for use as a Java identifier.

The mapping is one-to-one (that is, distinct strings will produce distinct java identifiers). The mapping is also reversible, but the inverse mapping is not implemented.

A valid Java identifier must start with a Unicode letter, underscore, or dollar sign ($). The other characters, if any, can be a Unicode letter, underscore, dollar sign, or digit.

This method uses an algorithm similar to URL encoding. Valid characters are unchanged; invalid characters are converted to an underscore followed by the hex code of the character; and underscores are doubled.

Examples:

• toJavaId("foo") returns "foo"
• toJavaId("foo bar") returns "foo_20_bar"
• toJavaId("foo_bar") returns "foo__bar"
• toJavaId("0bar") returns "_40_bar" (digits are illegal as a prefix)
• toJavaId("foo0bar") returns "foo0bar"

isValidJavaIdentifier

public static boolean isValidJavaIdentifier(String s)

Returns true when input string is a valid Java identifier.

Parameters:

s - input string

Returns:

true when input string is a valid Java identifier

toLinux

public static String toLinux(String s)

toList

@Deprecated
public static <T> List<T> toList(Iterator<T> iter)

Deprecated.

Materializes the results of a Iterator as a List.

Parameters:

iter - iterator to materialize

Returns:

materialized list

isNullOrEmpty

public static boolean isNullOrEmpty(@Nullable String s)

Returns whether s == null or if s.length() == 0.

commaList

public static <T> String commaList(List<T> list)

Converts a list of a string, with commas between elements.

For example, commaList(Arrays.asList({"a", "b"})) returns "a, b".

Parameters:

list - List

Returns:

String representation of string

sepList

public static <T> String sepList(List<T> list,
 String sep)

Converts a list of a string, with a given separator between elements.

printIterable

public static <E> StringBuilder printIterable(StringBuilder sb,
 Iterable<E> iterable)

Prints a collection of elements to a StringBuilder, in the same format as AbstractCollection.toString().

printList

public static StringBuilder printList(StringBuilder sb,
 int elementCount,
 ObjIntConsumer<StringBuilder> consumer)

Prints a set of elements to a StringBuilder, in the same format same as AbstractCollection.toString().

The 'set' is represented by the number of elements and an action to perform for each element.

This method can be a very efficient way to convert a structure to a string, because the components can write directly to the StringBuilder rather than constructing intermediate strings.

See Also:

• Functions.generate(int, java.util.function.IntFunction<E>)

getDefaultCharset

public static Charset getDefaultCharset()

Returns the Charset object representing the value of CalciteSystemProperty.DEFAULT_CHARSET.

Throws:

IllegalCharsetNameException - If the given charset name is illegal

UnsupportedCharsetException - If no support for the named charset is available in this instance of the Java virtual machine

newInternal

@Deprecated
public static Error newInternal()

Deprecated.

Throw new AssertionError

newInternal

@Deprecated
public static Error newInternal(String s)

Deprecated.

Throw new AssertionError

newInternal

@Deprecated
public static Error newInternal(Throwable e)

Deprecated.

Throw new RuntimeException if checked; throw raw exception if unchecked or Error

newInternal

public static Error newInternal(Throwable e,
 String s)

Deprecated.

Throw new AssertionError if applicable; or RuntimeException if e is checked; or raw exception if e is unchecked or Error.

throwIfUnchecked

@Deprecated
public static void throwIfUnchecked(Throwable throwable)

Deprecated.

As Throwables.throwIfUnchecked(Throwable).

throwAsRuntime

@API(since="1.26",
     status=EXPERIMENTAL)
public static RuntimeException throwAsRuntime(Throwable throwable)

This method rethrows input throwable as is (if its unchecked) or wraps it with RuntimeException and throws.

The typical usage would be throw throwAsRuntime(...), where throw statement is needed so Java compiler knows the execution stops at that line.

Parameters:

throwable - input throwable

Returns:

the method never returns, it always throws an unchecked exception

throwAsRuntime

@API(since="1.26",
     status=EXPERIMENTAL)
public static RuntimeException throwAsRuntime(String message,
 Throwable throwable)

This method rethrows input throwable as is (if its unchecked) with an extra message or wraps it with RuntimeException and throws.

The typical usage would be throw throwAsRuntime(...), where throw statement is needed so Java compiler knows the execution stops at that line.

Parameters:

throwable - input throwable

Returns:

the method never returns, it always throws an unchecked exception

toUnchecked

public static RuntimeException toUnchecked(Exception e)

Wraps an exception with RuntimeException and return it. If the exception is already an instance of RuntimeException, returns it directly.

causeOrSelf

@API(since="1.26",
     status=EXPERIMENTAL)
public static Throwable causeOrSelf(Throwable throwable)

Returns cause of the given throwable if it is non-null or the throwable itself.

Parameters:

throwable - input throwable

Returns:

cause of the given throwable if it is non-null or the throwable itself

getMessages

@Deprecated
public static String getMessages(Throwable t)

Deprecated.

Retrieves messages in a exception and writes them to a string. In the string returned, each message will appear on a different line.

Returns:

a non-null string containing all messages of the exception

getStackTrace

@Deprecated
public static String getStackTrace(Throwable t)

Deprecated.

Use Throwables.getStackTraceAsString(Throwable)

Returns the stack trace of a throwable. Called from native code.

Parameters:

t - Throwable

Returns:

Stack trace

pre

@Deprecated
public static void pre(boolean b,
 String description)

Deprecated.

Use Preconditions.checkArgument(boolean) or Objects.requireNonNull(Object)

post

@Deprecated
public static void post(boolean b,
 String description)

Deprecated.

Use Preconditions.checkArgument(boolean) or Objects.requireNonNull(Object)

permAssert

@Deprecated
public static void permAssert(boolean b,
 String description)

Deprecated.

Use Preconditions.checkArgument(boolean)

needToImplement

public static RuntimeException needToImplement(@Nullable Object o)

Returns a RuntimeException indicating that a particular feature has not been implemented, but should be.

If every 'hole' in our functionality uses this method, it will be easier for us to identity the holes. Throwing a UnsupportedOperationException isn't as good, because sometimes we actually want to partially implement an API.

Example usage:

class MyVisitor extends BaseVisitor {
     void accept(Foo foo) {
         // Exception will identify which subclass forgot to override
         // this method
         throw Util.needToImplement(this);
     }
 }

Parameters:

o - The object which was the target of the call, or null. Passing the object gives crucial information if a method needs to be overridden and a subclass forgot to do so.

Returns:

an UnsupportedOperationException.

deprecated

public static <T> T deprecated(T argument,
 boolean fail)

Deprecated.

If a piece of code calls this method, it indicates that the code needs to be cleaned up.

Flags a piece of code as needing to be cleaned up before you check in.

Introduce a call to this method to indicate that a piece of code, or a javadoc comment, needs work before you check in. If you have an IDE which can easily trace references, this is an easy way to maintain a to-do list.

Checked-in code must never call this method: you must remove all calls/references to this method before you check in.

The argument has generic type and determines the type of the result. This allows you to use the method inside an expression, for example

int x = Util.deprecated(0, false);

but the usual usage is to pass in a descriptive string.

Examples

Example #1: Using deprecated to fail if a piece of supposedly dead code is reached

void foo(int x) {
     if (x < 0) {
         // If this code is executed, an error will be thrown.
         Util.deprecated(
             "no longer need to handle negative numbers", true);
         bar(x);
     } else {
         baz(x);
     }
 }

Example #2: Using deprecated to comment out dead code

if (Util.deprecated(false, false)) {
     // This code will not be executed, but an error will not be thrown.
     baz();
 }

Parameters:

argument - Arbitrary argument to the method.

fail - Whether to throw an exception if this method is called

Returns:

The value of the argument.

contains

public static boolean contains(String[] a,
 int length,
 String s)

Returns whether an array of strings contains a given string among the first length entries.

Parameters:

a - Array of strings

length - Number of entries to search

s - String to seek

Returns:

Whether array contains the name

readAllAsString

@Deprecated
public static String readAllAsString(Reader reader)
                              throws IOException

Deprecated.

Reads all remaining contents from a Reader and returns them as a string.

Parameters:

reader - reader to read from

Returns:

reader contents as string

Throws:

IOException

squelchJar

@Deprecated
public static void squelchJar(@Nullable JarFile jar)

Deprecated.

Closes a Jar, ignoring any I/O exception. This should only be used in finally blocks when it's necessary to avoid throwing an exception which might mask a real exception.

Parameters:

jar - jar to close

squelchStream

@Deprecated
public static void squelchStream(@Nullable InputStream stream)

Deprecated.

Closes an InputStream, ignoring any I/O exception. This should only be used in finally blocks when it's necessary to avoid throwing an exception which might mask a real exception.

Parameters:

stream - stream to close

squelchStream

@Deprecated
public static void squelchStream(@Nullable OutputStream stream)

Deprecated.

Closes an OutputStream, ignoring any I/O exception. This should only be used in finally blocks when it's necessary to avoid throwing an exception which might mask a real exception. If you want to make sure that data has been successfully flushed, do NOT use this anywhere else; use stream.close() instead.

Parameters:

stream - stream to close

squelchReader

@Deprecated
public static void squelchReader(@Nullable Reader reader)

Deprecated.

Closes a Reader, ignoring any I/O exception. This should only be used in finally blocks when it's necessary to avoid throwing an exception which might mask a real exception.

Parameters:

reader - reader to close

squelchWriter

@Deprecated
public static void squelchWriter(@Nullable Writer writer)

Deprecated.

Closes a Writer, ignoring any I/O exception. This should only be used in finally blocks when it's necessary to avoid throwing an exception which might mask a real exception. If you want to make sure that data has been successfully flushed, do NOT use this anywhere else; use writer.close() instead.

Parameters:

writer - writer to close

squelchStmt

@Deprecated
public static void squelchStmt(@Nullable Statement stmt)

Deprecated.

Closes a Statement, ignoring any SQL exception. This should only be used in finally blocks when it's necessary to avoid throwing an exception which might mask a real exception.

Parameters:

stmt - stmt to close

squelchConnection

@Deprecated
public static void squelchConnection(@Nullable Connection connection)

Deprecated.

Closes a Connection, ignoring any SQL exception. This should only be used in finally blocks when it's necessary to avoid throwing an exception which might mask a real exception.

Parameters:

connection - connection to close

rtrim

@Deprecated
public static String rtrim(String s)

Deprecated.

Trims trailing spaces from a string.

Parameters:

s - string to be trimmed

Returns:

trimmed string

rpad

@Deprecated
public static String rpad(String s,
 int len)

Deprecated.

Use Spaces.padRight(String, int)

Pads a string with spaces up to a given length.

Parameters:

s - string to be padded

len - desired length

Returns:

padded string

toString

public static <T> String toString(Iterable<T> iterable,
 String start,
 String sep,
 String end)

Converts an iterable to a string.

lines

public static String lines(Iterable<String> strings)

Converts a list of strings to a string separated by newlines.

tokenize

public static Iterable<String> tokenize(String s,
 String delim)

Converts a string into tokens.

toPosix

public static String toPosix(TimeZone tz,
 boolean verbose)

Converts a Java timezone to POSIX format, so that the boost C++ library can instantiate timezone objects.

POSIX IEEE 1003.1 defines a format for timezone specifications.

The boost C++ library can read these specifications and instantiate posix_time_zone objects from them. The purpose of this method, therefore, is to allow the C++ code such as the fennel calculator to use the same notion of timezone as Java code.

The format is as follows:

"std offset dst [offset],start[/time],end[/time]"

where:

• 'std' specifies the abbrev of the time zone.
• 'offset' is the offset from UTC, and takes the form [+|-]hh[:mm[:ss]] {h=0-23, m/s=0-59}
• 'dst' specifies the abbrev of the time zone during daylight savings time
• The second offset is how many hours changed during DST. Default=1
• 'start' and 'end' are the dates when DST goes into (and out of) effect. They can each be one of three forms:
  1. Mm.w.d {month=1-12, week=1-5 (5 is always last), day=0-6}
  2. Jn {n=1-365 Feb29 is never counted}
  3. n {n=0-365 Feb29 is counted in leap years}
• 'time' has the same format as 'offset', and defaults to 02:00:00.

For example:

• "PST-8PDT01:00:00,M4.1.0/02:00:00,M10.1.0/02:00:00"; or more tersely
• "PST-8PDT,M4.1.0,M10.1.0"

(Real format strings do not contain spaces; they are in the above template only for readability.)

Boost apparently diverges from the POSIX standard in how it treats the sign of timezone offsets. The POSIX standard states 'If preceded by a '-', the timezone shall be east of the Prime Meridian; otherwise, it shall be west', yet boost requires the opposite. For instance, PST has offset '-8' above. This method generates timezone strings consistent with boost's expectations.

Parameters:

tz - Timezone

verbose - Whether to include fields which can be omitted because they have their default values

Returns:

Timezone in POSIX format (offset sign reversed, per boost's idiosyncracies)

parseLocale

public static Locale parseLocale(String localeString)

Parses a locale string.

The inverse operation of Locale.toString().

Parameters:

localeString - Locale string, e.g. "en" or "en_US"

Returns:

Java locale object

cast

public static <E> List<E> cast(List<? super E> list,
 Class<E> clazz)

Converts a list whose members are automatically down-cast to a given type.

If a member of the backing list is not an instanceof E, the accessing method (such as List.get(int)) will throw a ClassCastException.

All modifications are automatically written to the backing list. Not synchronized.

Parameters:

list - Backing list.

clazz - Class to cast to.

Returns:

A list whose members are of the desired type.

cast

public static <E extends @PolyNull Object>
Iterator<E> cast(Iterator<? extends @PolyNull Object> iter,
 Class<E> clazz)

Converts a iterator whose members are automatically down-cast to a given type.

If a member of the backing iterator is not an instance of E, Iterator.next()) will throw a ClassCastException.

All modifications are automatically written to the backing iterator. Not synchronized.

If the backing iterator has not-nullable elements, the returned iterator has not-nullable elements.

Parameters:

iter - Backing iterator

clazz - Class to cast to

Returns:

An iterator whose members are of the desired type.

cast

public static <E> Iterable<E> cast(Iterable<? super E> iterable,
 Class<E> clazz)

Converts an Iterable whose members are automatically down-cast to a given type.

All modifications are automatically written to the backing iterator. Not synchronized.

Parameters:

iterable - Backing iterable

clazz - Class to cast to

Returns:

An iterable whose members are of the desired type.

filter

public static <E> Iterable<E> filter(Iterable<?> iterable,
 Class<E> includeFilter)

Makes a collection of untyped elements appear as a list of strictly typed elements, by filtering out those which are not of the correct type.

The returned object is an Iterable, which makes it ideal for use with the 'foreach' construct. For example,

   List<Number> numbers = Arrays.asList(1, 2, 3.14, 4, null, 6E23);
   for (int myInt : filter(numbers, Integer.class)) {
     print(i);
   }
 

will print 1, 2, 4.

Parameters:

iterable - Iterable

includeFilter - Class whose instances to include

filter

public static <E> Collection<E> filter(Collection<?> collection,
 Class<E> includeFilter)

filter

public static <E> List<E> filter(List<?> list,
 Class<E> includeFilter)

Returns a subset of a list containing only elements of a given type.

Modifications to the list are NOT written back to the source list.

Parameters:

list - List of objects

includeFilter - Class to filter for

Returns:

List of objects of given class (or a subtype)

toMap

public static Map<String,String> toMap(Properties properties)

Converts a Properties object to a Map<String, String>.

This is necessary because Properties is a dinosaur class. It ought to extend Map<String,String>, but instead extends Hashtable<Object,Object>.

Typical usage, to iterate over a Properties:

Properties properties;
for (Map.Entry<String, String> entry = Util.toMap(properties).entrySet()) {
println("key=" + entry.getKey() + ", value=" + entry.getValue());
}

mapOf

public static <K,
V> Map<K,V> mapOf(K key,
 V value,
 Object... keyValues)

Returns a hashmap with given contents.

Use this method in initializers. Type parameters are inferred from context, and the contents are initialized declaratively. For example,

Map<String, Integer> population =
Olap4jUtil.mapOf(
"UK", 65000000,
"USA", 300000000);

Type Parameters:

K - Key type

V - Value type

Parameters:

key - First key

value - First value

keyValues - Second and sequent key/value pairs

Returns:

Map with given contents

unexpected

public static <E extends Enum<E>> Error unexpected(E value)

Returns an exception indicating that we didn't expect to find this enumeration here.

Parameters:

value - Enumeration value which was not expected

Returns:

an error, to be thrown

enumConstants

public static <T extends Enum<T>> Map<String,T> enumConstants(Class<T> clazz)

Creates a map of the values of an enumeration by name.

Parameters:

clazz - Enumeration class

Returns:

map of values

enumVal

public static <T extends Enum<T>> @Nullable T enumVal(Class<T> clazz,
 String name)

Returns the value of an enumeration with a particular name.

Similar to Enum.valueOf(Class, String), but returns null rather than throwing IllegalArgumentException.

Type Parameters:

T - Enum class type

Parameters:

clazz - Enum class

name - Name of enum constant

Returns:

Enum constant or null

enumVal

public static <T extends Enum<T>> T enumVal(T default_,
 @Nullable String name)

Returns the value of an enumeration with a particular or default value if not found.

Type Parameters:

T - Enum class type

Parameters:

default_ - Default value (not null)

name - Name of enum constant

Returns:

Enum constant, never null

quotientList

public static <E> List<E> quotientList(List<E> list,
 int n,
 int k)

Creates a list that returns every nth element of a list, starting at element k.

It is OK if the list is empty or its size is not a multiple of n.

For instance, quotientList(list, 2, 0) returns the even elements of a list, and quotientList(list, 2, 1) returns the odd elements. Those lists are the same length only if list has even size.

pairs

public static <E> List<Pair<E,E>> pairs(List<E> list)

Given a list with N elements [e₀, e₁, ..., e_N-1] (where N is even), returns a list of the N / 2 elements [ (e₀, e₁), (e₂, e₃), ... ].

first

public static <T> @PolyNull T first(@Nullable T v0,
 @PolyNull T v1)

Returns the first value if it is not null, otherwise the second value.

The result may be null only if the second argument is not null.

Equivalent to the Elvis operator (?:) of languages such as Groovy or PHP.

first

public static double first(@Nullable Double v0,
 double v1)

Unboxes a Double value, using a given default value if it is null.

first

public static float first(@Nullable Float v0,
 float v1)

Unboxes a Float value, using a given default value if it is null.

first

public static int first(@Nullable Integer v0,
 int v1)

Unboxes a Integer value, using a given default value if it is null.

first

public static long first(@Nullable Long v0,
 long v1)

Unboxes a Long value, using a given default value if it is null.

first

public static boolean first(@Nullable Boolean v0,
 boolean v1)

Unboxes a Boolean value, using a given default value if it is null.

first

public static short first(@Nullable Short v0,
 short v1)

Unboxes a Short value, using a given default value if it is null.

first

public static char first(@Nullable Character v0,
 char v1)

Unboxes a Character value, using a given default value if it is null.

first

public static byte first(@Nullable Byte v0,
 byte v1)

Unboxes a Byte value, using a given default value if it is null.

orEmpty

public static <T> Iterable<T> orEmpty(@Nullable Iterable<T> v0)

first

public <E> E first(List<E> list)

Returns the first element of a list.

Throws:

IndexOutOfBoundsException - if the list is empty

last

public static <E> E last(List<E> list)

Returns the last element of a list.

Throws:

IndexOutOfBoundsException - if the list is empty

first

public static <E> List<E> first(List<E> list,
 int n)

Returns the first n elements of a list.

skipLast

public static <E> List<E> skipLast(List<E> list)

Returns every element of a list but its last element.

skipLast

public static <E> List<E> skipLast(List<E> list,
 int n)

Returns every element of a list but its last n elements.

last

public static <E> List<E> last(List<E> list,
 int n)

Returns the last n elements of a list.

skip

public static <E> List<E> skip(List<E> list)

Returns all but the first element of a list.

skip

public static <E> List<E> skip(List<E> list,
 int fromIndex)

Returns all but the first n elements of a list.

range

public static List<Integer> range(int end)

range

public static List<Integer> range(int start,
 int end)

isDistinct

public static <E> boolean isDistinct(List<E> list)

Returns whether the elements of list are distinct.

firstDuplicate

public static <E> int firstDuplicate(List<E> list)

Returns the ordinal of the first element in the list which is equal to a previous element in the list.

For example, firstDuplicate(Arrays.asList("a", "b", "c", "b", "a")) returns 3, the ordinal of the 2nd "b".

Parameters:

list - List

Returns:

Ordinal of first duplicate, or -1 if not found

isDefinitelyDistinctAndNonNull

public static <E> boolean isDefinitelyDistinctAndNonNull(List<? extends @Nullable E> list)

Returns whether the elements of list are definitely distinct and not null, working quickly and sometimes giving false negatives for large lists.

A return of true means that the list is distinct (true positive); a return of false means either that list is not distinct (true negative) or that the list is large and distinct (false negative). (If the list is large, a hash map would be required to do an accurate job, and this method does its best quickly.)

distinctList

public static <E> List<E> distinctList(List<E> list)

Converts a list into a list with unique elements.

The order is preserved; the second and subsequent occurrences are removed.

If the list is already unique it is returned unchanged.

distinctList

public static <E> List<E> distinctList(Iterable<E> keys)

Converts an iterable into a list with unique elements.

The order is preserved; the second and subsequent occurrences are removed.

If iterable is a unique list it is returned unchanged.

intersects

public static <E> boolean intersects(Collection<E> c0,
 Collection<E> c1)

Returns whether two collections have any elements in common.

findMatch

public static int findMatch(List<String> strings,
 String seek,
 boolean caseSensitive)

Looks for a string within a list of strings, using a given case-sensitivity policy, and returns the position at which the first match is found, or -1 if there are no matches.

matches

public static boolean matches(boolean caseSensitive,
 String s0,
 String s1)

Returns whether a name matches another according to a given case-sensitivity policy.

startsWith

public static <E> boolean startsWith(List<E> list0,
 List<E> list1)

Returns whether one list is a prefix of another.

listToString

public static String listToString(List<String> list)

Converts ["ab", "c"] to "ab"."c".

stringToList

public static List<String> stringToList(String s)

human

public static String human(double d)

Converts a number into human-readable form, with 3 digits and a "K", "M" or "G" multiplier for thousands, millions or billions.

Examples: -2, 0, 1, 999, 1.00K, 1.99K, 3.45M, 4.56B.

asIndexMapJ

public static <K,
V> Map<K,V> asIndexMapJ(Collection<V> values,
 Function<V,K> function)

Returns a map that is a view onto a collection of values, using the provided function to convert a value to a key.

Unlike Maps.uniqueIndex(Iterable, com.google.common.base.Function), returns a view whose contents change as the collection of values changes.

Type Parameters:

K - Key type

V - Value type

Parameters:

values - Collection of values

function - Function to map value to key

Returns:

Map that is a view onto the values

asIndexMap

@Deprecated
public static <K,
V> Map<K,V> asIndexMap(Collection<V> values,
 com.google.common.base.Function<V,K> function)

Deprecated.

debugCode

public static void debugCode(PrintStream out,
 String code)

Prints the given code with line numbering.

immutableCopy

public static <E> List<List<E>> immutableCopy(Iterable<? extends Iterable<E>> lists)

Returns a copy of a list of lists, making the component lists immutable if they are not already.

printWriter

public static PrintWriter printWriter(OutputStream out)

Creates a PrintWriter to a given output stream using UTF-8 character set.

Does not use the default character set.

printWriter

public static PrintWriter printWriter(File file)
                               throws FileNotFoundException

Creates a PrintWriter to a given file using UTF-8 character set.

Does not use the default character set.

Throws:

FileNotFoundException

reader

public static BufferedReader reader(InputStream in)

Creates a BufferedReader to a given input stream using UTF-8 character set.

Does not use the default character set.

reader

public static BufferedReader reader(File file)
                             throws FileNotFoundException

Creates a BufferedReader to read a given file using UTF-8 character set.

Does not use the default character set.

Throws:

FileNotFoundException

asStringBuilder

public static void asStringBuilder(Appendable appendable,
 Consumer<StringBuilder> consumer)

Given an Appendable, performs an action that requires a StringBuilder. Casts the Appendable if possible.

calendar

public static Calendar calendar()

Creates a Calendar in the UTC time zone and root locale. Does not use the time zone or locale.

calendar

public static Calendar calendar(long millis)

Creates a Calendar in the UTC time zone and root locale with a given time.

toImmutableList

@Deprecated
public static <T>
Collector<T,?,com.google.common.collect.ImmutableList<T>> toImmutableList()

Deprecated.

Use ImmutableList.toImmutableList()

Returns a Collector that accumulates the input elements into a Guava ImmutableList via a ImmutableList.Builder.

combine

public static <E>
com.google.common.collect.ImmutableList.Builder<E> combine(com.google.common.collect.ImmutableList.Builder<E> b0,
 com.google.common.collect.ImmutableList.Builder<E> b1)

Combines a second immutable list builder into a first.

combine

public static <E> ArrayList<E> combine(ArrayList<E> list0,
 ArrayList<E> list1)

Combines a second array list into a first.

andThen

public static <X> UnaryOperator<X> andThen(UnaryOperator<X> op1,
 UnaryOperator<X> op2)

Returns an operator that applies op1 and then op2.

As Function.andThen(Function) but for UnaryOperator.

transform

public static <F,
T> List<T> transform(List<? extends F> list,
 Function<? super F,? extends T> function)

Transforms a list, applying a function to each element.

transformIndexed

public static <F,
T> List<T> transformIndexed(List<? extends F> list,
 BiFunction<? super F,Integer,? extends T> function)

Transforms a list, applying a function to each element, also passing in the element's index in the list.

transform

@API(since="1.27",
     status=EXPERIMENTAL)
public static <F,
T> Iterable<T> transform(Iterable<? extends F> iterable,
 Function<? super F,? extends T> function)

Transforms an iterable, applying a function to each element.

transform

@API(since="1.27",
     status=EXPERIMENTAL)
public static <F,
T> Iterator<T> transform(Iterator<? extends F> iterator,
 Function<? super F,? extends T> function)

Transforms an iterator.

filter

@API(since="1.27",
     status=EXPERIMENTAL)
public static <E> Iterable<E> filter(Iterable<? extends E> iterable,
 Predicate<? super E> predicate)

Filters an iterable.

filter

@API(since="1.27",
     status=EXPERIMENTAL)
public static <E> Iterator<E> filter(Iterator<? extends E> iterator,
 Predicate<? super E> predicate)

Filters an iterator.

moveToHead

public static <E> List<E> moveToHead(List<? extends E> terms,
 Predicate<? super E> predicate)

Returns a list with any elements for which the predicate is true moved to the head of the list. The algorithm does not modify the list, is stable, and is idempotent.

select

public static <E> List<E> select(List<E> list,
 List<Integer> ordinals)

Returns a view of a list, picking the elements of a list with the given set of ordinals.

blackholeMap

public static <K,
V> Map<K,V> blackholeMap()

Returns a map which ignores any write operation.