/* 
    P/P   *  Method: com.dmdirc.util.RollingList__static_init
          */
     1  /*
     2   * Copyright (c) 2006-2009 Chris Smith, Shane Mc Cormack, Gregory Holmes
     3   *
     4   * Permission is hereby granted, free of charge, to any person obtaining a copy
     5   * of this software and associated documentation files (the "Software"), to deal
     6   * in the Software without restriction, including without limitation the rights
     7   * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
     8   * copies of the Software, and to permit persons to whom the Software is
     9   * furnished to do so, subject to the following conditions:
    10   *
    11   * The above copyright notice and this permission notice shall be included in
    12   * all copies or substantial portions of the Software.
    13   *
    14   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    15   * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    16   * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    17   * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    18   * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    19   * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
    20   * SOFTWARE.
    21   */
    22  
    23  package com.dmdirc.util;
    24  
    25  import java.util.ArrayList;
    26  import java.util.List;
    27  
    28  /**
    29   * Implements a "rolling list". A rolling list has a maximum capacity, and
    30   * removes the oldest elements from the list to maintain this capacity.
    31   * 
    32   * @param <T> The type if items that this list contains 
    33   * @author chris
    34   */
    35  public class RollingList<T> {
    36     
    37      /** The items in this rolling list. */
    38      private final List<T> items = new ArrayList<T>();
    39      
    40      /** The maximum capacity of this list. */
    41      private final int capacity;
    42      
    43      /** This list's position pointer. */
    44      private int position = 0;
    45      
    46      /** Whether or not to add a fake empty item to the end of this list. */
    47      private boolean addEmpty;
    48      /** The "empty" item to be added. */
    49      private T empty;
    50      
    51      /**
    52       * Creates a new RollingList of the specified capacity.
    53       * 
    54       * @param capacity The capacity of this list.
    55       */
             /* 
    P/P       *  Method: void com.dmdirc.util.RollingList(int)
              * 
              *  Postconditions:
              *    this.addEmpty == 0
              *    this.position == 0
              *    this.capacity == capacity
              *    init'ed(this.capacity)
              *    this.items == &amp;new ArrayList(RollingList#1)
              *    new ArrayList(RollingList#1) num objects == 1
              */
    56      public RollingList(final int capacity) {
    57          this.capacity = capacity;
    58          this.addEmpty = false;
    59      }
    60  
    61      /**
    62       * Creates a new RollingList of the specified capacity, with the specified
    63       * "empty" element appended to the end.
    64       * 
    65       * @param capacity The capacity of this list.
    66       * @param empty The "empty" element to be added
    67       */    
             /* 
    P/P       *  Method: void com.dmdirc.util.RollingList(int, Object)
              * 
              *  Postconditions:
              *    this.addEmpty == 1
              *    new ArrayList(RollingList#1) num objects == 1
              *    this.capacity == capacity
              *    init'ed(this.capacity)
              *    this.empty == empty
              *    init'ed(this.empty)
              *    this.items == &amp;new ArrayList(RollingList#1)
              *    this.position == 0
              */
    68      public RollingList(final int capacity, final T empty) {
    69          this.capacity = capacity;
    70          this.addEmpty = true;
    71          this.empty = empty;
    72      }
    73  
    74      /**
    75       * Removes the specified element from this list.
    76       * 
    77       * @param o The object to be removed from the list.
    78       * @return True if the list contained the specified element, false otherwise.
    79       */
    80      public boolean remove(final Object o) {
                 /* 
    P/P           *  Method: bool remove(Object)
                  * 
                  *  Preconditions:
                  *    this.items != null
                  * 
                  *  Postconditions:
                  *    init'ed(return_value)
                  */
    81          return items.remove(o);
    82      }
    83  
    84      /**
    85       * Determines if this list is currently empty.
    86       * 
    87       * @return True if the list is empty, false otherwise.
    88       */
    89      public boolean isEmpty() {
                 /* 
    P/P           *  Method: bool isEmpty()
                  * 
                  *  Preconditions:
                  *    this.items != null
                  * 
                  *  Postconditions:
                  *    init'ed(return_value)
                  */
    90          return items.isEmpty();
    91      }
    92  
    93      /**
    94       * Retrieves the item at the specified index in this list.
    95       * 
    96       * @param index The index to look up
    97       * @return The item at the specified index
    98       */
    99      public T get(final int index) {
                 /* 
    P/P           *  Method: Object get(int)
                  * 
                  *  Preconditions:
                  *    this.items != null
                  * 
                  *  Postconditions:
                  *    init'ed(return_value)
                  */
   100          return items.get(index);
   101      }
   102  
   103      /**
   104       * Determines if this list contains the specified object.
   105       * 
   106       * @param o The object to be checked
   107       * @return True if this list contains the item, false otherwise.
   108       */
   109      public boolean contains(final Object o) {
                 /* 
    P/P           *  Method: bool contains(Object)
                  * 
                  *  Preconditions:
                  *    this.items != null
                  * 
                  *  Postconditions:
                  *    init'ed(return_value)
                  */
   110          return items.contains(o);
   111      }
   112  
   113      /**
   114       * Clears all items from this list.
   115       */
   116      public void clear() {
                 /* 
    P/P           *  Method: void clear()
                  * 
                  *  Preconditions:
                  *    this.items != null
                  */
   117          items.clear();
   118      }  
   119      
   120      /**
   121       * Adds the specified item to this list. If the list has reached its
   122       * maximum capacity, this method will remove elements from the start of the
   123       * list until there is sufficient room for the new element.
   124       * 
   125       * @param e The element to be added to the list.
   126       * @return True
   127       */
   128      public boolean add(T e) {
                 /* 
    P/P           *  Method: bool add(Object)
                  * 
                  *  Preconditions:
                  *    this.capacity >= -231+1
                  *    this.items != null
                  *    (soft) this.position >= -231+1
                  * 
                  *  Postconditions:
                  *    init'ed(return_value)
                  *    init'ed(this.position)
                  *    this.position - old this.position in {-6_442_450_943..0}
                  */
   129          while (items.size() > capacity - 1) {
   130              items.remove(0);
   131              position--;
   132          }
   133          
   134          return items.add(e);
   135      }
   136      
   137      /**
   138       * Retrieves the current position within the list.
   139       * 
   140       * @return This list's positional pointer
   141       */
   142      public int getPosition() {
                 /* 
    P/P           *  Method: int getPosition()
                  * 
                  *  Preconditions:
                  *    init'ed(this.position)
                  * 
                  *  Postconditions:
                  *    return_value == this.position
                  *    init'ed(return_value)
                  */
   143          return position;
   144      }
   145  
   146      /**
   147       * Sets the positional pointer of this list.
   148       * 
   149       * @param position The new position
   150       */
   151      public void setPosition(int position) {
                 /* 
    P/P           *  Method: void setPosition(int)
                  * 
                  *  Postconditions:
                  *    this.position == position
                  *    init'ed(this.position)
                  */
   152          this.position = position;
   153      }    
   154      
   155      /**
   156       * Determines if there is an element after the positional pointer of the list.
   157       * 
   158       * @return True if there is an element, false otherwise.
   159       */
   160      public boolean hasNext() {
                 /* 
    P/P           *  Method: bool hasNext()
                  * 
                  *  Preconditions:
                  *    this.items != null
                  *    init'ed(this.position)
                  *    (soft) init'ed(this.addEmpty)
                  * 
                  *  Postconditions:
                  *    init'ed(return_value)
                  */
   161          return (items.size() > position + 1) || ((items.size() > position) && addEmpty);
   162      }
   163      
   164      /**
   165       * Retrieves the element after the positional pointer of the list.
   166       * 
   167       * @return The next element in the list
   168       */
   169      public T getNext() {
                 /* 
    P/P           *  Method: Object getNext()
                  * 
                  *  Preconditions:
                  *    this.position <= 232-2
                  *    this.items != null
                  *    (soft) init'ed(this.addEmpty)
                  *    (soft) init'ed(this.empty)
                  * 
                  *  Postconditions:
                  *    init'ed(return_value)
                  *    this.position == old this.position + 1
                  *    this.position >= -231+1
                  * 
                  *  Test Vectors:
                  *    this.addEmpty: {1}, {0}
                  */
   170          if (items.size() > position + 1 || !addEmpty) {
   171              return get(++position);
   172          } else {
   173              position++;
   174              return empty;
   175          }
   176      }
   177      
   178      /**
   179       * Determines if there is an element befpre the positional pointer of the list.
   180       * 
   181       * @return True if there is an element, false otherwise.
   182       */    
   183      public boolean hasPrevious() {
                 /* 
    P/P           *  Method: bool hasPrevious()
                  * 
                  *  Preconditions:
                  *    init'ed(this.position)
                  * 
                  *  Postconditions:
                  *    init'ed(return_value)
                  */
   184          return 0 < position;
   185      }
   186      
   187      /**
   188       * Retrieves the element before the positional pointer of the list.
   189       * 
   190       * @return The previous element in the list
   191       */    
   192      public T getPrevious() {
                 /* 
    P/P           *  Method: Object getPrevious()
                  * 
                  *  Preconditions:
                  *    this.position >= -231+1
                  *    this.items != null
                  * 
                  *  Postconditions:
                  *    init'ed(return_value)
                  *    this.position == old this.position - 1
                  *    this.position <= 232-2
                  */
   193          return get(--position);
   194      }    
   195      
   196      /**
   197       * Sets the positional pointer of this list to the end.
   198       */
   199      public void seekToEnd() {
                 /* 
    P/P           *  Method: void seekToEnd()
                  * 
                  *  Preconditions:
                  *    this.items != null
                  * 
                  *  Postconditions:
                  *    init'ed(this.position)
                  */
   200          position = items.size();
   201      }
   202      
   203      /**
   204       * Sets the positional pointer of this list to the start.
   205       */
   206      public void seekToStart() {
                 /* 
    P/P           *  Method: void seekToStart()
                  * 
                  *  Postconditions:
                  *    this.position == 0
                  */
   207          position = 0;
   208      }
   209      
   210      /**
   211       * Retrieves a list of items that this rolling list contains.
   212       * 
   213       * @return A list of items in this rolling list.
   214       */
   215      public List<T> getList() {
                 /* 
    P/P           *  Method: List getList()
                  * 
                  *  Postconditions:
                  *    return_value == &amp;new ArrayList(getList#1)
                  *    new ArrayList(getList#1) num objects == 1
                  */
   216          return new ArrayList<T>(items);
   217      }
   218  
   219  }