circularindex.java

使用java编写的关于通讯及串口编程所必需的类库

/*
 * CircularIndex.java
 *
 * This is a required part of the com.adaptiveview.ospso package.
 *
 * Copyright (C) 2003 AdaptiveView.com
 * 
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 * 
 * You may contact AdaptiveView.com via email at: [e-mail] 
 *
 */

package com.adaptiveview.toolkits.arrays;

/**CircularIndex is used to emulate a "circular array" (an array
 * of fixed size where the index loops back to 0). This class is used to 
 * manage <i>the array index, only</i>. It maintains <code>current</code> and <code>next</code> "pointers" for the array.
 * Every time you invoke the <code>saveNext()</code> method, <code>current</code> is set to <code>next</code> and <code>next</code>
 * is incremented (and if <code>next</code> is then <code>> maximumIndex</code>, it's set to <code>0</code>).
 * <p>Note that you should allocate 1 extra index in the array to hold the next item.
 * If, for example, you want an array to hold 4 items you should initialize it with 
 * a size of 5 (your 4 items plus the <code>next</code> (unsaved) item).
 * <p>For example:
 * <pre>
 *      String[] seasons = new String[5];
 *      CircularIndex ci = new CircularIndex(5);
 *      seasons[ci.getNext()] = "Spring"; // next=0, current undefined
 *      System.out.println(seasons[ci.getNext()]); // prints Spring
 *      ci.saveNext(); // next = 1, current = 0
 *      seasons[ci.getNext()] = "Summer"; ci.saveNext(); // next = 2, current = 1
 *      seasons[ci.getNext()] = "Fall"; ci.saveNext(); // next = 3, current = 2
 *      seasons[ci.getNext()] = "Winter"; 
 *      int[] seasons1 = ci.getLast(4); // seasons1 = {2,1,0} - only 3 saved so far
 *      ci.saveNext(); // next = 4, current = 3
 *      int[] seasons2 = ci.getLast(4); // seasons2 = {3,2,1,0}
 *      System.out.println(seasons[ci.getCurrentt()]); // prints Winter
 *      System.out.println(seasons[ci.getNext()]); // prints "" (null string)
 * </pre>
 *
 * @author  AdaptiveView.com
 */
public final class CircularIndex implements com.adaptiveview.ospso.dmi.DMI_GPL_License {
    
    private int maximumIndex = 0;
    private int current = 0;
    private int next = 0;
    private int saved = 0;
    
    /** Creates a new instance of CircularIndex
     * @param size Should be same as array size. <B>Note</B> that array
     * size should be one greater than number of items
     * you intend to store in it to allow for the
     * <CODE>next</CODE> (unsaved) item.
     * @throws IllegalArgumentException if size is less than 2 (to accomodate <CODE>current</CODE> and
     * <CODE>next</CODE>)
     */
    public CircularIndex(int size) throws IllegalArgumentException {
        if (size < 2)
            throw new IllegalArgumentException("Maximum index must be > 1.");
        this.maximumIndex = --size;
    }
    
    /** Returns the index for the <CODE>next</CODE> item.
     * @return the index for the <CODE>next</CODE> item.
     */    
    public int getNext() {
        return next;
    }
    
    /** Returns the index for the <CODE>current</CODE> item.
     * @throws IllegalStateException if no next item has been saved yet.
     * @return the index for the <CODE>current</CODE> item.
     */    
    public int getCurrent() throws IllegalStateException {
//System.out.println("getCurrent: current=" + current + "; next=" + next + "; saved=" + saved);        
        if (saved == 0)
            throw new IllegalStateException("Current index not valid until after saveNext().");
        return current;
    }
    
    /** Returns an array of <CODE>int</CODE>egers containing the
     * indexes for the last "<CODE>count</CODE>" items saved. If
     * <CODE>count</CODE> is > number of saved items then it is reduced to the
     * number of saved items.
     * @param count Number of saved item indexes to return.
     * @throws IllegalStateException if there are no saved items.
     * @throws IllegalArgumentException if <CODE>count</CODE> is greater than the array size.
     * @return an array of <CODE>int</CODE>egers containing the
     * indexes for the last "<CODE>count</CODE>" items saved.
     */    
    public int[] getLast(int count) throws IllegalStateException, IllegalArgumentException {
        if (current < 0)
            throw new IllegalStateException("Current index not valid until after saveNext().");
        if (count > maximumIndex)
            throw new IllegalArgumentException("Count cannot be greater than size - 1.");
        if (count < 1)
            throw new IllegalArgumentException("Count must be greater than 0.");
        if (count > saved)
            count = saved;
        int[] last = new int[count];
        for (int i=0, n = current; i < count; i++) {
            if (n < 0) 
                n = maximumIndex;
            last[i] = n--;
        }
        return last;
    }
    
