improved API doc for ICharArrayMap

core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/parser/util/CharArrayMap.java

@@ -18,17 +18,7 @@ import java.util.Map;
 /**
  * A facade for a Map that allows char[] slices to be used as keys.
  * 
- * Most methods are overloaded with two versions, one that uses a
+ * @see ICharArrayMap for API docs
- * section of a char[] as the key (a slice), and one that uses
- * the entire char[] as the key.
- * 
- * ex:
- * char[] key = "one two three".toCharArray();
- * map.put(key, 4, 3, new Integer(99));
- * map.get(key, 4, 3); // returns 99
- * map.get("two".toCharArray()); // returns 99
- * 
- * 
  * @author Mike Kucera
  */
 public final class CharArrayMap<V> implements ICharArrayMap<V> {
@@ -40,8 +30,6 @@ public final class CharArrayMap<V> implements ICharArrayMap<V> {
 	 * 
 	 * This class is private so it is assumed that the arguments
 	 * passed to the constructor are legal.
-	 * 
-	 * TODO: implement compareTo() so that the map may be sorted
 	 */
     private static final class Key {
         private final char[] buffer;
@@ -63,7 +51,8 @@ public final class CharArrayMap<V> implements ICharArrayMap<V> {
         	this.start = 0;
         }
         
-        @Override public boolean equals(Object x) {
+        @Override 
+        public boolean equals(Object x) {
         	if(this == x) 
         		return true;
         	if(!(x instanceof Key))  
@@ -81,7 +70,8 @@ public final class CharArrayMap<V> implements ICharArrayMap<V> {
             return true;
         }
         
-        @Override public int hashCode() {
+        @Override 
+        public int hashCode() {
             int result = 17;
             for(int i = start; i < start+length; i++) {
             	result = 37 * result + buffer[i];
@@ -89,8 +79,10 @@ public final class CharArrayMap<V> implements ICharArrayMap<V> {
             return result;
         }
         
-        @Override public String toString() {
+        @Override 
-        	return "'" + new String(buffer, start, length) + "'@(" + start + "," + length + ")"; //$NON-NLS-1$ //$NON-NLS-2$ //$NON-NLS-3$ //$NON-NLS-4$
+        public String toString() {
+        	String slice = new String(buffer, start, length);
+        	return "'" + slice + "'@(" + start + "," + length + ")"; //$NON-NLS-1$ //$NON-NLS-2$ //$NON-NLS-3$ //$NON-NLS-4$
         }
         
     }
@@ -98,7 +90,6 @@ public final class CharArrayMap<V> implements ICharArrayMap<V> {
 
     /**
      * Used to enforce preconditions. 
-     * 
      * Note that the NPE thrown by mutator methods is thrown from the Key constructor.
      * 
      * @throws IndexOutOfBoundsException if boundaries are wrong in any way
@@ -202,7 +193,8 @@ public final class CharArrayMap<V> implements ICharArrayMap<V> {
     /**
      * Returns a String representation of the map.
      */
-    @Override public String toString() {
+    @Override 
+    public String toString() {
     	return map.toString();
     }
    

core/org.eclipse.cdt.core/parser/org/eclipse/cdt/core/parser/util/ICharArrayMap.java

@@ -2,13 +2,36 @@ package org.eclipse.cdt.core.parser.util;
 
 import java.util.Collection;
 
+/**
+ * Provides an interface similar to Map, with the feature that char arrays 
+ * and sections of char arrays (known as slices) may be used as keys.
+ * 
+ * This interface is useful because small pieces of an existing large char[] buffer
+ * can be directly used as map keys. This avoids the need to create many String 
+ * objects as would normally be needed as keys in a standard java.util.Map.
+ * Thus performance is improved in the CDT core.
+ *
+ * Most methods are overloaded with two versions, one that uses a
+ * section of a char[] as the key (a slice), and one that uses
+ * the entire char[] as the key.
+ * 
+ * ex:
+ * char[] key = "one two three".toCharArray();
+ * map.put(key, 4, 3, new Integer(99));
+ * map.get(key, 4, 3); // returns 99
+ * map.get("two".toCharArray()); // returns 99
+ * 
+ * @author Mike Kucera
+ *
+ * @param <V> 
+ */
 public interface ICharArrayMap<V> {
 
 	/**
 	 * Creates a new mapping in this map, uses the given array slice as the key.
 	 * If the map previously contained a mapping for this key, the old value is replaced.
 	 * @throws NullPointerException if chars is null
-	 * @throws IllegalArgumentException if the boundaries specified by start and length are out of range
+	 * @throws IndexOutOfBoundsException if the boundaries specified by start and length are out of range
 	 */
 	void put(char[] chars, int start, int length, V value);
 
@@ -23,7 +46,7 @@ public interface ICharArrayMap<V> {
 	 * Returns the value to which the specified array slice is mapped in this map, 
 	 * or null if the map contains no mapping for this key. 
 	 * @throws NullPointerException if chars is null
-	 * @throws IllegalArgumentException if the boundaries specified by start and length are out of range
+	 * @throws IndexOutOfBoundsException if the boundaries specified by start and length are out of range
 	 */
 	V get(char[] chars, int start, int length);
 
@@ -39,7 +62,7 @@ public interface ICharArrayMap<V> {
 	 * Returns the value object that corresponded to the key
 	 * or null if the key was not in the map.
 	 * @throws NullPointerException if chars is null
-	 * @throws IllegalArgumentException if the boundaries specified by start and length are out of range
+	 * @throws IndexOutOfBoundsException if the boundaries specified by start and length are out of range
 	 */
 	V remove(char[] chars, int start, int length);
 
@@ -48,21 +71,19 @@ public interface ICharArrayMap<V> {
 	 * Returns the value object that corresponded to the key
 	 * or null if the key was not in the map.
 	 * @throws NullPointerException if chars is null
-	 * @throws IllegalArgumentException if the boundaries specified by start and length are out of range
 	 */
 	V remove(char[] chars);
 
 	/**
 	 * Returns true if the given key has a value associated with it in the map.
 	 * @throws NullPointerException if chars is null
-	 * @throws IllegalArgumentException if the boundaries specified by start and length are out of range
+	 * @throws IndexOutOfBoundsException if the boundaries specified by start and length are out of range
 	 */
 	boolean containsKey(char[] chars, int start, int length);
 
 	/**
 	 * Returns true if the given key has a value associated with it in the map.
 	 * @throws NullPointerException if chars is null
-	 * @throws IllegalArgumentException if the boundaries specified by start and length are out of range
 	 */
 	boolean containsKey(char[] chars);