Jun 252013
 

The ‘RX’ in front of ‘List’ – R for Roycat, to differentiate from any other List, and X for extended, because I already had an RList interface. I’ll get the abstract class and a concrete class posted in the days to come.

 /**
  * A revised, updated, and extended RList interface
  * @author Steven Bolin - June 2013 - All rights reserved.
  */
 interface RXList {

  /**
   * Adds an element to the end of the list and 
   * returns the resulting list
   * @param mixed $element The element to add
   * @return mixed The resulting list
   */
  public function add($element);

  /**
   * Adds $element at the index specified by $index and returns the list
   * @param int $index The index at which to add $element
   * @param mixed The element to add at $index
   * @return mixed The resulting list
   */
  public function addAt($index, $element);

  /**
   * Adds an element to the beginning of the list and 
   * returns the resulting list
   * @param mixed $element The element to add
   * @return mixed The resulting list
   */
  public function addFirst($element);

  /**
   * Adds an element to the end of the list and 
   * returns the resulting list
   * @param mixed $element The element to add
   * @return mixed The resulting list
   */
  public function addLast($element);

  /**
   * Removes all of the elements from this list and returns
   * the resulting empty list
   * @return mixed The resulting (empty) list
   */
  public function clear();

  /**
   * Returns true if this list contains the specified element, false otherwise.
   * @param mixed $element - The element to search for.
   * @return boolean - Returns true if this list contains the specified element, 
   * false otherwise.
   */
  public function contains($element);

  /**
   * Searches the array for a given value and returns the corresponding key 
   * if successful
   * @param mixed $element The element to find
   * @return mixed Returns the index of the first occurance of $element, or
   * null if $element not found
   */
  public function findFirst($element);

  /**
   * Returns the element at the specified position in this list.
   * @param int $index - The index of the element to return.
   * @return mixed - Returns the element at the specified position in this list
   * or null if the index is out of bounds.
   * @require Index must be within bounds
   */
  public function get($index);

  /**
   * Returns the index of the first occurrence of the specified element in this 
   * list, or null if this list does not contain the element.
   * @param mixed $element - The element to get the index of.
   * @return int - Returns the index of the first occurrence of the specified 
   * element in this list, or null if this list does not contain the element.
   */
  public function indexOf($element);

  /**
   * Returns true if this list contains no elements, false otherwise.
   * @return boolean - Returns true if this list contains no elements, false 
   * otherwise.
   */
  public function isEmpty();

  /**
   * Returns an iterator over the elements in this list in proper sequence.
   * @return \RListIterator - Returns an iterator over the elements in this list 
   * in proper sequence.
   */
  public function iterator();

  /**
   * Removes the first occurrence of the specified element from this list, if 
   * it is present
   * @param mixed $element - The element to remove the first occurance of.
   * @return mixed Returns the resulting list
   */
  public function remove($element);

  /**
   * Removes the element at the index given by $index and returns the
   * resulting List. Alias for removeIndex($index)
   * @param int $index The index of the element to remove
   * @return mixed Returns the element which is being removed or null if $index 
   * is out of bounds
   */
  public function removeAt($index);

  /**
   * Removes duplicate values from the array and returns the resulting array
   * @return mixed Returns the resulting list
   */
  public function removeDuplicates();

  /**
   * Removes and returns the first element in the list.
   * @return The element being removed, or null if the list is empty.
   */
  public function removeFirst();

  /**
   * Removes the element at the specified position in this list. 
   * Alias for removeAt($index).
   * @param int $index - the index of the element to remove.
   * @return The element being removed, or null if $index is out of bounds.
   */
  public function removeIndex($index);

  /**
   * Removes and returns the last element in the list
   * @return The element which is being removed, or null if the list is empty.
   */
  public function removeLast();

  /**
   * Replaces the element at the specified position in this list with the 
   * specified element
   * @param int $index - The index at which to place element
   * @param mixed $element - The element to place at index
   */
  public function set($index, $element);

  /**
   * Returns the number of elements in the array
   * @return Returns the number of elements in the array
   */
  public function size();

  /**
   * Returns an array containing all of the elements in this list in proper 
   * sequence (from first to last element).
   * @return mixed array - Returns an array containing all of the elements in 
   * this list in proper sequence (from first to last element).
   */
  public function toArray();

  /**
   * Returns a string representation of the List.
   * @return string - Returns a string representation of the List.
   */
  public function toString();
} // End of interface
 Posted by at 9:39 am