Skip to content

Ghidra is a software reverse engineering (SRE) framework

13.0 KB
Raw Blame
/* ###
 * IP: GHIDRA
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package util;

import java.util.*;
import java.util.stream.Stream;
import java.util.stream.StreamSupport;

import org.apache.commons.collections4.IterableUtils;
import org.apache.commons.collections4.IteratorUtils;
import org.apache.commons.lang3.ObjectUtils;
import org.apache.commons.lang3.StringUtils;

import ghidra.util.task.CancellableIterator;
import ghidra.util.task.TaskMonitor;

/**
 * A collection of utility methods that prevent you from having to do unsafe casts of
 * {@link Collection} classes due to runtime type erasure.
 *
 * <P>Be sure to check Apache collection utils before using this class, as it's a
 * standard utility and often more efficient.
 *
 * <P>Some examples:
 * <OL>
 *  <LI>{@link org.apache.commons.collections4.CollectionUtils}</LI>
 *  <LI>{@link IterableUtils}</LI>
 *  <LI>{@link IteratorUtils}</LI>
 *  <LI>{@link StringUtils#join(Iterable, char)} - for pretty printing collections with newlines</LI>
 *  <LI><code>Apache CollectionUtils.collect(Collection, Transformer)</code> - to turn a
 *      collection in to collection of strings when the default <code>toString()</code> is lacking</LI>
 * </OL>
 */
public class CollectionUtils {

	private CollectionUtils() {
		// utility class; can't create
	}

	/**
	 * Turns the given items into a set.  If there is only a single item and it is null, then
	 * an empty set will be returned.
	 *
	 * @param items the items to put in the set
	 * @return the list of items
	 */
	@SafeVarargs
	public static <T> Set<T> asSet(T... items) {
		Set<T> set = new HashSet<>();
		if (items == null) {
			return set;
		}

		if (items.length == 1 && items[0] == null) {
			return set;
		}

		for (T e : items) {
			set.add(e);
		}
		return set;
	}

	@SuppressWarnings({ "rawtypes", "unchecked" })
	public static <T> Set<T> asSet(Collection<T> c) {
		if (c instanceof Set) {
			return (Set) c;
		}
		if (c == null) {
			return new HashSet<>();
		}

		return new HashSet<>(c);
	}

	/**
	 * Drains the given iterator into a new Set
	 *
	 * @param it the iterator
	 * @return the set
	 */
	public static <T> Set<T> asSet(Iterator<T> it) {
		Set<T> set = new HashSet<>();
		if (it == null) {
			return set;
		}

		while (it.hasNext()) {
			T t = it.next();
			set.add(t);
		}
		return set;
	}

	/**
	 * Turns the given iterable into a new Set, returning it directly if it is a set, draining
	 * it into a set if it is not already.
	 *
	 * @param iterable the iterable
	 * @return the set
	 */
	public static <T> Set<T> asSet(Iterable<T> iterable) {
		if (iterable instanceof Set) {
			return (Set<T>) iterable;
		}

		Set<T> set = new HashSet<>();
		if (iterable == null) {
			return set;
		}

		Iterator<T> it = iterable.iterator();
		while (it.hasNext()) {
			T t = it.next();
			set.add(t);
		}
		return set;
	}

	/**
	 * Similar to {@link Arrays#asList(Object...)}, except that this method will turn a single
	 * null parameter into an empty list.  Also, this method creates a new, mutable array,
	 * whereas the former's array is not mutable.
	 *
	 * @param items the items to add to the list
	 * @return the list
	 */
	@SafeVarargs
	public static <T> List<T> asList(T... items) {
		List<T> list = new ArrayList<>();
		if (items == null) {
			return list;
		}

		if (items.length == 1 && items[0] == null) {
			return list;
		}

		for (T arrayElement : items) {
			list.add(arrayElement);
		}

		return list;
	}

	/**
	 * Returns the given list if not null, otherwise returns an empty list. This is
	 * useful for clients avoid null checks.
	 *
	 * @param list the list to check
	 * @return a non-null collection
	 */
	public static <T> List<T> asList(List<T> list) {
		if (list == null) {
			return new ArrayList<>();
		}
		return list;
	}

	/**
	 * A convenient way to check for null and whether the given collection is a {@link List}.
	 * If the value is a list, then it is returned.  If the value is null, an empty list is
	 * returned.  Otherwise, a new list is created from the given collection.
	 *
	 * @param c the collection to check
	 * @return a list
	 */
	public static <T> List<T> asList(Collection<T> c) {
		if (c instanceof List) {
			return (List<T>) c;
		}
		if (c == null) {
			return new ArrayList<>();
		}
		return new ArrayList<>(c);
	}

