buffer.scala

来自「JAVA 语言的函数式编程扩展」· SCALA 代码 · 共 261 行

/*                     __                                               *\
**     ________ ___   / /  ___     Scala API                            **
**    / __/ __// _ | / /  / _ |    (c) 2003-2007, LAMP/EPFL             **
**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
** /____/\___/_/ |_/____/_/ | |                                         **
**                          |/                                          **
\*                                                                      */

// $Id: Buffer.scala 12349 2007-07-18 07:40:06Z mcdirmid $


package scala.collection.mutable


import Predef._

/** Buffers are used to create sequences of elements incrementally by
 *  appending, prepending, or inserting new elements. It is also
 *  possible to access and modify elements in a random access fashion
 *  via the index of the element in the current sequence.
 *
 *  @author  Matthias Zenger
 *  @version 1.1, 02/03/2004
 */
@cloneable
trait Buffer[A] extends AnyRef
      with Seq[A]
      with Scriptable[Message[(Location, A)]]
      with CloneableCollection
{

  /** Append a single element to this buffer.
   *
   *  @param elem  the element to append.
   */
  def +=(elem: A): Unit

  /** Append a single element to this buffer and return
   *  the identity of the buffer.
   *
   *  @param elem  the element to append.
   */
  def +(elem: A): Buffer[A] = { this += elem; this }

  /** Prepend a single element to this buffer and return
   *  the identity of the buffer.
   *
   *  @param elem  the element to append.
   */
  def +:(elem: A): Buffer[A]

  /** Appends a number of elements provided by an iterator
   *
   *  @param iter  the iterator.
   */
  def ++=(iter: Iterator[A]) { iter foreach += }

  /** Appends a number of elements provided by an iterable object
   *  via its <code>elements</code> method.
   *
   *  @param iter  the iterable object.
   */
  def ++=(iter: Iterable[A]) { ++=(iter.elements) }

  /** Appends a number of elements in an array
   *
   *  @param src    the array
   *  @param start  the first element to append
   *  @param len    the number of elements to append           
   */
  def ++=(src: Array[A], start: Int, len: Int) {
    var i = start
    val end = i + len
    while (i < end) {
      this += src(i)
      i += 1
    }
  }
  /** return a read only alias of this buffer 
   */
  def readOnly : Seq[A]

  /** Appends a number of elements provided by an iterable object
   *  via its <code>elements</code> method. The identity of the
   *  buffer is returned.
   *
   *  @param iter     the iterable object.
   *  @return       the updated buffer.
   */
  def ++(iter: Iterable[A]): Buffer[A] = { this ++= iter; this }

  override def ++[B >: A](that : Iterable[B]) : Seq[B] = {
    val buf = new ArrayBuffer[B]
    this copyToBuffer buf
    that copyToBuffer buf
    buf
  }
   
  /** Appends a number of elements provided by an iterator
   *  via its <code>elements</code> method. The identity of the
   *  buffer is returned.
   *
   *  @param iter   the iterator
   *  @return       the updated buffer.
   */
  def ++(iter: Iterator[A]): Buffer[A] = { this ++= iter; this }

  /** Prepends a number of elements provided by an iterable object
   *  via its <code>elements</code> method. The identity of the
   *  buffer is returned.
   *
   *  @param iter  the iterable object.
   */
  def ++:(iter: Iterable[A]): Buffer[A] = {
    iter.elements.toList.reverse.foreach(e => e +: this)
    this
  }

  /** Removes a single element from this buffer, at its first occurrence.
   *  If the list does not contain that element, it is unchanged
   *
   *  @param x  the element to remove.
   */
  def -= (x: A) {
    val i = indexOf(x)
    if(i != -1) remove(i)
  }

  /** Appends a sequence of elements to this buffer.
   *
   *  @param elems  the elements to append.
   */
  def append(elems: A*) { this ++= elems }

  /** Appends a number of elements provided by an iterable object
   *  via its <code>elements</code> method.
   *
   *  @param iter  the iterable object.
   */
  def appendAll(iter: Iterable[A]) { this ++= iter }

  /** Prepend an element to this list.
   *
   *  @param elem  the element to prepend.
   */
  def prepend(elems: A*) { elems ++: this }

  /** Prepends a number of elements provided by an iterable object
   *  via its <code>elements</code> method. The identity of the
   *  buffer is returned.
   *
   *  @param iter  the iterable object.
   */
  def prependAll(iter: Iterable[A]) { iter ++: this }

  /** Inserts new elements at the index <code>n</code>. Opposed to method
   *  <code>update</code>, this method will not replace an element with a
   *  one. Instead, it will insert the new elements at index <code>n</code>.
   *
   *  @param n      the index where a new element will be inserted.
   *  @param elems  the new elements to insert.
   */
  def insert(n: Int, elems: A*) { insertAll(n, elems) }

  /** Inserts new elements at the index <code>n</code>. Opposed to method
   *  <code>update</code>, this method will not replace an element with a
   *  one. Instead, it will insert a new element at index <code>n</code>.
   *
   *  @param n     the index where a new element will be inserted.
   *  @param iter    the iterable object providing all elements to insert.
   */
  def insertAll(n: Int, iter: Iterable[A]): Unit

  /** Replace element at index <code>n</code> with the new element
   *  <code>newelem</code>.
   *
   *  @param n       the index of the element to replace.
   *  @param newelem the new element.
   */
  def update(n: Int, newelem: A): Unit

  /** Removes the element on a given index position.
   *
   *  @param n  the index which refers to the element to delete.
   */
  def remove(n: Int): A

  /** Removes the first <code>n</code> elements.
   *
   *  @param n  the number of elements to remove from the beginning
   *            of this buffer.
   */
  def trimStart(n: Int) {
    var i = n
    while (i > 0) { remove(0); i -= 1 }
  }

  /** Removes the last <code>n</code> elements.
   *
   *  @param n  the number of elements to remove from the end
   *            of this buffer.
   */
  def trimEnd(n: Int) {
    var i = n
    while (i > 0) { remove(length - 1); i -= 1 }
  }

  /** Clears the buffer contents.
   */
  def clear(): Unit

  /** Send a message to this scriptable object.
   *
   *  @param cmd  the message to send.
   */
  def <<(cmd: Message[(Location, A)]) {
    cmd match {
      case Include((l, elem)) => l match {
        case Start => prepend(elem)
        case End => append(elem)
        case Index(n) => insert(n, elem)
        case _ => throw new UnsupportedOperationException("message " + cmd + " not understood")
      }
      case Update((l, elem)) => l match {
        case Start => update(0, elem)
        case End => update(length - 1, elem)
        case Index(n) => update(n, elem)
        case _ => throw new UnsupportedOperationException("message " + cmd + " not understood")
      }
      case Remove((l, _)) => l match {
        case Start => remove(0)
        case End => remove(length - 1)
        case Index(n) => remove(n)
        case _ => throw new UnsupportedOperationException("message " + cmd + " not understood")
      }
      case Reset() => clear
      case s: Script[_] => s.elements foreach <<
      case _ => throw new UnsupportedOperationException("message " + cmd + " not understood")
    }
  }

  /** Return a clone of this buffer.
   *
   *  @return a buffer with the same elements.
   */
  override def clone(): Buffer[A] = super.clone().asInstanceOf[Buffer[A]]

  /** The hashCode method always yields an error, since it is not
   *  safe to use buffers as keys in hash tables.
   *
   *  @return never.
   */
  override def hashCode(): Int =
    throw new UnsupportedOperationException("unsuitable as hash key")

  /** Defines the prefix of the string representation.
   */
  override protected def stringPrefix: String = "Buffer"
    
}