home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1998 July & August / Pcwk78a98.iso / Internet / Javadraw / DATA.Z / StringCharacterIterator.java < prev    next >
Text File  |  1997-08-30  |  8KB  |  295 lines
  1. /*
  2.  * @(#)StringCharacterIterator.java    1.8 97/02/06
  3.  *
  4.  * (C) Copyright Taligent, Inc. 1996 - All Rights Reserved
  5.  * (C) Copyright IBM Corp. 1996 - All Rights Reserved
  6.  *
  7.  * Portions copyright (c) 1996 Sun Microsystems, Inc. All Rights Reserved.
  8.  *
  9.  *   The original version of this source code and documentation is copyrighted
  10.  * and owned by Taligent, Inc., a wholly-owned subsidiary of IBM. These
  11.  * materials are provided under terms of a License Agreement between Taligent
  12.  * and Sun. This technology is protected by multiple US and International
  13.  * patents. This notice and attribution to Taligent may not be removed.
  14.  *   Taligent is a registered trademark of Taligent, Inc.
  15.  *
  16.  * Permission to use, copy, modify, and distribute this software
  17.  * and its documentation for NON-COMMERCIAL purposes and without
  18.  * fee is hereby granted provided that this copyright notice
  19.  * appears in all copies. Please refer to the file "copyright.html"
  20.  * for further important copyright and licensing information.
  21.  *
  22.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF
  23.  * THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
  24.  * TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
  25.  * PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR
  26.  * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
  27.  * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
  28.  *
  29.  */
  30.  
  31. package java.text;
  32.  
  33. /**
  34.  * <code>StringCharacterIterator</code> implements the
  35.  * <code>CharacterIterater</code> protocol for a <code>String</code>.
  36.  * The <code>StringCharacterIterator</code> class iterates over the
  37.  * entire <code>String</code>.
  38.  *
  39.  * <P>
  40.  * <strong>Examples</strong>:
  41.  *
  42.  * <P>
  43.  * Traverse the text from start to finish
  44.  * <blockquote>
  45.  * <pre>
  46.  * public void traverseForward(CharacterIterator iter) {
  47.  *     for (char c = iter.first(); c != CharacterIterator.DONE; c = iter.next()) {
  48.  *         processChar(c);
  49.  *     }
  50.  * }
  51.  * </pre>
  52.  * </blockquote>
  53.  * Traverse the text backwards, from end to start
  54.  * <blockquote>
  55.  * <pre>
  56.  * public void traverseBackward(CharacterIterator iter) {
  57.  *     for (char c = iter.last(); c != CharacterIterator.DONE; c = iter.prev()) {
  58.  *         processChar(c);
  59.  *     }
  60.  * }
  61.  * </pre>
  62.  * </blockquote>
  63.  *
  64.  * Traverse both forward and backward from a given position in the text.
  65.  * <blockquote>
  66.  * <pre>
  67.  * public void traverseOut(CharacterIterator iter, int pos) {
  68.  *     for (char c = iter.setIndex(pos);
  69.  *          c != CharacterIterator.DONE && notBoundary(c);
  70.  *          c = iter.next()) {}
  71.  *     int end = iter.getIndex();
  72.  *     for (char c = iter.setIndex(pos);
  73.  *          c != CharacterIterator.DONE && notBoundary(c);
  74.  *          c = iter.prev()) {}
  75.  *     int start = iter.getIndex();
  76.  *     processSection(iter.getText.subString(start,end);
  77.  * }
  78.  * </pre>
  79.  * </blockquote>
  80.  */
  81.  
  82. public final class StringCharacterIterator implements CharacterIterator
  83. {
  84.     private String text;
  85.     private int begin;
  86.     private int end;
  87.     private int pos;
  88.  
  89.     /**
  90.      * Construct an iterator with an initial index of 0.
  91.      */
  92.     public StringCharacterIterator(String text)
  93.     {
  94.         this(text, 0);
  95.     }
  96.  
  97.     /**
  98.      * Construct an iterator with the specified initial index.
  99.      *
  100.      * @param  text   The String to be iterated over
  101.      * @param  pos    Initial iterator position
  102.      */
  103.     public StringCharacterIterator(String text, int pos)
  104.     {
  105.     this(text, 0, text.length(), pos);
  106.     }
  107.  
  108.     /**
  109.      * Construct an iterator over the given range of the given string, with the
  110.      * index set at the specified position.
  111.      *
  112.      * @param  text   The String to be iterated over
  113.      * @param  begin  Index of the first character
  114.      * @param  end    Index of the character following the last character
  115.      * @param  pos    Initial iterator position
  116.      */
  117.     public StringCharacterIterator(String text, int begin, int end, int pos) {
  118.         if (text == null)
  119.             throw new NullPointerException();
  120.         this.text = text;
  121.  
  122.     if (begin < 0 || begin > end)
  123.         throw new IllegalArgumentException("Invalid substring range");
  124.  
  125.     if (pos < begin || pos > end)
  126.         throw new IllegalArgumentException("Invalid position");
  127.  
  128.     this.begin = begin;
  129.     this.end = end;
  130.     this.pos = pos;
  131.     }
  132.  
  133.  
  134.     /**
  135.      * Set the position to getBeginIndex() and return the character at that
  136.      * position.
  137.      */
  138.     public char first()
  139.     {
  140.         pos = begin;
  141.         return text.charAt(pos);
  142.     }
  143.  
  144.     /**
  145.      * Set the position to getEndIndex() and return the character at that
  146.      * position.
  147.      */
  148.     public char last()
  149.     {
  150.         pos = end - 1;
  151.         return text.charAt(pos);
  152.     }
  153.  
  154.     /**
  155.      * Set the position to specified position in the text and return that
  156.      * character.
  157.      */
  158.     public char setIndex(int p)
  159.     {
  160.     if (p < begin || p >= end)
  161.             throw new IllegalArgumentException("Invalid index");
  162.         pos = p;
  163.         return text.charAt(p);
  164.     }
  165.  
  166.     /**
  167.      * Get the character at the current position (as returned by getIndex()).
  168.      * @return the character at the current position or DONE if the current
  169.      * position is off the end of the text.
  170.      */
  171.     public char current()
  172.     {
  173.         if (pos >= begin && pos < end) {
  174.             return text.charAt(pos);
  175.         }
  176.         else {
  177.             return DONE;
  178.         }
  179.     }
  180.  
  181.     /**
  182.      * Increment the iterator's index by one and return the character
  183.      * at the new index.  If the resulting index is greater or equal
  184.      * to getEndIndex(), the current index is reset to getEndIndex() and
  185.      * a value of DONE is returned.
  186.      * @return the character at the new position or DONE if the current
  187.      * position is off the end of the text.
  188.      */
  189.     public char next()
  190.     {
  191.         if (++pos < end) {
  192.             return text.charAt(pos);
  193.         }
  194.         else {
  195.             return DONE;
  196.         }
  197.     }
  198.  
  199.     /**
  200.      * Decrement the iterator's index by one and return the character
  201.      * at the new index.  If the resulting index is
  202.      * less than getBeginIndex(), the current index is reset to getBeginIndex()
  203.      * and a value of DONE is returned.
  204.      * @return the character at the new position or DONE if the current
  205.      * position is off the end of the text.
  206.      */
  207.     public char previous()
  208.     {
  209.         if (pos > begin) {
  210.             return text.charAt(--pos);
  211.         }
  212.         else {
  213.             return DONE;
  214.         }
  215.     }
  216.  
  217.     /**
  218.      * Return the start index of the text.
  219.      * @return the index at which the text begins.
  220.      */
  221.     public int getBeginIndex()
  222.     {
  223.         return begin;
  224.     }
  225.  
  226.     /**
  227.      * Return the end index of the text.  This index is the index of the
  228.      * first character following the end of the text.
  229.      * @return the index at which the text end.
  230.      */
  231.     public int getEndIndex()
  232.     {
  233.         return end;
  234.     }
  235.  
  236.     /**
  237.      * Return the current index.
  238.      * @return the current index.
  239.      */
  240.     public int getIndex()
  241.     {
  242.         return pos;
  243.     }
  244.  
  245.     /**
  246.      * Compares the equality of two StringCharacterIterator objects.
  247.      * @param obj the StringCharacterIterator object to be compared with.
  248.      * @return true if the given obj is the same as this
  249.      * StringCharacterIterator object; false otherwise.
  250.      */
  251.     public boolean equals(Object obj)
  252.     {
  253.         if (this == obj)
  254.             return true;
  255.         if (!(obj instanceof StringCharacterIterator))
  256.             return false;
  257.  
  258.         StringCharacterIterator that = (StringCharacterIterator) obj;
  259.  
  260.         if (hashCode() != that.hashCode())
  261.             return false;
  262.         if (!text.equals(that.text))
  263.             return false;
  264.         if (pos != that.pos || begin != that.begin || end != that.end)
  265.             return false;
  266.         return true;
  267.     }
  268.  
  269.     /**
  270.      * Compute a hashcode for this enumeration
  271.      * @return A hash code
  272.      */
  273.     public int hashCode()
  274.     {
  275.         return text.hashCode() ^ pos ^ begin ^ end;
  276.     }
  277.  
  278.     /**
  279.      * Create a copy of this boundary
  280.      * @return A copy of this
  281.      */
  282.     public Object clone()
  283.     {
  284.         try {
  285.             StringCharacterIterator other
  286.             = (StringCharacterIterator) super.clone();
  287.             return other;
  288.         }
  289.         catch (CloneNotSupportedException e) {
  290.             throw new InternalError();
  291.         }
  292.     }
  293.  
  294. }
  295.