org.zkoss.util

Class CollectionsX

java.lang.Object

org.zkoss.util.CollectionsX

public class CollectionsX
extends Object

The collection related utilities.

Author:

tomyeh

See Also:

Collections

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CollectionsX.ArrayCollection<E> An readonly collection on top of an array.
static class	CollectionsX.ArrayEnumeration<E> An enumeration on top of an array.
static class	CollectionsX.ArrayIterator<E> An iterator on top of an array.
static class	CollectionsX.ArrayList<E> An readonly list on top of an array.
static class	CollectionsX.ArrayListIterator<E>
static class	CollectionsX.CollectionEnumeration<E> An enumeration on top of a collection or iterator.
static class	CollectionsX.EnumerationIterator<E> An iterator that iterates thru an Enumeration.
static class	CollectionsX.OneCollection<E> A collection that contains only one element.
static class	CollectionsX.OneEnumeration<E> An enumeration that enumerates one element.
static class	CollectionsX.OneIterator<E> An iterator that iterates one element.

Field Summary

Fields

Modifier and Type	Field and Description
static Enumeration	EMPTY_ENUMERATION Empty enumeration.
static Iterator	EMPTY_ITERATOR Empty iterator.

Constructor Summary

Constructors

Constructor and Description
CollectionsX()

Method Summary

Methods

Modifier and Type	Method and Description
static <T> int	addAll(Collection<T> col, Enumeration<? extends T> enm) Adds all elements returned by the enumerator to a collection.
static <T> int	addAll(Collection<T> col, Iterator<? extends T> iter) Adds all elements returned by the iterator to a collection.
static <T> int	addAll(Collection<T> col, Object[] ary) Adds all elements of an array to a collection.
static <E> Iterator<E>	comodifiableIterator(Collection<E> col) Returns an iterator that allows the caller to modify the collection directly (in addition to Iterator.remove()).
static <F,T> Iterator<T>	comodifiableIterator(Collection<F> col, Converter<F,T> converter) Returns an iterator that allows the caller to modify the collection directly (in addition to Iterator.remove()).
static <T> Enumeration<T>	emptyEnumeration() Returns a generic empty enumeration.
static <T> Iterable<T>	emptyIterable() Returns an empty iterable object.
static <T> Iterator<T>	emptyIterator() Returns a generic empty iterator.
static boolean	isIntersected(Set<?> a, Set<?> b) Tests whether two sets has any intersection.
static Iterator	iterator(Object obj) Based on the given collection type of Object, return an iterator.
static Collection<String>	parse(Collection<String> c, String src, char separator) Parses a string into a list.
static Collection<String>	parse(Collection<String> c, String src, char separator, boolean escBackslash) Parses a string into a list.
static Collection<String>	parse(Collection<String> c, String src, char separator, boolean escBackslash, boolean parenthesis) Parses a string into a list.
static <T> T[]	toArray(Collection<? extends T> col, T[] dst, int from, int to) Returns the specified range of the given collection; the runtime type of the returned array is that of the specified array.
static Object[]	toArray(Collection col, int from, int to) Returns the specified range of the specified collection into a new array.

Methods inherited from class java.lang.Object

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

Field Detail

EMPTY_ITERATOR

public static final Iterator EMPTY_ITERATOR

Empty iterator.

EMPTY_ENUMERATION

public static final Enumeration EMPTY_ENUMERATION

Empty enumeration.

Constructor Detail

CollectionsX

public CollectionsX()

Method Detail

emptyIterator

public static final <T> Iterator<T> emptyIterator()

Returns a generic empty iterator.

Since:

6.0.0

emptyEnumeration

public static final <T> Enumeration<T> emptyEnumeration()

Returns a generic empty enumeration.

Since:

6.0.0

emptyIterable

public static final <T> Iterable<T> emptyIterable()

Returns an empty iterable object.

Since:

6.0.0

toArray

public static final Object[] toArray(Collection col,
               int from,
               int to)

Returns the specified range of the specified collection into a new array. The initial index of the range (from) must lie between zero and col.size, inclusive. The final index of the range (to), which must be greater than or equal to from.

The returned array will be "safe" in that no references to it are maintained by this list. (In other words, this method must allocate a new array). The caller is thus free to modify the returned array.

This method acts as bridge between array-based and collection-based APIs.

Parameters:

col - the collection to be copied.

from - the initial index of the range to be copied, inclusive.

to - the final index of the range to be copied, exclusive.

Since:

3.0.6

toArray

public static final <T> T[] toArray(Collection<? extends T> col,
              T[] dst,
              int from,
              int to)

Returns the specified range of the given collection; the runtime type of the returned array is that of the specified array.

Parameters:

col - the collection to be copied.

