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

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

Field Summary

static Enumeration	EMPTY_ENUMERATION Empty enumeration.
static Iterator	EMPTY_ITERATOR Empty iterator.

Constructor Summary

CollectionsX()

Method Summary

static int	addAll(Collection col, Enumeration enm) Adds all elements returned by the enumerator to a collection.
static int	addAll(Collection col, Iterator iter) Adds all elements returned by the iterator to a collection.
static int	addAll(Collection col, Object[] ary) Adds all elements of an array to a collection.
static Iterator	comodifiableIterator(Collection col) Returns an iterator that allows the caller to modify the collection directly (in addition to Iterator.remove()).
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	parse(Collection c, String src, char separator) Parses a string into a list.
static Collection	parse(Collection c, String src, char separator, boolean escBackslash) Parses a string into a list.
static Collection	parse(Collection c, String src, char separator, boolean escBackslash, boolean parenthesis) Parses a string into a list.
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

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

addAll

public static final int addAll(Collection col,
                               Iterator 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 int addAll(Collection col,
                               Enumeration 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 int addAll(Collection 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 parse(Collection 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, java.lang.String, char, char), parse(Collection, String, char, boolean, boolean)

parse

public static final Collection parse(Collection 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, java.lang.String, char, char), parse(Collection, String, char, boolean, boolean)

parse

public static final Collection parse(Collection 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, 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 Iterator comodifiableIterator(Collection 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 ingored. 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