All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.nervousync.utils.CollectionUtils Maven / Gradle / Ivy

Go to download

Java utility collections, development by Nervousync Studio (NSYC)

There is a newer version: 1.2.1
Show newest version
/*
 * Licensed to the Nervousync Studio (NSYC) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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 org.nervousync.utils;

import java.lang.reflect.Array;
import java.util.*;

/**
 * 
Collection Utilities

 * 
 *     Current utilities implements features:
 *     
    Check collection is empty

 *     
    Check collection contains target element

 *     
    Check two collection contains the same element

 *     
    Check collection contains unique element

 *     
    Convert object to array list

 *     
    Merge array to list

 *     
    Merge properties to map

 *     
    Find the first match element of collection

 * 
 * 
数据集合工具集

 * 
 *     此工具集实现以下功能:
 *     
    检查集合是否为空

 *     
    检查集合是否包含目标对象

 *     
    检查两个集合是否包含同一元素

 *     
    检查集合是否有唯一元素

 *     
    转换对象为列表

 *     
    合并数组到列表中

 *     
    合并属性信息实例到哈希表中

 *     
    从集合中寻找第一个符合要求的元素

 * 
 *
 * @author Steven Wee	[email protected]
 * @version $Revision: 1.2.0 $ $Date: Jan 13, 2010 16:27:49 $
 */
