http://lucene.apache.org/lucene-parent/lucene-core: Apache Lucene Java Core (The Apache Software Foundation) 
/*
 * Licensed to the Apache Software Foundation (ASF) 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.apache.lucene.analysis;


import java.util.AbstractSet;
import java.util.Collection;
import java.util.Iterator;
import java.util.Set;


A simple class that stores Strings as char[]'s in a
hash table.  Note that this is not a general purpose
class.  For example, it cannot remove items from the
set, nor does it resize its hash table to be smaller,
etc.  It is designed to be quick to test if a char[]
is in the set without the necessity of converting it
to a String first.


Please note: This class implements Set but does not behave like it should in all cases. The generic type is Set<Object>, because you can add any object to it, that has a string representation. The add methods will use Object.toString and store the result using a char[] buffer. The same behavior have the contains() methods. The iterator() returns an Iterator<char[]>. 
/**
 * A simple class that stores Strings as char[]'s in a
 * hash table.  Note that this is not a general purpose
 * class.  For example, it cannot remove items from the
 * set, nor does it resize its hash table to be smaller,
 * etc.  It is designed to be quick to test if a char[]
 * is in the set without the necessity of converting it
 * to a String first.
 *
 * <P>
 * <em>Please note:</em> This class implements {@link java.util.Set Set} but
 * does not behave like it should in all cases. The generic type is
 * {@code Set<Object>}, because you can add any object to it,
 * that has a string representation. The add methods will use
 * {@link Object#toString} and store the result using a {@code char[]}
 * buffer. The same behavior have the {@code contains()} methods.
 * The {@link #iterator()} returns an {@code Iterator<char[]>}.
 */
public class CharArraySet extends AbstractSet<Object> {

  
An empty CharArraySet. 
/** An empty {@code CharArraySet}. */
  public static final CharArraySet EMPTY_SET = new CharArraySet(CharArrayMap.<Object>emptyMap());
  
  private static final Object PLACEHOLDER = new Object();
  
  private final CharArrayMap<Object> map;
  
  
Create set with enough capacity to hold startSize terms

Params:
  • startSize – 
         the initial capacity
  • ignoreCase – 
         false if and only if the set should be case sensitive
         otherwise true.
/**
   * Create set with enough capacity to hold startSize terms
   * 
   * @param startSize
   *          the initial capacity
   * @param ignoreCase
   *          <code>false</code> if and only if the set should be case sensitive
   *          otherwise <code>true</code>.
   */
  public CharArraySet(int startSize, boolean ignoreCase) {
    this(new CharArrayMap<>(startSize, ignoreCase));
  }

  
Creates a set from a Collection of objects. 

Params:
  • c – 
         a collection whose elements to be placed into the set
  • ignoreCase – 
         false if and only if the set should be case sensitive
         otherwise true.
/**
   * Creates a set from a Collection of objects. 
   * 
   * @param c
   *          a collection whose elements to be placed into the set
   * @param ignoreCase
   *          <code>false</code> if and only if the set should be case sensitive
   *          otherwise <code>true</code>.
   */
  public CharArraySet(Collection<?> c, boolean ignoreCase) {
    this(c.size(), ignoreCase);
    addAll(c);
  }

  
Create set from the specified map (internal only), used also by CharArrayMap.keySet() 
/** Create set from the specified map (internal only), used also by {@link CharArrayMap#keySet()} */
  CharArraySet(final CharArrayMap<Object> map){
    this.map = map;
  }
  
  
Clears all entries in this set. This method is supported for reusing, but not Set.remove. 
/** Clears all entries in this set. This method is supported for reusing, but not {@link Set#remove}. */
  @Override
  public void clear() {
    map.clear();
  }

  
true if the len chars of text starting at off
are in the set 
/** true if the <code>len</code> chars of <code>text</code> starting at <code>off</code>
   * are in the set */
  public boolean contains(char[] text, int off, int len) {
    return map.containsKey(text, off, len);
  }

  
true if the CharSequence is in the set 
/** true if the <code>CharSequence</code> is in the set */
  public boolean contains(CharSequence cs) {
    return map.containsKey(cs);
  }

