FormatCharacterIterator.java: Documented the class and

2003-11-27  Guilhem Lavaux <guilhem@kaffe.org>

	* java/text/FormatCharacterIterator.java: Documented the class and

2003-11-27  Guilhem Lavaux <guilhem@kaffe.org>

	* java/text/FormatCharacterIterator.java: Fixed some typos.

From-SVN: r73986

2 files changed, 126 insertions, 54 deletions

diff --git a/libjava/ChangeLog b/libjava/ChangeLog
index c3a798b..544f2c4 100644
--- a/libjava/ChangeLog
+++ b/libjava/ChangeLog
@@ -1,5 +1,13 @@
 2003-11-27  Guilhem Lavaux <guilhem@kaffe.org>
 
+	* java/text/FormatCharacterIterator.java: Documented the class and
+
+2003-11-27  Guilhem Lavaux <guilhem@kaffe.org>
+
+	* java/text/FormatCharacterIterator.java: Fixed some typos.
+
+2003-11-27  Guilhem Lavaux <guilhem@kaffe.org>
+
 	* java/text/NumberFormat.java:
 	(getIntegerInstance) Added the java version in the comments.
 
diff --git a/libjava/java/text/FormatCharacterIterator.java b/libjava/java/text/FormatCharacterIterator.java
index 8693707..a31154c 100644
--- a/libjava/java/text/FormatCharacterIterator.java
+++ b/libjava/java/text/FormatCharacterIterator.java
@@ -43,6 +43,18 @@ import java.util.Map;
 import java.util.HashMap;
 import java.util.Vector;
 
+
+/**
+ * This class should not be put public and it is only intended to the
+ * classes of the java.text package. Its aim is to build a segmented
+ * character iterator by appending strings and adding attributes to
+ * portions of strings. The code intends to do some optimization
+ * concerning memory consumption and attribute access but at the
+ * end it is only an AttributedCharacterIterator.
+ *
+ * @author Guilhem Lavaux <guilhem@kaffe.org>
+ * @date November 22, 2003
+ */
 class FormatCharacterIterator implements AttributedCharacterIterator
 {
   private String formattedString;
@@ -51,6 +63,11 @@ class FormatCharacterIterator implements AttributedCharacterIterator
   private int[] ranges;
   private HashMap[] attributes;
   
+  /**
+   * This constructor builds an empty iterated strings. The attributes
+   * are empty and so is the string. However you may append strings
+   * and attributes to this iterator.
+   */
   FormatCharacterIterator()
   {
     formattedString = "";
@@ -58,18 +75,33 @@ class FormatCharacterIterator implements AttributedCharacterIterator
     attributes = new HashMap[0];
   }
 
-  FormatCharacterIterator(String s, int[] ranges, HashMap[] attributes)
+  /**
+   * This constructor take a string <code>s</code>, a set of ranges 
+   * and the corresponding attributes. This is used to build an iterator.
+   * The array <code>ranges</code> should be formatted as follow:
+   * each element of <code>ranges</code> specifies the index in the string
+   * until which the corresponding map of attributes at the same position
+   * is applied. For example, if you have:
+   * <pre>
+   *   s = "hello";
+   *   ranges = new int[] { 2, 6 };
+   *   attributes = new HashMap[2];
+   * </pre>
+   * <code>"he"</code> will have the attributes <code>attributes[0]</code>,
+   * <code>"llo"</code> the <code>attributes[1]</code>.
+   */
+  FormatCharacterIterator (String s, int[] ranges, HashMap[] attributes)
   {
     formattedString = s;
     this.ranges = ranges;
     this.attributes = attributes;
   }
   
-  /*
-   * -----------------------------------
-   * AttributedCharacterIterator methods
-   * -----------------------------------
+  /* 
+   * The following methods are inherited from AttributedCharacterIterator,
+   * and thus are already documented. 
    */
+
   public Set getAllAttributeKeys()
   {
     if (attributes != null && attributes[attributeIndex] != null)
@@ -86,10 +118,10 @@ class FormatCharacterIterator implements AttributedCharacterIterator
       return new HashMap();
   }
   
-  public Object getAttribute(AttributedCharacterIterator.Attribute attrib)
+  public Object getAttribute (AttributedCharacterIterator.Attribute attrib)
   {
     if (attributes != null && attributes[attributeIndex] != null)
-      return attributes[attributeIndex].get(attrib);
+      return attributes[attributeIndex].get (attrib);
     else
       return null;
   }
@@ -111,17 +143,17 @@ class FormatCharacterIterator implements AttributedCharacterIterator
 	  break;
 	newKeys = attributes[currentAttrIndex].keySet();
       }
-    while (newKeys.containsAll(reqAttrs));
+    while (newKeys.containsAll (reqAttrs));
 
     return ranges[currentAttrIndex-1];
   }
   
-  public int getRunLimit(AttributedCharacterIterator.Attribute attribute) 
+  public int getRunLimit (AttributedCharacterIterator.Attribute attribute) 
   {
     Set s = new HashSet();
 
-    s.add(attribute);
-    return getRunLimit(s);
+    s.add (attribute);
+    return getRunLimit (s);
   }
 
   public int getRunLimit()
