Add Stack.scala and ReusableBuilder.scala to stdlib

tests/pos-special/stdlib/collection/mutable/ReusableBuilder.scala

@@ -0,0 +1,56 @@
+/*
+ * Scala (https://www.scala-lang.org)
+ *
+ * Copyright EPFL and Lightbend, Inc.
+ *
+ * Licensed under Apache License 2.0
+ * (http://www.apache.org/licenses/LICENSE-2.0).
+ *
+ * See the NOTICE file distributed with this work for
+ * additional information regarding copyright ownership.
+ */
+
+package scala
+package collection
+package mutable
+
+import language.experimental.captureChecking
+
+/** `ReusableBuilder` is a marker trait that indicates that a `Builder`
+ * can be reused to build more than one instance of a collection. In
+ * particular, calling `result()` followed by `clear()` will produce a
+ * collection and reset the builder to begin building a new collection
+ * of the same type.
+ *
+ * In general no method other than `clear()` may be called after `result()`.
+ * It is up to subclasses to implement and to document other allowed sequences
+ * of operations (e.g. calling other methods after `result()` in order to obtain
+ * different snapshots of a collection under construction).
+ *
+ * @tparam Elem the type of elements that get added to the builder.
+ * @tparam To the type of collection that it produced.
+ *
+ * @define multipleResults
+ *
+ * This Builder can be reused after calling `result()` without an
+ * intermediate call to `clear()` in order to build multiple related results.
+ */
+trait ReusableBuilder[-Elem, +To] extends Builder[Elem, To] {
+ /** Clears the contents of this builder.
+ * After execution of this method, the builder will contain no elements.
+ *
+ * If executed immediately after a call to `result()`, this allows a new
+ * instance of the same type of collection to be built.
+ */
+ override def clear(): Unit // Note: overriding for Scaladoc only!
+
+ /** Produces a collection from the added elements.
+ *
+ * After a call to `result`, the behavior of all other methods is undefined
+ * save for `clear()`. If `clear()` is called, then the builder is reset and
+ * may be used to build another instance.
+ *
+ * @return a collection containing the elements added to this builder.
+ */
+ override def result(): To // Note: overriding for Scaladoc only!
+}

tests/pos-special/stdlib/collection/mutable/Stack.scala

@@ -0,0 +1,144 @@
+/*
+ * Scala (https://www.scala-lang.org)
+ *
+ * Copyright EPFL and Lightbend, Inc.
+ *
+ * Licensed under Apache License 2.0
+ * (http://www.apache.org/licenses/LICENSE-2.0).
+ *
+ * See the NOTICE file distributed with this work for
+ * additional information regarding copyright ownership.
+ */
+
+package scala.collection.mutable
+
+import scala.annotation.{migration, nowarn}
+import scala.collection.generic.DefaultSerializable
+import scala.collection.{IterableFactoryDefaults, IterableOnce, SeqFactory, StrictOptimizedSeqFactory, StrictOptimizedSeqOps}
+
+import language.experimental.captureChecking
+
+/** A stack implements a data structure which allows to store and retrieve
+ * objects in a last-in-first-out (LIFO) fashion.
+ *
+ * Note that operations which consume and produce iterables preserve order,
+ * rather than reversing it (as would be expected from building a new stack
+ * by pushing an element at a time).
+ *
+ * @tparam A type of the elements contained in this stack.
+ *
+ * @define Coll `Stack`
+ * @define coll stack
+ * @define orderDependent
+ * @define orderDependentFold
+ * @define mayNotTerminateInf
+ * @define willNotTerminateInf
+ */
+@migration("Stack is now based on an ArrayDeque instead of a linked list", "2.13.0")
+class Stack[sealed A] protected (array: Array[AnyRef], start: Int, end: Int)
+ extends ArrayDeque[A](array, start, end)
+ with IndexedSeqOps[A, Stack, Stack[A]]
+ with StrictOptimizedSeqOps[A, Stack, Stack[A]]
+ with IterableFactoryDefaults[A, Stack]
+ with ArrayDequeOps[A, Stack, Stack[A]]
+ with Cloneable[Stack[A]]
+ with DefaultSerializable {
+
+ def this(initialSize: Int = ArrayDeque.DefaultInitialSize) =
+ this(ArrayDeque.alloc(initialSize), start = 0, end = 0)
+
+ override def iterableFactory: SeqFactory[Stack] = Stack
+
+ @nowarn("""cat=deprecation&origin=scala\.collection\.Iterable\.stringPrefix""")
+ override protected[this] def stringPrefix = "Stack"
+
+ /**
+ * Add elements to the top of this stack
+ *
+ * @param elem
+ * @return
+ */
+ def push(elem: A): this.type = prepend(elem)
+
+ /** Push two or more elements onto the stack. The last element
+ * of the sequence will be on top of the new stack.
+ *
+ * @param elems the element sequence.
+ * @return the stack with the new elements on top.
+ */
+ def push(elem1: A, elem2: A, elems: A*): this.type = {
+ val k = elems.knownSize
+ ensureSize(length + (if(k >= 0) k + 2 else 3))
+ prepend(elem1).prepend(elem2).pushAll(elems)
+ }
+
+ /** Push all elements in the given iterable object onto the stack. The
+ * last element in the iterable object will be on top of the new stack.
+ *
+ * @param elems the iterable object.
+ * @return the stack with the new elements on top.
+ */
+ def pushAll(elems: scala.collection.IterableOnce[A]): this.type =
+ prependAll(elems match {
+ case it: scala.collection.Seq[A] => it.view.reverse
+ case it => IndexedSeq.from(it).view.reverse
+ })
+
+ /**
+ * Removes the top element from this stack and return it
+ *
+ * @return
+ * @throws NoSuchElementException when stack is empty
+ */
+ def pop(): A = removeHead()
+
+ /**
+ * Pop all elements from this stack and return it
+ *
+ * @return The removed elements
+ */
+ def popAll(): scala.collection.Seq[A] = removeAll()
+
+ /**
+ * Returns and removes all elements from the top of this stack which satisfy the given predicate
+ *
+ * @param f the predicate used for choosing elements
+ * @return The removed elements
+ */
+ def popWhile(f: A => Boolean): scala.collection.Seq[A] = removeHeadWhile(f)
+
+ /** Returns the top element of the stack. This method will not remove
+ * the element from the stack. An error is signaled if there is no
+ * element on the stack.
+ *
+ * @throws NoSuchElementException
+ * @return the top element
+ */
+ @`inline` final def top: A = head
+
+ override protected def klone(): Stack[A] = {
+ val bf = newSpecificBuilder
+ bf ++= this
+ bf.result()
+ }
+
+ override protected def ofArray(array: Array[AnyRef], end: Int): Stack[A] =
+ new Stack(array, start = 0, end)
+
+}
+
+/**
+ * $factoryInfo
+ * @define coll stack
+ * @define Coll `Stack`
+ */
+@SerialVersionUID(3L)
+object Stack extends StrictOptimizedSeqFactory[Stack] {
+
+ def from[sealed A](source: IterableOnce[A]): Stack[A] = empty ++= source
+
+ def empty[sealed A]: Stack[A] = new Stack
+
+ def newBuilder[sealed A]: Builder[A, Stack[A]] = new GrowableBuilder[A, Stack[A]](empty)
+
+}