de.schlichtherle.util
Class CanonicalStringSet

java.lang.Object
  java.util.AbstractCollection
      java.util.AbstractSet
          de.schlichtherle.util.CanonicalStringSet

All Implemented Interfaces:

Iterable, Collection, Set

Direct Known Subclasses:

SuffixSet

public class CanonicalStringSet
extends AbstractSet

A set of canonicalized strings in natural order. A string is canonicalized by the template method canonicalize(java.lang.String), which should get overridden by subclasses.

String sets can be converted from and to string lists by using addAll(String) and toString(). A string list is a string which consists of zero or more elements which are separated by the separator character provided to the constructor. Note that in general, a string list is just a sequence of strings elements. In particular, a string list may be empty (but not null) and its elements don't have to be in canonical form, may be duplicated in the list and may be listed in arbitrary order. However, string lists have a canonical form, too: A string list in canonical form (or canonical string list for short) is a string list which contains only canonical strings in natural order and does not contain any duplicates (so it's actually a set).

Unless otherwise documented, all Set methods work on the canonical form of the string elements in this set.

Null elements are not permitted in this set.

Since:

TrueZIP 6.5

Version:

TrueZIP 6.7

Author:

Christian Schlichtherle

Constructor Summary

CanonicalStringSet(char separator)
Constructs a new, empty set of canonical strings.

CanonicalStringSet(char separator, CanonicalStringSet set)
Constructs a new set of canonical strings from the given set of canonical strings.

CanonicalStringSet(char separator, String list)
Deprecated. This constructor is dangerous: It may call canonicalize(java.lang.String), which may result in a call from a superclass if this constructor is called from a subclass.

Method Summary

boolean	add(Object list) Adds the canonical form of all strings in the given list to this set.
boolean	addAll(CanonicalStringSet set) Adds all canonical strings in the given set to this set after they have been canonicalized by this set again.
boolean	addAll(String list) Adds the canonical form of all strings in the given list to this set.
protected String	canonical(String s) Deprecated. Override and use canonicalize(java.lang.String) instead.
protected String	canonicalize(String s) A template method which returns the canonical form of s or null if the given string does not have a canonical form.
void	clear()
boolean	contains(Object list) Tests if the canonical form of all strings in the given string list is contained in this set.
boolean	containsAll(CanonicalStringSet set) Tests if all canonical strings in the given set are contained in this set.
boolean	containsAll(String list) Tests if the canonical form of all strings in the given string list is contained in this set.
boolean	isEmpty()
Iterator	iterator() Returns a new iterator for all canonical string elements in this set.
Iterator	originalIterator() Returns a new iterator for all original string elements in this set.
boolean	remove(Object list) Removes the canonical form of all strings in the given list from this set.
boolean	removeAll(CanonicalStringSet set) Removes all canonical strings in the given set from this set.
boolean	removeAll(String list) Removes the canonical form of all strings in the given list from this set.
boolean	retainAll(CanonicalStringSet set) Retains all canonical strings in the given set in this set.
boolean	retainAll(String list) Retains the canonical form of all strings in the given list in this set.
int	size()
Object[]	toArray()
Object[]	toArray(Object[] array)
String	toString() Returns the canonical string list representation of this set.

Methods inherited from class java.util.AbstractSet

equals, hashCode, removeAll

Methods inherited from class java.util.AbstractCollection

addAll, containsAll, retainAll

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Set

addAll, containsAll, retainAll

Constructor Detail

CanonicalStringSet

public CanonicalStringSet(char separator)

Constructs a new, empty set of canonical strings.

Parameters:

separator - The separator character to use in string lists.

CanonicalStringSet

public CanonicalStringSet(char separator,
                          CanonicalStringSet set)

Constructs a new set of canonical strings from the given set of canonical strings.

Parameters:

separator - The separator character to use in string lists.

set - A set of canonical strings - may be null to construct an empty set.

CanonicalStringSet

public CanonicalStringSet(char separator,
                          String list)

Deprecated. This constructor is dangerous: It may call canonicalize(java.lang.String), which may result in a call from a superclass if this constructor is called from a subclass.

Constructs a new set of canonical strings from the given string list.

Parameters:

separator - The separator character to use in string lists.

list - A string list - may be null to construct an empty set.

Method Detail

canonical

protected String canonical(String s)

Deprecated. Override and use canonicalize(java.lang.String) instead.

canonicalize

protected String canonicalize(String s)

A template method which returns the canonical form of s or null if the given string does not have a canonical form.

The implementation in CanonicalStringSet simply returns the parameter.

Parameters:

s - The string to get canonicalized. Never null and never contains the separator.

Returns:

The canonical form of s or null if s does not have a canonical form.

isEmpty

public final boolean isEmpty()

Specified by:

isEmpty in interface Collection

Specified by:

isEmpty in interface Set

Overrides:

isEmpty in class AbstractCollection

size

public final int size()

Specified by:

size in interface Collection

Specified by:

size in interface Set

Specified by:

size in class AbstractCollection

contains

public final boolean contains(Object list)