@@ -139,7 +171,7 @@ class FormatCharacterIterator implements AttributedCharacterIterator
     return getRunLimit (attributes[attributeIndex].keySet());
   }
   
-  public int getRunStart(Set reqAttrs)
+  public int getRunStart (Set reqAttrs)
   {
     if (attributes == null)
       return formattedString.length();
@@ -157,7 +189,7 @@ class FormatCharacterIterator implements AttributedCharacterIterator
 	  break;
 	newKeys = attributes[currentAttrIndex].keySet();
       }
-    while (newKeys.containsAll(reqAttrs));
+    while (newKeys.containsAll (reqAttrs));
    
     return (currentAttrIndex > 0) ? ranges[currentAttrIndex-1] : 0;
   } 
@@ -175,37 +207,37 @@ class FormatCharacterIterator implements AttributedCharacterIterator
 	return 0;
       }
 
-    return getRunStart(attributes[attributeIndex].keySet());
+    return getRunStart (attributes[attributeIndex].keySet());
   }
   
-  public int getRunStart(AttributedCharacterIterator.Attribute attribute) 
+  public int getRunStart (AttributedCharacterIterator.Attribute attribute) 
   {
     Set s = new HashSet();
     
-    s.add(attribute);
-    return getRunStart(s);
+    s.add (attribute);
+    return getRunStart (s);
   }
 
   public Object clone()
   {
-    return new FormatCharacterIterator(formattedString, ranges, attributes);
+    return new FormatCharacterIterator (formattedString, ranges, attributes);
   }
   
   /*
-   * ---------------------------------
-   * CharacterIterator methods
-   * ---------------------------------
+   * The following methods are inherited from CharacterIterator and thus
+   * are already documented.
    */
+
   public char current()
   {
-    return formattedString.charAt(charIndex);
+    return formattedString.charAt (charIndex);
   }
   
   public char first()
   {
     charIndex = 0;
     attributeIndex = 0;
-    return formattedString.charAt(0);
+    return formattedString.charAt (0);
   }
   
   public int getBeginIndex()
@@ -228,7 +260,7 @@ class FormatCharacterIterator implements AttributedCharacterIterator
     charIndex = formattedString.length()-1;
     if (attributes != null)
       attributeIndex = attributes.length-1;
-    return formattedString.charAt(charIndex);
+    return formattedString.charAt (charIndex);
   }
   
   public char next()
@@ -244,7 +276,7 @@ class FormatCharacterIterator implements AttributedCharacterIterator
 	if (charIndex >= ranges[attributeIndex])
 	  attributeIndex++;
       }
-    return formattedString.charAt(charIndex);
+    return formattedString.charAt (charIndex);
   }
   
   public char previous()
@@ -261,13 +293,13 @@ class FormatCharacterIterator implements AttributedCharacterIterator
 	if (charIndex < ranges[attributeIndex])
 	  attributeIndex--;
       }
-    return formattedString.charAt(charIndex);
+    return formattedString.charAt (charIndex);
   }
   
-  public char setIndex(int position)
+  public char setIndex (int position)
   {
     if (position < 0 || position > formattedString.length())
-      throw new IllegalArgumentException("position is out of range");
+      throw new IllegalArgumentException ("position is out of range");
     
     charIndex = position;
     if (attributes != null)
@@ -281,10 +313,19 @@ class FormatCharacterIterator implements AttributedCharacterIterator
     if (charIndex == formattedString.length())
       return DONE;
     else
-      return formattedString.charAt(charIndex);
+      return formattedString.charAt (charIndex);
   }
 