dst - the array into which the elements of this list are to be stored, if it is big enough (less than to - from; otherwise, a new array of the same runtime type is allocated for this purpose. Note: dst[0] will be col[from].

from - the initial index of the range to be copied, inclusive.

to - the final index of the range to be copied, exclusive.

Since:

6.0.0

addAll

public static final <T> int addAll(Collection<T> col,
             Iterator<? extends T> iter)

Adds all elements returned by the iterator to a collection.

Parameters:

iter - the iterator; null is OK

Returns:

the number element being added

addAll

public static final <T> int addAll(Collection<T> col,
             Enumeration<? extends T> enm)

Adds all elements returned by the enumerator to a collection.

Parameters:

enm - the enumeration; null is OK

Returns:

the number element being added

addAll

public static final <T> int addAll(Collection<T> col,
             Object[] ary)

Adds all elements of an array to a collection.

Parameters:

ary - the array; null is OK

Returns:

the number element being added

isIntersected

public static final boolean isIntersected(Set<?> a,
                    Set<?> b)

Tests whether two sets has any intersection.

parse

public static final Collection<String> parse(Collection<String> c,
                       String src,
                       char separator)

Parses a string into a list. It is the same as parse(c, src, separator, true, false). Refer to parse(Collection, String, char, boolean, boolean) for details.

Throws:

IllegalSyntaxException - if syntax errors

See Also:

Maps.parse(java.util.Map<? super java.lang.String, ? super java.lang.String>, java.lang.String, char, char), parse(Collection, String, char, boolean, boolean)

parse

public static final Collection<String> parse(Collection<String> c,
                       String src,
                       char separator,
                       boolean escBackslash)

Parses a string into a list. It is the same as parse(c, src, separator, escBackslash, false). Refer to parse(Collection, String, char, boolean, boolean) for details.

Throws:

IllegalSyntaxException - if syntax errors

See Also:

Maps.parse(java.util.Map<? super java.lang.String, ? super java.lang.String>, java.lang.String, char, char), parse(Collection, String, char, boolean, boolean)

parse

public static final Collection<String> parse(Collection<String> c,
                       String src,
                       char separator,
                       boolean escBackslash,
                       boolean parenthesis)

Parses a string into a list. To quote a string, both '\'' and '"' are OK. Whitespaces are trimmed between quotation and separators.

Unlike Java, quotation could spread over multiple lines.

Example,
a b , ' c d',"'f'", '1' "2", 3
generate a list of "a b", "c d", "'f'", "1", "2" and "3". Note: the separator between "1" and "2" is optional.

Note: Like Java, if the string is ending with a separator, it will be ignored.

Example,
a, , b,
generate a list of "a", "", "b".

Parameters:

c - the collection to hold the parsed results; a linked list is created if c is null.

src - the string to parse

separator - the separator, e.g., ',', '\n' or ' '. Note: if separator is ' ', it denotes any white space.

escBackslash - whether to treat '\\' specially (as escape char)

parenthesis - whether to parse parenthesis in the value, {}, () and []. If true, the separator is ignored inside the parenthesis. Specify true if the value might contain EL expressions.

Returns:

the c collection if not null; or a linked list if c is null (so you can cast it to List)

Throws:

IllegalSyntaxException - if syntax errors

Since:

3.0.6

See Also:

Maps.parse(java.util.Map<? super java.lang.String, ? super java.lang.String>, java.lang.String, char, char)

iterator

public static final Iterator iterator(Object obj)

Based on the given collection type of Object, return an iterator. The Collection type of object can be Collection, Map (return the entry), or Array.

comodifiableIterator

public static <E> Iterator<E> comodifiableIterator(Collection<E> col)

Returns an iterator that allows the caller to modify the collection directly (in addition to Iterator.remove()). In other words, the iterator will handle java.util.ConcurrentModificationException and return the items one-by-one even if collection's add, remove or other method was called (which is not allowed by a regular iterator).

Limitation:

• It is still not safe to modify the collection between hasNext() and next().Modify it after next(), if necessary.
• If the collection have multiple items referencing to the same object, and if we remove the item that has been iterated, the other item might be ignored. For example, if a collection has A, B, C, B, then the following code only iterates A, B, C

        for (Iterator it = org.zkoss.util.CollectionsX.comodifiableIterator(list); it.hasNext();) {
                it.next();
                l.remove(0);
        }

Since:

5.0.6

comodifiableIterator

public static <F,T> Iterator<T> comodifiableIterator(Collection<F> col,
                                     Converter<F,T> converter)

Returns an iterator that allows the caller to modify the collection directly (in addition to Iterator.remove()).

Parameters:

converter - the filter used to convert the value of each element found in the given collection to the return iterator. Ignored if null (and then F must be the same as T or extends from T).

Since:

6.0.0