Tests if the canonical form of all strings in the given string list is contained in this set. If a string in the list does not have a canonical form, it's skipped. This implies that if the list is empty or entirely consists of strings which do not have a canonical form, true is returned. In other words, an empty set is considered to be a true subset of this set.

Specified by:

contains in interface Collection

Specified by:

contains in interface Set

Overrides:

contains in class AbstractCollection

Parameters:

list - A non-null string list.

Returns:

true Iff the canonical form of all strings in the given string list is contained in this set.

Throws:

NullPointerException - If list is null.

ClassCastException - If list is not a String.

iterator

public final Iterator iterator()

Returns a new iterator for all canonical string elements in this set.

Specified by:

iterator in interface Iterable

Specified by:

iterator in interface Collection

Specified by:

iterator in interface Set

Specified by:

iterator in class AbstractCollection

Returns:

A new iterator for all canonical string elements.

originalIterator

public final Iterator originalIterator()

Returns a new iterator for all original string elements in this set. Note that strings which don't have a canonical form cannot get added to this class and hence cannot get returned by the iterator.

Returns:

A new iterator for all original string elements.

toArray

public final Object[] toArray()

Specified by:

toArray in interface Collection

Specified by:

toArray in interface Set

Overrides:

toArray in class AbstractCollection

toArray

public final Object[] toArray(Object[] array)

Specified by:

toArray in interface Collection

Specified by:

toArray in interface Set

Overrides:

toArray in class AbstractCollection

add

public final boolean add(Object list)

Adds the canonical form of all strings in the given list to this set. If a string in the list does not have a canonical form or its canonical form is already contained in this set, it's ignored.

Specified by:

add in interface Collection

Specified by:

add in interface Set

Overrides:

add in class AbstractCollection

Parameters:

list - A non-null string list.

Returns:

true Iff this set changed as a result of the call.

Throws:

NullPointerException - If list is null.

ClassCastException - If list is not a String.

remove

public final boolean remove(Object list)

Removes the canonical form of all strings in the given list from this set. If a string in the list does not have a canonical form, it's ignored.

Specified by:

remove in interface Collection

Specified by:

remove in interface Set

Overrides:

remove in class AbstractCollection

Parameters:

list - A non-null string list.

Returns:

true Iff this set changed as a result of the call.

Throws:

NullPointerException - If list is null.

ClassCastException - If list is not a String.

containsAll

public final boolean containsAll(CanonicalStringSet set)

Tests if all canonical strings in the given set are contained in this set. An empty set is considered to be a true subset of this set.

Parameters:

set - A non-null set of canonical strings.

Returns:

true Iff all strings in the given set are contained in this set.

Throws:

NullPointerException - If set is null.

containsAll

public final boolean containsAll(String list)

Tests if the canonical form of all strings in the given string list is contained in this set. If a string in the list does not have a canonical form, it's skipped. This implies that if the list is empty or entirely consists of strings which do not have a canonical form, true is returned. In other words, an empty set is considered to be a true subset of this set.

Parameters:

list - A non-null string list.

Returns:

true Iff the canonical form of all strings in the given string list is contained in this set.

Throws:

NullPointerException - If list is null.

addAll

public final boolean addAll(CanonicalStringSet set)

Adds all canonical strings in the given set to this set after they have been canonicalized by this set again.

Parameters:

set - A non-null set of canonical strings.

Returns:

true Iff this set of canonicalized strings has changed as a result of the call.

Throws:

NullPointerException - If set is null.

addAll

public final boolean addAll(String list)

Adds the canonical form of all strings in the given list to this set. If a string in the list does not have a canonical form, it's skipped.

Parameters:

list - A non-null string list.

Returns:

true Iff this set of canonicalized strings has changed as a result of the call.

Throws:

NullPointerException - If list is null.

retainAll

public final boolean retainAll(CanonicalStringSet set)

Retains all canonical strings in the given set in this set.

Parameters:

set - A non-null set of canonical strings.

Returns:

true Iff this set of canonicalized strings has changed as a result of the call.

Throws:

NullPointerException - If set is null.

retainAll

public final boolean retainAll(String list)

Retains the canonical form of all strings in the given list in this set. If a string in the list does not have a canonical form, it's skipped.

Parameters:

list - A non-null string list.

Returns:

true Iff this set of canonicalized strings has changed as a result of the call.

Throws:

NullPointerException - If list is null.

removeAll

public final boolean removeAll(CanonicalStringSet set)

Removes all canonical strings in the given set from this set.

Parameters:

set - A non-null set of strings.

Returns:

true Iff this set of canonicalized strings has changed as a result of the call.

Throws:

NullPointerException - If set is null.

removeAll

public final boolean removeAll(String list)

Removes the canonical form of all strings in the given list from this set. If a string in the list does not have a canonical form, it's skipped.

Parameters:

list - A non-null string list.

Returns:

true Iff this set of canonicalized strings has changed as a result of the call.

Throws:

NullPointerException - If list is null.

clear

public final void clear()

Specified by:

clear in interface Collection

Specified by:

clear in interface Set

Overrides:

clear in class AbstractCollection

toString

public final String toString()

Returns the canonical string list representation of this set. If this string set is empty, an empty string is returned.

Overrides:

toString in class AbstractCollection