de.schlichtherle.truezip.util.CanonicalStringSet Maven / Gradle / Ivy

Go to download
/*
 * Copyright (C) 2005-2015 Schlichtherle IT Services.
 * All rights reserved. Use is subject to license terms.
 */
package de.schlichtherle.truezip.util;

import java.util.AbstractSet;
import java.util.Iterator;
import java.util.NoSuchElementException;
import java.util.Set;
import java.util.StringTokenizer;
import java.util.TreeSet;
import javax.annotation.CheckForNull;

/**
 * An abstract set of the canonical string representation of objects in
 * natural sort order.
 * An object is canonicalized by the idempotent function
 * {@link Canonicalizer#map}.
 * 
 * Canonical string sets can be converted from and to string lists by using
 * {@link #addAll(String)} and {@link #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 {@code 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 sort order
 * and does not contain any duplicates (so it's actually a set).
 * 

 * Unless otherwise documented, all {@link java.util.Set} methods work on the
 * canonical form of the string elements in this set.
 * 

 * Null elements are not permitted in this set.
 *
 * @author Christian Schlichtherle
 */
public class CanonicalStringSet extends AbstractSet {

    /**
     * An idempotent function which maps an arbitrary object to its canonical
     * string representation.
     *
     * @see  0)
                s.append(separator);
            s.append(string);
        }
        return s.toString();
    }

    /**
     * {@inheritDoc}
     * 

     * The implementation in the class {@link CanonicalStringSet} first
     * canonicalizes the given parameter before the operation is continued.
     */
    @Override public boolean contains(Object o) {
        return set.contains(canonicalizer.map(o));
    }

    /**
     * {@inheritDoc}
     * 

     * The implementation in the class {@link CanonicalStringSet} first
     * canonicalizes the given parameter before the operation is continued.
     */
    @Override
    public boolean add(String s) { return set.add(canonicalizer.map(s)); }

    /**
     * {@inheritDoc}
     * 
     * The implementation in the class {@link CanonicalStringSet} first
     * canonicalizes the given parameter before the operation is continued.
     */
    @Override
    public boolean remove(Object o) { return set.remove(canonicalizer.map(o)); }

    @Override public void clear() { set.clear(); }

    /**
     * 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.
     *
     * @param set A set of canonical strings.
     * @return {@code true} Iff all strings in the given set are contained
     *         in this set.
     */
    public boolean containsAll(final CanonicalStringSet set) {
        return this.set.containsAll(set.set);
    }

    /**
     * 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, {@code true} is returned.
     * In other words, an empty set is considered to be a true subset of this
     * set.
     *
     * @param  list a string list.
     * @return {@code true} Iff the canonical form of all strings in the
     *         given string list is contained in this set.
     */
    public boolean containsAll(final String list) {
        Iterator i = new CanonicalStringIterator(list);
        while (i.hasNext())
            if (!set.contains(i.next()))
                return false;
        return true;
    }

    /**
     * Adds all canonical strings in the given set to this set after they have
     * been canonicalized by this set again.
     *
     * @param  set a set of canonical strings.
     * @return {@code true} Iff this set of canonicalized strings has
     *         changed as a result of the call.
     */
    public boolean addAll(final CanonicalStringSet set) {
        boolean changed = false;
        for (String s : set.set)
            changed |= add(s);
        return changed;
    }

    /**
     * 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.
     *
     * @param  list a string list.
     * @return {@code true} Iff this set of canonicalized strings has
     *         changed as a result of the call.
     */
    public boolean addAll(final String list) {
        boolean changed = false;
        Iterator i = new CanonicalStringIterator(list);
        while (i.hasNext())
            changed |= set.add(i.next());
        return changed;
    }

    /**
     * Retains all canonical strings in the given set in this set.
     *
     * @param  set a set of canonical strings.
     * @return {@code true} Iff this set changed as a result of the call.
     */
    public boolean retainAll(CanonicalStringSet set) {
        return this.set.retainAll(set.set);
    }

    /**
     * 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.
     *
     * @param  list a string list.
     * @return {@code true} Iff this set changed as a result of the call.
     */
    public boolean retainAll(final String list) {
        final CanonicalStringSet
                set = new CanonicalStringSet(canonicalizer, separator);
        set.addAll(list);
        return this.set.retainAll(set);
    }

    /**
     * Removes all canonical strings in the given set from this set.
     *
     * @param  set a set of strings.
     * @return {@code true} Iff this set changed as a result of the call.
     */
    public boolean removeAll(CanonicalStringSet set) {
        return this.set.removeAll(set.set);
    }

    /**
     * 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.
     *
     * @param  list a string list.
     * @return {@code true} Iff this set changed as a result of the call.
     */
    public boolean removeAll(final String list) {
        boolean changed = false;
        Iterator i = new CanonicalStringIterator(list);
        while (i.hasNext())
            changed |= set.remove(i.next());
        return changed;
    }

    private class CanonicalStringIterator implements Iterator {
        private final StringTokenizer tokenizer;
        private @CheckForNull String canonical;

        private CanonicalStringIterator(final String list) {
            tokenizer = new StringTokenizer(list, "" + separator); // NOI18N
            advance();
        }

        private void advance() {
            while (tokenizer.hasMoreTokens())
                if (null != (canonical = canonicalizer.map(tokenizer.nextToken())))
                    return;
            canonical = null; // no such element
        }

        @Override
        public boolean hasNext() { return null != canonical; }

        @Override
        public String next() {
            final String canonical = this.canonical;
            if (null == canonical) throw new NoSuchElementException();
            advance();
            return canonical;
        }

        @Override
        public void remove() { throw new UnsupportedOperationException(); }
    } // CanonicalStringIterator
}
Related Artifacts