	/**
	 * Returns the given collection if not null, an empty collection (a Set) otherwise.  This is
	 * useful for clients avoid null checks.
	 *
	 * @param c the collection to check
	 * @return a non-null collection
	 */
	public static <T> Collection<T> nonNull(Collection<T> c) {
		return asCollection(c);
	}

	/**
	 * Returns the given collection if not null, an empty collection otherwise.  This is
	 * useful for clients avoid null checks.
	 *
	 * @param c the collection to check
	 * @return a non-null collection
	 */
	public static <T> Collection<T> asCollection(Collection<T> c) {
		if (c == null) {
			return new HashSet<>();
		}
		return c;
	}

	public static <T> List<T> asList(Enumeration<T> enumeration) {
		List<T> list = new ArrayList<>();
		if (enumeration == null) {
			return list;
		}

		while (enumeration.hasMoreElements()) {
			T t = enumeration.nextElement();
			list.add(t);
		}
		return list;
	}

	public static <T> List<T> asList(Iterable<T> it) {
		return asList(it.iterator());
	}

	public static <T> List<T> asList(Iterator<T> it) {
		List<T> list = new ArrayList<>();
		if (it == null) {
			return list;
		}

		while (it.hasNext()) {
			T t = it.next();
			list.add(t);
		}
		return list;
	}

	/**
	 * Checks that the elements in the given list are of the type specified by <code>clazz</code>
	 * and then casts the list to be of the specified type.
	 *
	 * @param list  the source list
	 * @param clazz the class of T
	 * @return a casted list of type T
	 * @throws IllegalArgumentException if the given list contains elements that are not of the
	 *         type specified by <code>clazz</code>.
	 */
	@SuppressWarnings("unchecked")
	// we checked the elements of the list
	public static <T> List<T> asList(List<?> list, Class<T> clazz) {

		if (list == null) {
			return new ArrayList<>();
		}

		for (Object object : list) {
			if (!clazz.isAssignableFrom(object.getClass())) {
				throw new IllegalArgumentException("Given list contains data that is not " +
					"the type: " + clazz + ".  Value: " + object.getClass());
			}
		}

		return (List<T>) list;
	}

	/**
	 * Checks that the elements in the given collection are of the type specified by
	 * <code>clazz</code> and then casts the collection to be of the specified type.
	 *
	 * @param collection  the source collection
	 * @param clazz the class of T
	 * @return a casted list of type T
	 * @throws IllegalArgumentException if the given collection contains elements that are
	 *         not of the type specified by <code>clazz</code>.
	 */
	@SuppressWarnings("unchecked")
	// we checked the elements of the collection
	public static <T> Collection<T> asCollection(Collection<?> collection, Class<T> clazz) {
		for (Object object : collection) {
			if (!clazz.isAssignableFrom(object.getClass())) {
				throw new IllegalArgumentException("Given collection contains data that is not " +
					"the type: " + clazz + ".  Value: " + object.getClass());
			}
		}

		return (Collection<T>) collection;
	}

	/**
	 * Returns true if each item in the list is of type clazz.
	 * @param <T>     the type
	 * @param list    the list to inspect
	 * @param clazz   the class type
	 * @return true if each item in the list is of type clazz
	 */
	public static <T> boolean isAllSameType(Collection<?> list, Class<T> clazz) {
		for (Object object : list) {
			if (!clazz.isAssignableFrom(object.getClass())) {
				return false;
			}
		}
		return true;
	}

	/**
	 * Returns true if the given item is in the collection of possible items
	 *
	 * @param t the item in question
	 * @param possibles the set of things
	 * @return true if the given item is in the collection of possible items
	 */
	@SafeVarargs // this is safe, as we are only using Object methods
	public static <T> boolean isOneOf(T t, T... possibles) {
		for (T possible : possibles) {
			if (Objects.equals(possible, t)) {
				return true;
			}
		}
		return false;
	}

	/**
	 * Returns true if all the given objects are null.
	 *
	 * <P>See also apache {@link ObjectUtils#anyNotNull(Object...)} and
	 * {@link ObjectUtils#allNotNull(Object...)}
	 *
	 * @param objects the objects to check
	 * @return true if all the given objects are null
	 */
	public static boolean isAllNull(Object... objects) {
		return isAllNull(Arrays.asList(objects));
	}