-  protected void mergeAttributes(HashMap[] attributes, int[] ranges)
+  /**
+   * This method merge the specified attributes and ranges with the
+   * internal tables. This method is in charge of the optimization
+   * of tables. Two following sets of attributes are never the same.
+   *
+   * @see #FormatCharacterIterator()
+   *
+   * @param attributes the new array attributes to apply to the string.
+   */
+  protected void mergeAttributes (HashMap[] attributes, int[] ranges)
   {
     Vector new_ranges = new Vector();
     Vector new_attributes = new Vector();
@@ -294,28 +335,28 @@ class FormatCharacterIterator implements AttributedCharacterIterator
       {
 	if (this.attributes[i] != null)
 	  {
-	    new_attributes.add(this.attributes[i]);
+	    new_attributes.add (this.attributes[i]);
 	    if (attributes[j] != null)
-	      this.attributes[i].putAll(attributes[j]);
+	      this.attributes[i].putAll (attributes[j]);
 	  }
 	else
 	  {
-	    new_attributes.add(attributes[j]);
+	    new_attributes.add (attributes[j]);
 	  }
 	if (this.ranges[i] == ranges[j])
 	  {
-	    new_ranges.add(new Integer(ranges[j]));
+	    new_ranges.add (new Integer (ranges[j]));
 	    i++;
 	    j++;
 	  }
 	else if (this.ranges[i] < ranges[j])
 	  {
-	    new_ranges.add(new Integer(this.ranges[i]));
+	    new_ranges.add (new Integer (this.ranges[i]));
 	    i++;
 	  }
 	else
 	  {
-	    new_ranges.add(new Integer(ranges[j]));
+	    new_ranges.add (new Integer (ranges[j]));
 	    j++;
 	  }
      }
@@ -324,32 +365,39 @@ class FormatCharacterIterator implements AttributedCharacterIterator
       {
 	for (;i<this.ranges.length;i++)
 	  {
-	    new_attributes.add(this.attributes[i]);
-	    new_ranges.add(new Integer(this.ranges[i]));
+	    new_attributes.add (this.attributes[i]);
+	    new_ranges.add (new Integer (this.ranges[i]));
 	  }
       }
     if (j != ranges.length)
       {
 	for (;j<ranges.length;j++)
 	  {
-	    new_attributes.add(attributes[j]);
-	    new_ranges.add(new Integer(ranges[j]));
+	    new_attributes.add (attributes[j]);
+	    new_ranges.add (new Integer (ranges[j]));
 	  }
       }
 
     this.attributes = new HashMap[new_attributes.size()];
     this.ranges = new int[new_ranges.size()];
-    System.arraycopy(new_attributes.toArray(), 0, this.attributes,
-		     0, this.attributes.length);
+    System.arraycopy (new_attributes.toArray(), 0, this.attributes,
+		      0, this.attributes.length);
 
     for (i=0;i<new_ranges.size();i++)
       {
-	this.ranges[i] = ((Integer)new_ranges.elementAt(i)).intValue();
+	this.ranges[i] = ((Integer)new_ranges.elementAt (i)).intValue();
       }
     
   }
 
-  protected void append(AttributedCharacterIterator iterator)
+  /**
+   * This method appends to the internal attributed string the attributed
+   * string contained in the specified iterator.
+   *
+   * @param iterator the iterator which contains the attributed string to
+   * append to this iterator.
+   */
+  protected void append (AttributedCharacterIterator iterator)
   {
     char c = iterator.first();
     Vector more_ranges = new Vector();
@@ -360,7 +408,7 @@ class FormatCharacterIterator implements AttributedCharacterIterator
 	formattedString = formattedString + String.valueOf(c);
 	// TODO: Reduce the size of the output array.
 	more_attributes.add (iterator.getAttributes());
-	more_ranges.add(new Integer(formattedString.length()));
+	more_ranges.add (new Integer (formattedString.length()));
 	// END TOOD
 	c = iterator.next();
       } 
@@ -370,11 +418,11 @@ class FormatCharacterIterator implements AttributedCharacterIterator
 					   + more_attributes.size()];
     int[] new_ranges = new int[ranges.length + more_ranges.size()];
     
-    System.arraycopy(attributes, 0, new_attributes, 0, attributes.length);
-    System.arraycopy(more_attributes.toArray(), 0, new_attributes,
-		     attributes.length, more_attributes.size());
+    System.arraycopy (attributes, 0, new_attributes, 0, attributes.length);
+    System.arraycopy (more_attributes.toArray(), 0, new_attributes,
+		      attributes.length, more_attributes.size());
 
-    System.arraycopy(ranges, 0, new_ranges, 0, ranges.length);
+    System.arraycopy (ranges, 0, new_ranges, 0, ranges.length);
     Object[] new_ranges_array = more_ranges.toArray();
     for (int i=0;i<more_ranges.size();i++)
       new_ranges[i+ranges.length] = ((Integer)new_ranges_array[i]).intValue();
@@ -383,14 +431,23 @@ class FormatCharacterIterator implements AttributedCharacterIterator
     ranges = new_ranges;
   }
 
-  protected void append(String text, HashMap local_attributes)
+  /**
+   * This method appends an attributed string which attributes are specified
+   * directly in the calling parameters.
+   *
+   * @param text The string to append.
+   * @param local_attributes The attributes to put on this string in the
+   * iterator. If it is <code>null</code> the string will simply have no
+   * attributes.
+   */
+  protected void append (String text, HashMap local_attributes)
   {
     int[] new_ranges = new int[ranges.length+1];
     HashMap[] new_attributes = new HashMap[attributes.length+1];
 
     formattedString += text;
-    System.arraycopy(attributes, 0, new_attributes, 0, attributes.length);
-    System.arraycopy(ranges, 0, new_ranges, 0, ranges.length);
+    System.arraycopy (attributes, 0, new_attributes, 0, attributes.length);
+    System.arraycopy (ranges, 0, new_ranges, 0, ranges.length);
     new_ranges[ranges.length] = formattedString.length();
     new_attributes[attributes.length] = local_attributes;
 
@@ -398,8 +455,15 @@ class FormatCharacterIterator implements AttributedCharacterIterator
     attributes = new_attributes;
   }  
 
-  protected void append(String text)
+  /**
+   * This method appends a string without attributes. It is completely
+   * equivalent to call {@link #append(String,HashMap)} with local_attributes
+   * equal to <code>null</code>.
+   *
+   * @param text The string to append to the iterator.
+   */
+  protected void append (String text)
   {
-    append(text, null);
+    append (text, null);
   }  
 }