[kaffe] CVS kaffe (dalibor): Resynced with GNU Classpath

[Kaffe CVS]

PatchSet 4196 
Date: 2003/12/04 03:27:47
Author: dalibor
Branch: HEAD
Tag: (none) 
Log:
Resynced with GNU Classpath

2003-12-04  Dalibor Topic <robilad at kaffe.org>

        * libraries/javalib/java/text/FormatCharacterIterator.java:
        Resynced with GNU Classpath.

        2003-11-23  Guilhem Lavaux <guilhem at kaffe.org>

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

Members: 
	ChangeLog:1.1787->1.1788 
	libraries/javalib/java/text/FormatCharacterIterator.java:1.3->1.4 

Index: kaffe/ChangeLog
diff -u kaffe/ChangeLog:1.1787 kaffe/ChangeLog:1.1788
--- kaffe/ChangeLog:1.1787	Thu Dec  4 03:14:36 2003
+++ kaffe/ChangeLog	Thu Dec  4 03:27:47 2003
@@ -1,5 +1,15 @@
 2003-12-04  Dalibor Topic <robilad at kaffe.org>
 
+	* libraries/javalib/java/text/FormatCharacterIterator.java:
+	Resynced with GNU Classpath.
+
+	2003-11-23  Guilhem Lavaux <guilhem at kaffe.org>
+
+	* java/text/FormatCharacterIterator.java: Documented the class and
+        its methods.
+
+2003-12-04  Dalibor Topic <robilad at kaffe.org>
+
 	* libraries/javalib/java/text/Format.java:
         Resynced with GNU Classpath by removing empty comment.
 
Index: kaffe/libraries/javalib/java/text/FormatCharacterIterator.java
diff -u kaffe/libraries/javalib/java/text/FormatCharacterIterator.java:1.3 kaffe/libraries/javalib/java/text/FormatCharacterIterator.java:1.4
--- kaffe/libraries/javalib/java/text/FormatCharacterIterator.java:1.3	Sun Nov 23 20:41:05 2003
+++ kaffe/libraries/javalib/java/text/FormatCharacterIterator.java	Thu Dec  4 03:27:49 2003
@@ -43,6 +43,18 @@
 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 at kaffe.org>
+ * @date November 22, 2003
+ */
 class FormatCharacterIterator implements AttributedCharacterIterator
 {
   private String formattedString;
@@ -51,6 +63,11 @@
   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,6 +75,21 @@
     attributes = new HashMap[0];
   }
 
+  /**
+   * 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;
@@ -65,11 +97,11 @@
     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)
@@ -192,10 +224,10 @@
   }
   
   /*
-   * ---------------------------------
-   * CharacterIterator methods
-   * ---------------------------------
+   * The following methods are inherited from CharacterIterator and thus
+   * are already documented.
    */
+
   public char current()
   {
     return formattedString.charAt (charIndex);
@@ -284,6 +316,15 @@
       return formattedString.charAt (charIndex);
   }
 
+  /**
+   * 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();
@@ -349,6 +390,13 @@
     
   }
 
+  /**
+   * 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();
@@ -383,6 +431,15 @@
     ranges = new_ranges;
   }
 
+  /**
+   * 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];
@@ -398,6 +455,13 @@
     attributes = new_attributes;
   }  
 
+  /**
+   * 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);