public final class CollectionUtils {
	/**
	 * 
Private constructor for CollectionUtils

	 * 
数据集合工具集的私有构造方法

	 */
	private CollectionUtils() {
	}
	/**
	 * 
Check given collection instance is empty

	 * 
	 *     Return true if the supplied Collection is null
	 *     or empty. Otherwise, return false.
	 * 
	 * 
检查给定的集合实例对象是否为空

	 * 当给定的集合实例对象为null或者集合为空返回true，否则返回false
	 *
	 * @param collection 	collection instance
	 *                      集合实例对象
	 *
	 * @return 	whether the given Collection is empty
	 * 			给定的集合实例对象是否为空
	 */
	public static boolean isEmpty(final Collection collection) {
		return (collection == null || collection.isEmpty());
	}
	/**
	 * 
Check given collection instance is empty

	 * 
	 *     Return true if the supplied Collection is null
	 *     or empty. Otherwise, return false.
	 * 
	 * 
检查给定的集合实例对象是否为空

	 * 当给定的集合实例对象为null或者集合为空返回true，否则返回false
	 *
	 * @param objects 	array instance
	 *                  数组实例对象
	 *
	 * @return 	whether the given Collection is empty
	 * 			给定的集合实例对象是否为空
	 */
	public static boolean isEmpty(final Object[] objects) {
		return (objects == null || objects.length == 0);
	}
	/**
	 * 
Check given map instance is empty

	 * 
	 *     Return true if the supplied Map is null
	 *     or empty. Otherwise, return false.
	 * 
	 * 
检查给定的Map实例对象是否为空

	 * 当给定的Map实例对象为null或者集合为空返回true，否则返回false
	 *
	 * @param map 	Map instance
	 *              Map实例对象
	 *
	 * @return 	whether the given map is empty
	 * 			给定的Map实例对象是否为空
	 */
	public static boolean isEmpty(final Map map) {
		return (map == null || map.isEmpty());
	}
    /**
	 * 
Append the given Object to the given array, returning a new array consisting of the input array contents plus the given Object.

	 * 
将给定的对象附加到给定的数组，返回一个由输入数组内容加上给定的对象组成的新数组。

     *
     * @param array 	the array to append to (can be null)
	 *                  要附加到的数组（可以为 null）
     * @param obj   	the Object to append
	 *                  要附加的对象
	 *
	 * @return 	the new array of the same component type; (never null)
	 * 			相同组件类型的新数组；（永远不为null）
     */
    public static Object[] addObjectToArray(final Object[] array, final Object obj) {
        Class compType = Object.class;
        if (array != null) {
            compType = array.getClass().getComponentType();
        } else if (obj != null) {
            compType = obj.getClass();
        }
        int newArrLength = (array != null ? array.length + 1 : 1);
        Object[] newArr = (Object[]) Array.newInstance(compType, newArrLength);
        if (array != null) {
            System.arraycopy(array, 0, newArr, 0, array.length);
        }
        newArr[newArr.length - 1] = obj;
        return newArr;
    }
    /**
	 * 
Convert the given array (which may be a primitive array) to an object array (if necessary of primitive wrapper objects).

	 * A null source value will be converted to an empty Object array.
	 * 
将给定数组（可能是原始数组）转换为对象数组（如果需要原始包装对象）。

	 * null 源值将转换为空对象数组。
	 *
	 * @param source 	the (potentially primitive) array
	 *                  可能为基础类型的实例对象（数组）
	 *
	 * @return 	the corresponding object array (never null)
	 * 			相应的对象数组（永远不为null）
	 *
     * @throws IllegalArgumentException
	 * if the parameter is not an array
	 * 如果参数不是数组
     */
    public static Object[] toArray(final Object source) {
        if (source instanceof Object[]) {
            return (Object[]) source;
        }
        if (source == null) {
            return new Object[0];
        }
        if (!source.getClass().isArray()) {
            throw new IllegalArgumentException("Source is not an array: " + source);
        }
        int length = Array.getLength(source);
        if (length == 0) {
            return new Object[0];
        }
        Class wrapperType = Array.get(source, 0).getClass();
        Object[] newArray = (Object[]) Array.newInstance(wrapperType, length);
        for (int i = 0; i < length; i++) {
            newArray[i] = Array.get(source, i);
        }
        return newArray;
    }
	/**
	 * 
Convert supplied object (or array) instance to a List

	 * 
	 *     Convert the supplied array into a List. A primitive array gets
	 *     converted into a List of the appropriate wrapper type.
	 *     
A null source value will be converted to an empty List.
	 * 
	 * 
转换支持的实例对象为列表

	 * 转换支持的实例对象（数组）为列表。基础数据类型的数据转换为对应包装类对象列表。实例对象为null将返回一个空列表
	 *
	 * @param source 	the (potentially primitive) array
	 *                  可能为基础类型的实例对象（数组）
	 *
	 * @return 	the converted List result
	 * 			转换后的列表结果
	 */
	public static List toList(final Object source) {
		if (source instanceof Collection) {
			return new ArrayList<>((Collection) source);
		} else if (source instanceof Enumeration) {
			List list = new ArrayList<>();
			Enumeration enumeration = (Enumeration) source;
			while(enumeration.hasMoreElements()) {
				list.add(enumeration.nextElement());
			}
			return list;
		} else if (source instanceof Iterator) {
			List list = new ArrayList<>();
			Iterator iterator = (Iterator)source;
			while(iterator.hasNext()) {
				list.add(iterator.next());
			}
			return list;
		} else if (source instanceof Map) {
			return new ArrayList<>(((Map) source).entrySet());
		} else {
			return Arrays.asList(toArray(source));
		}
	}
	/**
	 * 
Merge the given array into the given Collection.

	 * 
合并给定的数组到给定的集合中

	 *
	 * @param array 		the array to merge (maybe null)
	 *                      要合并的数组（有可能为null）
	 * @param collection 	the target Collection to merge the array into
	 *                      将数组合并到的目标集合
	 */
	public static void mergeArrayIntoCollection(final Object array, final Collection collection) {
		if (collection == null) {
			throw new IllegalArgumentException("Collection must not be null");
		}
		Collections.addAll(collection, toArray(array));
	}
	/**
	 * 
Merge the given Properties instance into the given Map.

	 * 
	 *     Merge the given Properties instance into the given Map,
	 *     copying all properties (key-value pairs) over.
	 *     Uses Properties.propertyNames() to even catch
	 *     default properties linked into the original Properties instance.
	 * 
	 * 
合并给定的配置文件实例到给定的Map中

	 * 合并给定的配置文件实例到给定的Map中，复制所有的配置键值对。
	 *
	 * @param props 	the Properties instance to merge (maybe null)
	 *                  要合并的属性实例（可能为 null）
	 * @param map 		the target Map to merge the properties into
	 *                  将属性合并到的目标 Map
	 */
	public static void mergePropertiesIntoMap(final Properties props, final Map map) {
		if (map == null) {
			throw new IllegalArgumentException("Map must not be null");
		}
		if (props != null) {
			for (Enumeration en = props.propertyNames(); en.hasMoreElements();) {
				String key = (String) en.nextElement();
				map.put(key, props.getProperty(key));
			}
		}
	}
	/**
	 * 
Check whether the given Iterator contains the given element.

	 * 
检查给定的迭代器是否包含给定的元素。

	 *
	 * @param iterator 	the Iterator to check
	 *                  要检查的迭代器
	 * @param element 	the element to look for
	 *                  要寻找的元素
	 *
	 * @return 	true if found, false otherwise
	 * 			如果找到返回true，否则返回false
	 */
	public static  boolean contains(final Iterator iterator, final T element) {
		if (iterator != null) {
			while (iterator.hasNext()) {
				if (ObjectUtils.nullSafeEquals(iterator.next(), element)) {
					return Boolean.TRUE;
				}
			}
		}
		return Boolean.FALSE;
	}
	/**
	 * 
Check whether the given Enumeration contains the given element.

	 * 
检查给定的枚举是否包含给定的元素。

	 *
	 * @param enumeration 	the Enumeration to check
	 *                      要检查的枚举
	 * @param element 		the element to look for
	 *                  	要寻找的元素
	 *
	 * @return 	true if found, false otherwise
	 * 			如果找到返回true，否则返回false
	 */
	public static  boolean contains(final Enumeration enumeration, final T element) {
		if (enumeration != null) {
			while (enumeration.hasMoreElements()) {
				if (ObjectUtils.nullSafeEquals(enumeration.nextElement(), element)) {
					return Boolean.TRUE;
				}
			}
		}
		return Boolean.FALSE;
	}
	/**
	 * 
Check whether the given Collection contains the given element instance.

	 * 
	 *     Enforces the given instance to be present, rather than returning
	 *     true for an equal element as well.
	 * 
	 * 
检查给定的集合是否包含给定的元素实例。

	 * 强制给定实例存在，而不是对于相等的元素也返回 true。
	 *
	 * @param collection 	the Collection to check
	 *                      要检查的集合
	 * @param element 		the element to look for
	 *                  	要寻找的元素
	 *
	 * @return 	true if found, false otherwise
	 * 			如果找到返回true，否则返回false
	 */
	public static  boolean contains(final Collection collection, final T element) {
		if (collection != null) {
			return collection.stream().anyMatch(candidate -> ObjectUtils.nullSafeEquals(candidate, element));
		}
		return Boolean.FALSE;
	}
	/**
	 * 
Check whether the given Collections contains the same element instance.

	 * 
检查给定的集合是否包含相同的元素实例。

	 *
	 * @param source 		the source Collection
	 *                      源集合
	 * @param candidates 	the candidates to search for
	 *                      要搜索的候选元素
	 *
	 * @return 	true if found, false otherwise
	 * 			如果找到返回true，否则返回false
	 */
	public static  boolean containsAny(final Collection source, final Collection candidates) {
		if (isEmpty(source) || isEmpty(candidates)) {
			return false;
		}
		return candidates.stream().anyMatch(source::contains);
	}
	/**
	 * 
Find the first element of the given Collections contains the same element instance.

	 * 
寻找给定的集合包含的第一个相同的元素实例。

	 *
	 * @param source 		the source Collection
	 *                      源集合
	 * @param candidates 	the candidates to search for
	 *                      要搜索的候选元素
	 *
	 * @return 	the first present object, or null if not found
	 * 			找到的第一个元素，如果未找到返回null
	 */
	public static  T findFirstMatch(final Collection source, final Collection candidates) {
		if (isEmpty(source) || isEmpty(candidates)) {
			return null;
		}
		return candidates.stream().filter(source::contains).findFirst().orElse(null);
	}
	/**
	 * 
Find a single value of the given type in the given Collection.

	 * 
在给定集合中查找给定类型的单个值。

	 *
	 * @param collection 	the Collection to search
	 *                      要查询的集合
	 * @param type 			the type to look for
	 *                      要寻找的类型
	 *
	 * @return
	 * a value of the given type found if there is a clear match, or null if none or more than one such value found
	 * 如果存在明确匹配，则找到给定类型的值；如果未找到或找到多个此类值，则返回 null
	 */
	public static  T findValueOfType(final Collection collection, final Class type) {
		if (isEmpty(collection) || type == null) {
			return null;
		}
		return collection.stream()
				.filter(type::isInstance)
				.findFirst()
				.orElse(null);
	}
	/**
	 * 
Find a single value of one of the given types in the given Collection

	 * 
	 *     searching the Collection for a value of the first type, then
	 *     searching for a value of the second type, etc.
	 * 
	 * 
在给定集合中查找给定类型之一的单个值

	 * 在 Collection 中搜索第一种类型的值，然后搜索第二种类型的值，依此类推。
	 *
	 * @param collection 	the Collection to search
	 *                      要查询的集合
	 * @param types 		the types to look for, in prioritized order
	 *                      要查找的类型（按优先顺序）
	 *
	 * @return
	 * a value of the given type found if there is a clear match, or null if none or more than one such value found
	 * 如果存在明确匹配，则找到给定类型的值；如果未找到或找到多个此类值，则返回 null
	 */
	public static  T findValueOfTypes(final Collection collection, final Class[] types) {
		if (isEmpty(collection) || isEmpty(types)) {
			return null;
		}
		for (Class type : types) {
			T value = findValueOfType(collection, type);
			if (value != null) {
				return value;
			}
		}
		return null;
	}
	/**
	 * 
Determine whether the given Collection only contains a single unique object.

	 * 
确定给定的集合是否仅包含单个唯一对象。

	 *
	 * @param collection 	the Collection to check
	 *                      要检查的集合
	 *
	 * @return
	 * 
	 *     true if the collection contains a single reference
	 *     or multiple references to the same instance, false else
	 * 
	 * 如果集合包含对同一实例的单个引用或多个引用，则为 true，否则为 false
	 */
	public static boolean hasUniqueObject(final Collection collection) {
		if (isEmpty(collection)) {
			return Boolean.FALSE;
		}
		boolean hasCandidate = Boolean.FALSE;
		Object candidate = null;
		for (Object elem : collection) {
			if (!hasCandidate) {
				hasCandidate = Boolean.TRUE;
				candidate = elem;
			} else if (candidate != elem) {
				return Boolean.FALSE;
			}
		}
		return Boolean.TRUE;
	}
}
    

    

    

            

    

            



    
    






    
© 2015 - 2024 Weber Informatics LLC | Privacy Policy