    /** Adds 1 to the <CODE>current</CODE> and <CODE>next</CODE> "pointers"
     * (modulo the array size), essentially changing
     * <CODE>next</CODE> to <CODE>current</CODE> and pointing
     * <CODE>next</CODE> to the next index.
     */    
    public void saveNext() {
        current = next;
        if (++next > maximumIndex)
            next = 0;
        if (saved < maximumIndex)
            saved++;
//System.out.println("saveNext: current=" + current + "; next=" + next + "; saved=" + saved);        
    }
    
    /** Returns the maximum index (1 less than the <CODE>size</CODE>
     * specified in the constructor's arg1).
     * @return the maximum index (1 less than the <CODE>size</CODE>
     * specified in the constructor's arg1).
     */    
    public int getMaximumIndex() {
        return maximumIndex;
    }
    
    /** Sets <CODE>next</CODE> and <CODE>current</CODE> "pointers"
     * and the <CODE>saved</CODE> count to <CODE>0</CODE>.
     */    
    public void reset() {
        current = 0;
        next = 0;
        saved = 0;
    }
    
    /** Same as reset() but it also changes the <CODE>size</CODE>.
     * @param newMaximumIndex The new size.
     * @throws IllegalArgumentException if the new size is < 2 (see comments for the constructor).
     */    
    public void reset(int newSize) throws IllegalArgumentException {
        if (newSize < 2)
            throw new IllegalArgumentException("New maximum index must be > 0.");
        this.maximumIndex = --newSize;
        reset();
    }
    
    /** Overrides <CODE>toString()</CODE> to return the <CODE>current</CODE> and <CODE>next</CODE>
     * indexes and the <CODE>size</CODE>.
     * @return returns a string with the <CODE>current</CODE> and <CODE>next</CODE>
     * indexes and the <CODE>size</CODE>.
     */    
    public String toString() {
        StringBuffer s = new StringBuffer();
        s.append("Maximum Index: "); s.append(maximumIndex);
        s.append("; Current Index: "); s.append(current);
        s.append("; Next Index: "); s.append(next);
        return s.toString();
    }

/*
    public static void main(String[] args) {
       String[] seasons = new String[5];
       CircularIndex ci = new CircularIndex(5);
       seasons[ci.getNext()] = "Spring";                // next=0, current undefined
       System.out.println(seasons[ci.getNext()]); // prints Spring
       ci.saveNext();                                   // next = 1, current = 0
       seasons[ci.getNext()] = "Summer"; ci.saveNext(); // next = 2, current = 1
       seasons[ci.getNext()] = "Fall"; ci.saveNext();   // next = 3, current = 2
       seasons[ci.getNext()] = "Winter"; 
int[] seasons1 = ci.getLast(4); // seasons1 = {2,1,0} - only 3 saved so far
System.out.println("seasons1: length=" + seasons1.length);
       ci.saveNext();                                   // next = 4, current = 3
int[] seasons2 = ci.getLast(4); // seasons2 = {3,2,1,0}
System.out.println("seasons2: length=" + seasons2.length);
       System.out.println(seasons[ci.getCurrent()]); // prints Winter
       System.out.println(seasons[ci.getNext()]); // prints "" (null string)
       seasons[ci.getNext()] = "Green"; ci.saveNext();  // next = 0, current = 4
       seasons[ci.getNext()] = "Hot"; ci.saveNext();    // next = 1, current = 0
int[] seasons3 = ci.getLast(4); // seasons3 = {0,4,3,2}
System.out.println("seasons3: " + seasons3[0] + "," + seasons3[1] + "," + + seasons3[2] + "," + seasons3[3]);
       seasons[ci.getNext()] = "Windy"; ci.saveNext();  // next = 2, current = 1
       System.out.println("next=" + ci.getNext() + " current=" + ci.getCurrent());
       // Expected output:
       //  Spring
       //  seasons1: length=3
       //  seasons2: length=4
       //  Winter
       //  null
       //  seasons3: 0,4,3,2
       //  next=2 current=1
    }
 */    
}