  @Override
  public boolean contains(Object o) {
    return map.containsKey(o);
  }

  @Override
  public boolean add(Object o) {
    return map.put(o, PLACEHOLDER) == null;
  }

  
Add this CharSequence into the set 
/** Add this CharSequence into the set */
  public boolean add(CharSequence text) {
    return map.put(text, PLACEHOLDER) == null;
  }
  
  
Add this String into the set 
/** Add this String into the set */
  public boolean add(String text) {
    return map.put(text, PLACEHOLDER) == null;
  }

  
Add this char[] directly to the set.
If ignoreCase is true for this Set, the text array will be directly modified.
The user should never modify this text array after calling this method.

/** Add this char[] directly to the set.
   * If ignoreCase is true for this Set, the text array will be directly modified.
   * The user should never modify this text array after calling this method.
   */
  public boolean add(char[] text) {
    return map.put(text, PLACEHOLDER) == null;
  }

  @Override
  public int size() {
    return map.size();
  }
  
  
Returns an unmodifiable CharArraySet. This allows to provide unmodifiable views of internal sets for "read-only" use. 
Params:
  • set – 
         a set for which the unmodifiable set is returned.
Throws:
Returns:an new unmodifiable CharArraySet.
/**
   * Returns an unmodifiable {@link CharArraySet}. This allows to provide
   * unmodifiable views of internal sets for "read-only" use.
   * 
   * @param set
   *          a set for which the unmodifiable set is returned.
   * @return an new unmodifiable {@link CharArraySet}.
   * @throws NullPointerException
   *           if the given set is <code>null</code>.
   */
  public static CharArraySet unmodifiableSet(CharArraySet set) {
    if (set == null)
      throw new NullPointerException("Given set is null");
    if (set == EMPTY_SET)
      return EMPTY_SET;
    if (set.map instanceof CharArrayMap.UnmodifiableCharArrayMap)
      return set;
    return new CharArraySet(CharArrayMap.unmodifiableMap(set.map));
  }

  
Returns a copy of the given set as a CharArraySet. If the given set is a CharArraySet the ignoreCase property will be preserved. 
Params:
  • set – 
         a set to copy
Returns:a copy of the given set as a CharArraySet. If the given set is a CharArraySet the ignoreCase property as well as the matchVersion will be of the given set will be preserved.
/**
   * Returns a copy of the given set as a {@link CharArraySet}. If the given set
   * is a {@link CharArraySet} the ignoreCase property will be preserved.
   * 
   * @param set
   *          a set to copy
   * @return a copy of the given set as a {@link CharArraySet}. If the given set
   *         is a {@link CharArraySet} the ignoreCase property as well as the
   *         matchVersion will be of the given set will be preserved.
   */
  public static CharArraySet copy(final Set<?> set) {
    if(set == EMPTY_SET)
      return EMPTY_SET;
    if(set instanceof CharArraySet) {
      final CharArraySet source = (CharArraySet) set;
      return new CharArraySet(CharArrayMap.copy(source.map));
    }
    return new CharArraySet(set, false);
  }
  
  
Returns an Iterator for char[] instances in this set. 
/**
   * Returns an {@link Iterator} for {@code char[]} instances in this set.
   */
  @Override @SuppressWarnings("unchecked")
  public Iterator<Object> iterator() {
    // use the AbstractSet#keySet()'s iterator (to not produce endless recursion)
    return map.originalKeySet().iterator();
  }
  
  @Override
  public String toString() {
    final StringBuilder sb = new StringBuilder("[");
    for (Object item : this) {
      if (sb.length()>1) sb.append(", ");
      if (item instanceof char[]) {
        sb.append((char[]) item);
      } else {
        sb.append(item);
      }
    }
    return sb.append(']').toString();
  }
}