	/**
	 * Returns true if all the given objects are null.
	 *
	 * <P>See also apache {@link ObjectUtils#anyNotNull(Object...)} and
	 * {@link ObjectUtils#allNotNull(Object...)}
	 *
	 * @param c the objects to check
	 * @return true if all the given objects are null
	 */
	public static <T> boolean isAllNull(Collection<T> c) {
		if (c == null) {
			return true;
		}

		for (T t : c) {
			if (t != null) {
				return false;
			}
		}
		return true;
	}

	/**
	 * Returns true if the given array is null or has 0 length
	 *
	 * @param c the collection to check
	 * @return true if blank
	 */
	public static <T> boolean isBlank(Collection<T> c) {
		return c == null || c.isEmpty();
	}

	/**
	 * Returns true if the given array is null or has 0 length
	 *
	 * @param t the items to check
	 * @return true if blank
	 */
	@SuppressWarnings("unchecked")
	public static <T> boolean isBlank(T... t) {
		return t == null || t.length == 0;
	}

	/**
	 * Turns the given item into an iterable
	 * @param t the object from which to create an iterable
	 * @return an iterable over the given iterator
	 */
	public static <T> Iterable<T> asIterable(T t) {
		return Arrays.asList(t);
	}

	/**
	 * Returns an iterable over an iterator
	 * @param iterator the iterator to create an iterable from
	 * @return an iterable over the given iterator
	 */
	public static <T> Iterable<T> asIterable(Iterator<T> iterator) {
		return () -> iterator;
	}

	/**
	 * Combines all collections passed-in into a pass-through (not creating a new collection)
	 * Iterable.
	 *
	 * @param iterables the iterables to combine
	 * @return the iterable
	 */
	@SafeVarargs
	public static <T> Iterable<T> asIterable(Iterable<T>... iterables) {
		Stream<T> s = asStream(iterables);
		return asIterable(s.iterator());
	}

	/**
	 * Combines all collections passed-in into a pass-through (not creating a new collection)
	 * Iterable that uses the given task monitor.
	 *
	 * @param monitor a task monitor that allows for cancelling iteration
	 * @param iterables the iterables to combine
	 * @return the iterable
	 */
	@SafeVarargs
	public static <T> Iterable<T> asCancellableIterable(TaskMonitor monitor,
			Iterable<T>... iterables) {
		Stream<T> s = asStream(iterables);
		Iterator<T> it = s.iterator();
		CancellableIterator<T> cancellable = new CancellableIterator<>(it, monitor);
		return asIterable(cancellable);
	}

	/**
	 * Turns the given iterator into a stream
	 *
	 * @param iterator the iterator
	 * @return the stream
	 */
	public static <T> Stream<T> asStream(Iterator<T> iterator) {
		return asStream(asIterable(iterator));
	}

	/**
	 * Combines all iterables passed-in into a pass-through (not creating a new collection) Stream.
	 *
	 * @param iterables the iterables to combine
	 * @return the stream
	 */
	@SafeVarargs
	public static <T> Stream<T> asStream(Iterable<T>... iterables) {
		Stream<T> s =
			Stream.of(iterables).flatMap(e -> StreamSupport.stream(e.spliterator(), false));
		return s;
	}

	/**
	 * Returns an element from the given collection; null if the collection is null or empty.
	 * This is meant for clients that have a collection with any number of items and just need
	 * to get one.
	 *
	 * @param c the collection
	 * @return the item
	 */
	public static <T> T any(Collection<T> c) {
		return any((Iterable<T>) c);
	}

	/**
	 * Returns an element from the given iterable; null if the iterable is null or empty.
	 * This is meant for clients that have a collection with any number of items and just need
	 * to get one.
	 *
	 * @param iterable the items
	 * @return the item
	 */
	public static <T> T any(Iterable<T> iterable) {
		if (iterable == null) {
			return null;
		}

		Iterator<T> iterator = iterable.iterator();
		if (iterator.hasNext()) {
			return iterator.next();
		}
		return null;
	}

	/**
	 * Returns the only element from the given collection; null if the collection is null or empty
	 * or size is greater than 1. This is meant to clients to get the one and only element in 
	 * a collection of size 1.
	 *
	 * @param c the collection
	 * @return the item
	 * @see #any(Collection)
	 */
	public static <T> T get(Collection<T> c) {
		if (c == null || c.size() > 1) {
			return null;
		}
		return any((Iterable<T>) c);
	}

}